[wg-camlp4] Changes to the parsetree

[Thomas Gazagnaire]

>> * 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.

ok.

> > 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."]

For the @@sexp and @@xml parts, you won't see that in real-codebases. Usually, all the types in a given module/file have their associated generators. But ok for the documentation.

> 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.

A lot of existing code doesn't follow this convention (JS' core for instance). Personally, I found clearer to read what the function/type/module does in a comment, before reading its signature. 

> 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?

I never use ocamldoc on .ml files, so no, it's not important for me.

Thomas