<div dir="ltr">Hi all,<br><br>I made some basic tests yesterday with NaturalDocs.<br><br>The modified files can be found on [0], the conf for NaturalDocs is at [1] and the generated doc is at [2].<br><br><br>The down side of this currently is that the comments repeat the contents of the code, which make it a bit heavy to document. Ideally, I would like to make a Perl Module for NaturalDocs to enhance the Augeas language support, in order to parse the files for definitions, and only add comments for what is not explicit yet.<br>
<br><br><br>Raphael<br><br><br>[0] <a href="http://r.pinson.free.fr/augeas/doc/augfiles/">http://r.pinson.free.fr/augeas/doc/augfiles/</a><br>[1] <a href="http://r.pinson.free.fr/augeas/doc/conf/">http://r.pinson.free.fr/augeas/doc/conf/</a><br>
[2] <a href="http://r.pinson.free.fr/augeas/doc/">http://r.pinson.free.fr/augeas/doc/</a><br><br><br><br><div class="gmail_quote">On Sat, Aug 16, 2008 at 12:48 AM, Raphaël Pinson <span dir="ltr"><<a href="mailto:raphink@gmail.com">raphink@gmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><div dir="ltr"><br><br><div class="gmail_quote"><div><div></div><div class="Wj3C7c">On Fri, Aug 15, 2008 at 8:43 PM, David Lutterkort <span dir="ltr"><<a href="mailto:lutter@redhat.com" target="_blank">lutter@redhat.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
<div><div></div><div>On Fri, 2008-08-15 at 13:40 +0200, Raphaël Pinson wrote:<br>
<br>
> There are more and more lenses written. Now I think we need a standard<br>
> way of documenting them. I'm thinking of a POD-like syntax which could<br>
> used within the comments in lenses, and would allow to produce doc for<br>
> each lens, or request the doc from the API, like:<br>
><br>
> augtool> doc Dput.lns<br>
> "We use a standard INI File lens here"<br>
> let lns = IniFile.lns section comment<br>
> augtool> doc Dput.section<br>
> "We use an INI File section with labels, since '/' is allowed in<br>
> section names"<br>
> let section = IniFile.record title entry comment<br>
> augtool> doc Dput.filter<br>
> "Apply to dput config files"<br>
> let filter = blah blah<br>
> augtool> doc Dput<br>
> "Dput is a standard INI File lens which allows to parse dput config<br>
> files<br>
> blah blah blah<br>
> more sections and explanations on how to use...<br>
> blah blah<br>
> Author, blah blah<br>
> "<br>
><br>
><br>
> The idea behind this is for users to easily get documentation about<br>
> lenses without having to read the code.<br>
<br>
</div></div>I think that would be very nice .. any thought on what that would look<br>
like in the sources ? The cleanest (for users) will be to embed<br>
annotations in comments, but then I have to parse the comments ...<br>
<font color="#888888"></font></blockquote></div></div><div><br><br>I'm guessing that you would like the language to stay standard ML, so it would be better to describe the doc in the comments (I don't know if ML languages like ocaml have inline-doc systems.<br>

<br>The puppet common modules talk has led to using Natural Docs [0] for their inline doc. ML languages don't seem to be supported yet, but they have some doc [1] on how to add support for more languages. This would allow to easily produce a web interface (or standalone doc), but I'm not sure it would help getting interactive doc from augtool.<br>

<br><br>Raphael<br></div></div><br><br>[0] <a href="http://www.naturaldocs.org" target="_blank">http://www.naturaldocs.org</a><br>[1] <a href="http://www.naturaldocs.org/customizinglanguages.html" target="_blank">http://www.naturaldocs.org/customizinglanguages.html</a><br>

</div>
</blockquote></div><br></div>