[augeas-devel] Re: Lenses documentation

[Raphaël Pinson]

On Fri, Sep 5, 2008 at 9:52 AM, Free Ekanayaka <free at 64studio.com> wrote:

> Hi Raphaël,
>
> |--==> On Fri, 5 Sep 2008 08:36:52 +0200, "Raphaël Pinson" <
> raphink at gmail.com> said:
>
>  RP> Hi all,
>  RP> I made some basic tests yesterday with NaturalDocs.
>
>  RP> The modified files can be found on [0], the conf for NaturalDocs is at
> [1]
>  RP> and the generated doc is at [2].
>
>
>  RP> The down side of this currently is that the comments repeat the
> contents of
>  RP> the code, which make it a bit heavy to document. Ideally, I would like
> to
>  RP> make a Perl Module for NaturalDocs to enhance the Augeas language
> support,
>  RP> in order to parse the files for definitions, and only add comments for
> what
>  RP> is not explicit yet.
>
> Very interesting. Does it work only for lenses written with specific
> patterns for comments? I like the idea of having a "standard" way for
> writing lenses.
>

Yes, it requires a specific pattern for comments (although quite permisive),
like

"
Define: mylens
 The description of my lens

Parameters:
  param1 - description of parameter 1
  param2 - description of parameter 2, linking to <Another Lens>
"

You can have a look at the sources at
http://r.pinson.free.fr/augeas/doc/augfiles to see how it looks.
I also wrote to Greg Valure - the NaturalDocs dev - to ask him about info on
how to add full support (or at least greater support) for a language so that
NaturalDocs parses not only the comments but also the code of the lenses, to
grab the definitions of each lens for example, without having to rewrite it
in the comments.



Raphaël
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/augeas-devel/attachments/20080905/4fff7ad6/attachment.htm>