Documenting your modules

raphink edited this page Jan 4, 2013 · 1 revision

Augeas uses NaturalDocs to generate HTML documentation from comments.

Here is an example of a commented module.

 Author: Raphael Pinson <raphink@gmail.com>
 
 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

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.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.