ocaml-ppx
Manual missing
ppxlib is missing a manual. Right now the only "doc" available is existing code or the various .mli files. A manual is necessary for a piece of the ecosystem as central as ppxlib. See https://discuss.ocaml.org/t/am-i-missing-some-comprehensive-ppxlib-resource-somewhere/9277/2 for a recent discussion.
I want to add that metaquot probably more requires documentation then Ast_pattern. The only source of information I know about is .mli file in Lexify's project: https://github.com/ocaml-ppx/ppx_tools/blob/master/src/ppx_metaquot.ml @pitag-ha
Yes, thanks for opening the issue (and pinging me)! We definitely need to revamp our documentation (including the manual) and it's good to list what we're planning to do in an issue. Before coming to that list, I want to discuss the concrete topic you've mentioned: the manual.
Ppxlib does have a manual: https://ppxlib.readthedocs.io/en/latest/ (in fact, it's the only resource the user who wrote the discuss post you're mentioning had found before writing the post). @nojb, when you're saying "ppxlib is missing a manual", is that because you couldn't find that manual or because you think that manual is so brief and so high-level that it doesn't actually serve the purpose of a manual? (disclaimer: we have plans to tackle both those problems, but I'm curious which one was the problem here)
@Kakadu, there's also a section in our manual on metaquot: https://ppxlib.readthedocs.io/en/latest/ppx-for-plugin-authors.html#metaquot. I think from your comment it's quite clear that you didn't find that section so far (which is a problem we need to improve). Now that you've seen it, do you think there's something missing in there?
is that because you couldn't find that manual or because you think that manual is so brief and so high-level that it doesn't actually serve the purpose of a manual?
The latter: it is far too high-level and informal to be useful to beginners.
Ok, yes, I agree. I'll write an issue this week pointing out which things I think need to be added so that that can be discussed.
@pitag-ha I indeed haven't found the section about metaquot. I'm not sure why... I should also mention that I don't like CSS of the docs page. In the screenshot below you can see that actual useful text takes only 1/3 of my screen with, I don't really use tablet for reading documentation. Camlp5 and dune should also suffer from this, but for some reason my hands applied zoom on its' documentation pages, but for ppxlib -- not. Probably, we need at least fill the left contents column more carefully and often.
There are also more precise remarks about text describing ppx_metaquot.
- We start from say that normal quotations may be used to construct parts of AST. OK.
- After some example we show an example of using quotation in pattern matching (some
?are added). - After that syntax of antiqotations is described (without
?obviously). It also mentions special syntax for module expressions. I got a question: are module expressions supported in normal quotations? (see part 1) - And now we say that in pattern matching we should use antiquotations with
?. It looks like (2) and (3) should be reordered
Also, today I was touch my PPX extensions and few questions (unrelated to this thread) appeared again. Is it doable to extend metaquotations with new quotations for Longidents? I'm thinking about simplifying the code
(match t.ptyp_desc with
| Ptyp_constr ({ txt = Ldot (Lident "GT", "list") }, xs) -> ...
Just to be clear, as of right now, if you go to the official documentation page at https://ppxlib.readthedocs.io/en/latest/ there is nothing at all there.
