[augeas-devel] Re: Lenses documentation

[Free Ekanayaka]

|--==> 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).

Ciao,

Free