[wg-camlp4] Changes to the parsetree

[Alain Frisch]

On 03/26/2013 01:49 PM, Thomas Gazagnaire wrote:
> Personally, I found clearer to read what the function/type/module does in a comment, before reading its signature.

Of course, nothing prevent the tool to show the text before the item in 
the generated doc.  This is really a discussion about where to put the 
text in the source file (we expect users to read the ocamldoc-generated 
documentation, not the source .mli files).

Note that you can write:

;;[@@doc "blabla"]
val f: int -> unit

Here, the attribute is a standalone (floating) signature-item attribute. 
  The tool could interpret such attributes as being attached to the 
following item.  But I don't find it very nice to break the natural 
"scoping" of attributes like that.  (To some extent, the minidoc example 
already does that, since it allows "section headers" to be put on other 
items' attributes.)

ocamldoc uses the same syntax for prefix and postfix notation, and 
relies on heuristics based on concrete placement (including whitespace, 
I believe) in order to attach comments to items.  This is very fragile, 
and it doesn't support some interesting usage scenarios (like 
documentation fragments generated/inserted by -ppx filters).  If we had 
to support a prefix notation for attributes, we would need to introduce 
a different syntax.  We discussed it, but I don't think it is worthwhile 
doing so only for this use case.


-- Alain