[wg-camlp4] Changes to the parsetree

[Alain Frisch]

On 03/26/2013 12:57 PM, Thomas Gazagnaire wrote:
> * is the distinction between top-level items and other items really
> necessary (eg, @ vs. @@) ? This seems to be the only "complex" thing
> to explain, as the other parts of the design nicely sounds rather
> simple.

Consider:

type t = Foo of int [@xxx]

val x: int [@xxx]

module X : S [@xxx]

These are attributes on (module) type expressions.  If we want to 
support such attributes in addition to attributes on the corresponding 
"items" (type, value, module declarations), we need a different syntax.

 > Also I'm not sure to understand why you need/want to annotate
> individual structure items in a recursive type declaration.

type t = X | Y
   [@@sexp]
   [@@doc "This is the type [t], supporting s-exp."]

and s = A | B
   [@@xml]
   [@@doc "This is the type [s], supporting xml."]

> * the doc annotations are the ones where you usually prefer to have
> some kind of prefix notation (eg. you usually read what the function
> / module does before reading its signature). Is the plan to
> automatically transform prefix ocamldoc snippets into suffix
> annotations or to drop the prefix doc snippets completely ?

I don't have any plan to rewrite ocamldoc myself; I only mentioned that 
attributes could be used to drastically simplify the design of ocamldoc, 
avoiding the need to re-parse to source file to find comments.

Concerning the syntax, I tend to write ocamldoc comments *after* 
signature items.  Since the comments often refers to parts of the 
definition (function parameters, constructors, etc), it makes sense to 
do so.  This seems to be the convention adopted in the stdlib, for instance.

When using ocamldoc to generate doc based on implementations, not 
interfaces, it would indeed be more natural to put the description 
before the function definition.  But I don't think that ocamldoc is 
really used like that.  Or is it an important use case for you?


Alain