<div dir="ltr"><div><div><div><div><div><div><div><div>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.<br>

<br></div>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:<br>

<br></div>();; [@doc.declarations [<br></div>  firstpart, {{First Part of my API}};<br></div>  second, {{The More Specialized Rest}};<br>]]<br><br></div>type a = ... [@doc {{...}}][@doc.section firstpart]<br></div>and b = ... [@doc {{...}] (* implicitly it's still in section "firstpart" *)<br>

</div><div>and c = .... [@doc {{...}}]<br></div>and d = ... [@doc {{...}}][@doc.section second]<br></div><div>and e = [@doc {{...}}]<br></div>and f = ... [@doc {{...}}][@doc.section firstpart] <br>  (* for some reason I want to display [f] in the first section, but didn't want to move the actual  code around *)<br>

<div><div><div><div><div><div><div><br><br><br></div></div></div></div></div></div></div></div><div class="gmail_extra"><br><br><div class="gmail_quote">On Sat, Oct 12, 2013 at 7:59 AM, Alain Frisch <span dir="ltr"><<a href="mailto:alain.frisch@lexifi.com" target="_blank">alain.frisch@lexifi.com</a>></span> wrote:<br>

<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">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?<span class="HOEnZb"><font color="#888888"><br>


<br>
-- Alain</font></span><div class="HOEnZb"><div class="h5"><br>
<br>
On 10/11/2013 11:19 PM, Leo White wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Are you asking for allowing:<br>
<br>
  type t = ...<br>
<br>
  [@@@doc.section ....]<br>
<br>
  and s = ...<br>
<br>
<br>
?<br>
</blockquote>
<br>
Yes<br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Honestly, I'm not yet convinced this is really necessary.  Do we really need to split documentation sections in such<br>
places?<br>
</blockquote>
<br>
I think that large files of recursive type definitions, as are quite<br>
common in OCaml, are quite likely to want section headers. I am also<br>
hoping to be backwards-compatible with existing OCamldoc, which I think<br>
supports such comments.<br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
But if we go this way, I'd be inclined to look again at an early proposal of considering groups of declarations<br>
as successive items (similarly to Types), so that attached item attributes can be represented more uniformly (in the<br>
signature_item and structure_item records).<br>
</blockquote>
<br>
I think that will be more work than making type_declaration a variant<br>
type with a Ptyp_attribute constructor. However it may be a little<br>
neater.<br>
<br>
Regards,<br>
<br>
Leo<br>
<br>
</blockquote>
<br>
______________________________<u></u>_________________<br>
wg-camlp4 mailing list<br>
<a href="mailto:wg-camlp4@lists.ocaml.org" target="_blank">wg-camlp4@lists.ocaml.org</a><br>
<a href="http://lists.ocaml.org/listinfo/wg-camlp4" target="_blank">http://lists.ocaml.org/<u></u>listinfo/wg-camlp4</a><br>
</div></div></blockquote></div><br></div>