Ast_builder documentation

[patricoferris]

Related to: #324, #435

Much of Ast_builder is undocumented. The names of functions are derived from the things they construct from Ast.ml (mostly AST nodes from Parsetree). The parsetree is well-documented. This PR pulls through that documentation directly to Ast_builder.

In order for this to work well, the gen_ast_builder script now produces module types for the interface to Ast_builder (one for functions with ~loc arguments called S_located and one without, corresponding to the original S).

Before:

After:

Known problems:

Some of the doc attributes pulled from the parsetree contain odoc references which clash with the function names defined in the generated code e.g. type label_declaration and val label_declaration clash for the documentation comment attached to ptyp_poly.

---

If there is agreement to add this we could do the same for Ast_pattern I'm sure.

[NathanReb]

This looks great! Awesome addition!

I have a few minor code comments but other than that I think it's a great idea and a very useful addition to the documentation.

On a slightly unrelated note, I wonder if we shouldn't change the way we generate those files to promote the generated sources so they can be inspected and we are notified whenever they are updated rather than all of it being silent as it is now. That's of course a matter for a separate PR but I'm still curious to know what you think about it!

[patricoferris]

On a slightly unrelated note, I wonder if we shouldn't change the way we generate those files to promote the generated sources so they can be inspected and we are notified whenever they are updated rather than all of it being silent as it is now. That's of course a matter for a separate PR but I'm still curious to know what you think about it!

I think that's a great idea and would make debugging a little easier I think (a few times, especially for docs, I was having to open _build/default/src/ast_builder_generated.ml

[NathanReb]

Looks good to me! Let's follow up on promoting the generated files and optimizing the parse/print loops in a few places!

I'll open issues for both!

[NathanReb]

@patricoferris I think you can go ahead and merge this!