[augeas-devel] Lenses documentation

[David Lutterkort]

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

David