[wg-camlp4] Structure/signature attributes suggestion

[Gabriel Scherer]

I think the major benefits of extension-points for documentation, compared
to ocamldoc comments, is that they are unambiguously attached to an AST
node. We get in trouble for section headers because they don't fit that
framework very well; they're not semantically attached to a precise node,
and even if you would consider them as attached to a set of nods (the ones
in the section), this set apparently has no reason to respect the AST
structure. So we get an impedance mismatch here.

I don't think that the use case of putting free-floating section nodes in
between mutually recursive declarations is important enough to provoke
large changes to the AST structure. Alain's suggestion to not have any
special syntax for this seems sensible. Once we take a few step back to
contemplate the purpose of sections, one may even consider more flexible
approaches, such as:

();; [@doc.declarations [
  firstpart, {{First Part of my API}};
  second, {{The More Specialized Rest}};
]]

type a = ... [@doc {{...}}][@doc.section firstpart]
and b = ... [@doc {{...}] (* implicitly it's still in section "firstpart" *)
and c = .... [@doc {{...}}]
and d = ... [@doc {{...}}][@doc.section second]
and e = [@doc {{...}}]
and f = ... [@doc {{...}}][@doc.section firstpart]
  (* for some reason I want to display [f] in the first section, but didn't
want to move the actual  code around *)





On Sat, Oct 12, 2013 at 7:59 AM, Alain Frisch <alain.frisch at lexifi.com>wrote:

> What about using regular item attributes for section headers?  This might
> be not so nice conceptually, but would there be actual problems with this
> approach?
>
> -- Alain
>
>
> On 10/11/2013 11:19 PM, Leo White wrote:
>
>> Are you asking for allowing:
>>>
>>>   type t = ...
>>>
>>>   [@@@doc.section ....]
>>>
>>>   and s = ...
>>>
>>>
>>> ?
>>>
>>
>> Yes
>>
>>  Honestly, I'm not yet convinced this is really necessary.  Do we really
>>> need to split documentation sections in such
>>> places?
>>>
>>
>> I think that large files of recursive type definitions, as are quite
>> common in OCaml, are quite likely to want section headers. I am also
>> hoping to be backwards-compatible with existing OCamldoc, which I think
>> supports such comments.
>>
>>  But if we go this way, I'd be inclined to look again at an early
>>> proposal of considering groups of declarations
>>> as successive items (similarly to Types), so that attached item
>>> attributes can be represented more uniformly (in the
>>> signature_item and structure_item records).
>>>
>>
>> I think that will be more work than making type_declaration a variant
>> type with a Ptyp_attribute constructor. However it may be a little
>> neater.
>>
>> Regards,
>>
>> Leo
>>
>>
> ______________________________**_________________
> wg-camlp4 mailing list
> wg-camlp4 at lists.ocaml.org
> http://lists.ocaml.org/**listinfo/wg-camlp4<http://lists.ocaml.org/listinfo/wg-camlp4>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ocaml.org/pipermail/wg-camlp4/attachments/20131012/8e773466/attachment-0001.html>