Documenting your modules

Augeas uses NaturalDocs to generate HTML documentation from comments.

Here is an example of a commented module.

 Author: Raphael Pinson <[email protected]>
 
 About: Reference
   This lens tries to keep as close as possible to `man sudoers` where possible.
 
 For example, recursive definitions such as
 
      > Cmnd_Spec_List ::= Cmnd_Spec |
      >                    Cmnd_Spec ',' Cmnd_Spec_List
 
 are replaced by
 
   >   let cmnd_spec_list = cmnd_spec . ( sep_com . cmnd_spec )*
 
 since Augeas cannot deal with recursive definitions.
 The definitions from `man sudoers` are put as commentaries for reference
 throughout the file. More information can be found in the manual.
 
 About: License
   This file is licensed under the LGPLv2.
 
 About: Lens Usage
   Sample usage of this lens in augtool
 
     * Set first Defaults to apply to the "LOCALNET" network alias
       > set /files/etc/sudoers/Defaults[1]/type "@LOCALNET"
     * List all user specifications applying explicitely to the "admin" Unix group
       > match /files/etc/sudoers/spec/user "%admin"
     * Remove the full 3rd user specification
       > rm /files/etc/sudoers/spec[3]
 
 About: Configuration files
   This lens applies to /etc/sudoers. See <filter>.
 *)
 
 
 module Sudoers =
   autoload xfm
  
 (************************************************************************
  * Group:                 USEFUL PRIMITIVES
  *************************************************************************)
 
 (* Group: Generic primitives *)
 (* Variable: eol *)
 let eol       = del /[ \t]*\n/ "\n"
 
 (* Variable: indent *)
 let indent    = del /[ \t]*/ ""
 
 (* Group: Comments and empty lines *)
 
 (* View: comment
 Map comments in "#comment" nodes *)
 let comment =
   let sto_to_eol = store /([^ \t\n].*[^ \t\n]|[^ \t\n])/ in
   [ label "comment" . del /[ \t]*#[ \t]*/ "# " . sto_to_eol . eol ]
 
 (* View: empty
 Map empty lines *)
 let empty   = [ del /[ \t]*#?[ \t]*\n/ "\n" ]

Let's detail this example a bit:

Table of Contents General Keywords Modules Groups Variables View

General

NaturalDocs makes a large use of comments. In Augeas, comments are embedded by '(*' and '*)'. NaturalDocs fields are declared within these comments, following the format "Field: Value".

The lines following a NaturalDocs statement belong to this field, until another statement is met.

You can use one-liner comments...

 (* Group: Useful primitives *)

... boxes...

 (************************************************************************
  * Group:                 Useful primitives
  *************************************************************************)

... C-style comments...

 (*
  * Group: Useful primitives
  *
  *)

Keywords

Modules

The "Module" keyword introduces an Augeas module. It should be the first NaturalDocs keyword you use in your module.

Groups

The "Group" keyword creates a group in the documentation. This is useful to group your statements.

Variables

"Variable" is used to refer to Augeas statements that are not lenses. For example,

 let eol = "\n"

can be labeled Variable, while

 let empty = [ eol ]

is labeled View.

View

"View" is used to label Augeas lenses.