[augeas-devel] Lenses documentation

[Raphaël Pinson]

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/20080816/961cf474/attachment.htm>