[augeas-devel] Re: Lenses documentation

[Raphaël Pinson]

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

> |--==> On Fri, 5 Sep 2008 10:06:05 +0200, "Raphaël Pinson" <
> raphink at gmail.com> said:
>
>  >>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.
>  >>
>
>   RP> Yes, it requires a specific pattern for comments (although quite
> permisive),
>  RP> like
>
>  RP> "
>  RP> Define: mylens
>  RP>  The description of my lens
>
>  RP> Parameters:
>  RP>   param1 - description of parameter 1
>  RP>   param2 - description of parameter 2, linking to <Another Lens>
>  RP> "
>
> I see, the comments are now a bit cluttered because of the duplicated
> code, but it looks good otherwise.
>
>  RP> You can have a look at the sources at
>  RP> http://r.pinson.free.fr/augeas/doc/augfiles to see how it looks.
>  RP> I also wrote to Greg Valure - the NaturalDocs dev - to ask him about
> info on
>  RP> how to add full support (or at least greater support) for a language
> so that
>  RP> NaturalDocs parses not only the comments but also the code of the
> lenses, to
>  RP> grab the definitions of each lens for example, without having to
> rewrite it
>  RP> in the comments.
>
> What about also trying to drop some keywords like "Section:", and have
> them simply implied by comments a structure like
>
> (************************************************************************
>  *                           MY SECTION
>  *************************************************************************
>
> ?
>
> It would make the code look lighter, although it forces using specific
> structures for comments (which I don't dislike).
>


Yes, but NaturalDocs doesn't support that. I tried quite a few things and
was not happy with the results, so I chose to keep "Section:" and "Title:"
because these are NaturalDocs keywords.



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