Documenting your modules
Augeas uses NaturalDocs to generate HTML documentation from comments.
Here is an example of a commented module.
(*
Module: Sudoers
Parses /etc/sudoers
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 GPL.
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:
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.
Views
Personal tools
Toolbox
