-
Notifications
You must be signed in to change notification settings - Fork 95
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Improve documentation #324
Comments
I know this is an old issue and most things in the list have been done, but as someone who decided to write their first ppx a while ago, I have to say that the manual is nice but there could be a section dedicated to the parsetree (or maybe improving the ast builder/pattern documentation) as it's very hard to find any info about the ast for beginners. I wouldn't mind doing that myself but then again, I don't really know everything about the ast and there's not a lot of information online. |
Hi, I'm a new learner of ppxlib, and here are some possible improvements I found about documentation. This issue was originally discussed in a post in discuss.ocaml.org. Here, I'll use the documentation of I'd say that the doc does a good job listing all the APIs, including the type of arguments and return values. However, more explanation and examples would be really helpful. For example, a short explanation can be added at the top of the page stating that the purpose of | { ptyp_desc = Ptyp_constr (lid, args); _ } ->
(* We generate the name with "_stringify" on the end *)
let new_name = Expansion_helpers.mangle_lid (Suffix "stringify") lid.txt in
let new_lid = { lid with txt = new_name } in
(* We turn it into an identifier hoping we have already generated
the function either by hand or by using the ppx *)
let fn = Exp.ident new_lid in
(* We construct an application of this function to an argument.
Note that we assume the function may be higher-order if the type
contains parameters e.g. int list *)
let app =
if args = [] then fn else
Exp.apply fn (List.map (fun x -> Nolabel, expr_of_type x) args)
in
[%expr fun x -> [%e app] x] Also, I very much agreed with @ComanderP's opinion on adding a specific page to explain the overall design idea or a bigger picture of the AST. For example, I was able to grasp most of the meaning of the AST by looking at this page, but one thing that resulted in some confusions was the naming convention of the For example, some things are named like |
Current situation
As usual, we have different kinds of docs: a
manual(outdated), the API documentation with integrated manual, a section about metaprogramming on ocaml.org, a couple of very simple examples, the dune docs on preprocessing specifications. Apart from that, very important resources to learn about how to write a ppx rewriter are a blog post and the compiler's parsing/parsetree.mli file.The only resource that's kind of complete to learn how to write an extension node rewriter or a deriver is the blog post. The "manual" is more of a very high-level introduction to PPX (which is also very valuable but serves a different purpose) than a detailed manual. The API docs miss docs for some important values and aren't rendered perfectly. Apart from the docs for values/types, the API docs also include some important information about some of the modules (e.g.
Ast_builder
,Ast_pattern
,Ast_traverse
), which isn't easy to find and difficult to put into context.How to improve the situation
For the resources that make sense to co-exist separately, we should make them all easy to find:
Apart from those resources, we're currently also strongly relying on the blog post. Instead, we should integrate everything relevant in there (that is, most of it) into our manual and also write up some new bits for our manual:
Ast_builder
andmetaquot
. Formetaquot
we already have something in the manual.Ast_pattern
andmetaquot
. AboutAst_pattern
: To explain the general concept ofAst_pattern
, we need to write something new; to explain the type parameters inAst_pattern.t
, we can re-use a blog post section; to explain its combinators, we can re-use a discuss answer and link to the module docs.And in our API docs, there are also some things that could be improved:
Ppxlib__.Import.<some_type>
types around in our docs (which lead to the situation that folks would use our internalPpxlib__.Import
API), which now I'm not seeing anymore. We should find out if that was fixed by odoc or if I'm just missing it now.Ocaml_shadow
include in the library interface moduleOf_ocaml
) module allows AST nodes to be converted between the AST version used by ppxlib and the AST version used by the compiler the project is compiled with. The latter is variable and depends on the project. So, if that isn't much work, it would be nice to represent that version in our docs by a place holder such as<compiler_version>
:val copy_structure : Astlib.Ast_412.Parsetree.structure-> Astlib.Ast_<compiler_version>.Parsetree.structure
Currently that version gets fixed by the compiler version odoc uses when generating the docs (apparently, 4.05):
val copy_structure : Astlib.Ast_412.Parsetree.structure-> Astlib.Ast_405.Parsetree.structure
How to priorities
That's a long list of tasks, but lots of them only consist in moving info and adding links. Apart from that, I'd prioritize the new manual sections and adding missing API docs for the most important values. We can then complement the API docs for the more advanced/rare features over time.
The text was updated successfully, but these errors were encountered: