including doc comments in ast.ml

[panglesd]

While no changes have been made to the AST type since #320 has been merged, the comments have been lifted to doc-comments in ocaml/ocaml#11107.

This PR updates ast_414.ml and ast.ml to include the doc-comments. This will make it possible to link the rendering of these comments it in the ppxlib manual, instead of prompting the reader to open the file in <path-to-opam-switch>/lib/ocaml/compiler-libs/parsetree.mli

[pitag-ha]

Nice, thanks for this super nice docs-experience improvement, both in the compiler and here! I know it must have been a little bit tedious at some parts and really appreciate the outcome! Just a couple of comments:

You need to replace the occurrences of case list with cases (and we should update the comments at the beginning of ast.ml to reflect that). I've marked that in some of the occurrences below, but not in all. Once you've done that, let's see if dune build @lint keeps on complaining or if that's the only adjustment needed.

The next "comment" is more of a question out of curiosity: why have you also modified astlib/ast_414.ml?

And last thing: when running ocamlformat on this, I get the warning

Warning: Invalid documentation comment:
File "ast/ast.ml", line 643, characters 42-43:
'.' is not allowed in '{ul ...}' (bulleted list).
Suggestion: move '.' into a list item, '{li ...}' or '{- ...}'.

Have you also seen that already?

[pitag-ha]

Suggested change

	| Pexp_function of case list (** [function P1 -> E1 | ... | Pn -> En] *)
	| Pexp_function of cases (** [function P1 -> E1 | ... | Pn -> En] *)

[pitag-ha]

Suggested change

	| Pexp_match of expression * case list
	| Pexp_match of expression * cases

[pitag-ha]

Suggested change

	| Pexp_try of expression * case list
	| Pexp_try of expression * cases

[panglesd]

You need to replace the occurrences of case list with cases (and we should update the comments at the beginning of ast.ml to reflect that).

Lo he hecho.

The next "comment" is more of a question out of curiosity: why have you also modified astlib/ast_414.ml?

I figured that the workflow for updating ast.ml is the following:

1. Follow the instructions here to get the new version of astlib
2. Follow the instruction here to transform this ast_xxx into ast.ml.

Of course I could not start the process directly at stage 2 with the compiler parsetree.mli, I needed first the instructions here. And now that I have a new astlib/ast_414.ml, why not include it in the PR, to have everything synced (the compiler parsetree.mli, the astlib/ast_414.ml and the ast/ast.ml)?

And last thing: when running ocamlformat on this, I get the warning

Yes, I will investigate this. I suspect a bug on the ocamlformat side in the rendering of unordered list using some syntax, see the horrible output here.

[panglesd]

see the horrible output here.

Warning: Invalid documentation comment:
File "ast/ast.ml", line 643, characters 42-43:
'.' is not allowed in '{ul ...}' (bulleted list).
Suggestion: move '.' into a list item, '{li ...}' or '{- ...}'.

Why can't I read the line number? Anyway that's fixed!

[pitag-ha]

Cool, thanks again! It looks all good and I think this is a great UX improvement.