[augeas-devel] Lenses documentation

[Raphaël Pinson]

Hi all,

I made some basic tests yesterday with NaturalDocs.

The modified files can be found on [0], the conf for NaturalDocs is at [1]
and the generated doc is at [2].


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.



Raphael


[0] http://r.pinson.free.fr/augeas/doc/augfiles/
[1] http://r.pinson.free.fr/augeas/doc/conf/
[2] http://r.pinson.free.fr/augeas/doc/



On Sat, Aug 16, 2008 at 12:48 AM, Raphaël Pinson <raphink at gmail.com> wrote:

>
>
> On Fri, Aug 15, 2008 at 8:43 PM, David Lutterkort <lutter at redhat.com>wrote:
>
>> On Fri, 2008-08-15 at 13:40 +0200, Raphaël Pinson wrote:
>>
>> > There are more and more lenses written. Now I think we need a standard
>> > way of documenting them. I'm thinking of a POD-like syntax which could
>> > used within the comments in lenses, and would allow to produce doc for
>> > each lens, or request the doc from the API, like:
>> >
>> > augtool> doc Dput.lns
>> > "We use a standard INI File lens here"
>> > let lns = IniFile.lns section comment
>> > augtool> doc Dput.section
>> > "We use an INI File section with labels, since '/' is allowed in
>> > section names"
>> > let section = IniFile.record title entry comment
>> > augtool> doc Dput.filter
>> > "Apply to dput config files"
>> > let filter = blah blah
>> > augtool> doc Dput
>> > "Dput is a standard INI File lens which allows to parse dput config
>> > files
>> > blah blah blah
>> > more sections and explanations on how to use...
>> > blah blah
>> > Author, blah blah
>> > "
>> >
>> >
>> > The idea behind this is for users to easily get documentation about
>> > lenses without having to read the code.
>>
>> I think that would be very nice .. any thought on what that would look
>> like in the sources ? The cleanest (for users) will be to embed
>> annotations in comments, but then I have to parse the comments ...
>>
>
>
> 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.
>
> 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.
>
>
> Raphael
>
>
> [0] http://www.naturaldocs.org
> [1] http://www.naturaldocs.org/customizinglanguages.html
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/augeas-devel/attachments/20080905/ee522487/attachment.htm>