Documenting models using annotations

The predefined doc annotation category can be used to document a Mosel file. Using a dedicated set of annotations the model author can add descriptions to the various entities defined in the source, the user-defined descriptions are completed by definitions automatically generated by the Mosel compiler.

From a bim file that includes such definitions a documentation processor may produce a complete document: as an example, the Xpress distribution comes with the moseldoc processor that generates an HTML documentation from an annotated bim file.

doc annotation category

Unlike other annotation categories, the doc annotation category is disabled by default such that the corresponding annotations are silently ignored. To generate a documentation-enabled bim file the compiler has to be run with the option -D. In addition to enabling the doc category, this flag also activates the automatic generation of certain documentation annotations by the compiler. Alternatively to using this flag, a model may define the following annotations:

!@mc.set doc enable
!@doc.autogen=true

Note that these special annotations can also be used in the source file as a means to exclude some definitions from the documentation, setting doc.autogen to false right before the definitions to be excluded and back to true immediately after.

Global definitions

The following global annotations are automatically generated by the compiler:

@doc.name

Name of the package or model

@doc.version

Version number as stated by the 'version' statement

@doc.date

Current date

@doc.ispkg

Set to 'true' if the file is a package

All automatic annotations can also be defined explicitly in the Mosel source to overwrite their default values.

The following annotations may be added to complete the general appearance of the document to be produced (they are used by the moseldoc documentation processor):

@doc.title

Title of the document

@doc.subtitle

Subtitle of the document

@doc.xmlheader

Header of the XML document

@doc.xmlroot

Name of the XML element containing the documentation

@doc.id

Prefix used to generate IDs of chapters, sections, and subsections. If the documentation for several packages is generated from a single master model then a unique ID must be explicitly defined in each of the packages in order to avoid ID collision

The @doc category is complete (i.e. it is not possible to create new doc.X annotations), however, the category @doc.ext can be used to define further information assuming a particular documentation processor can exploit it.

Document structure

Optionally, the resulting document may be organised in chapters, sections and subsections. Each of these constructs can contain both text paragraphs and entity descriptions (declarations and subroutines). To enter a new documentation component, one of the following annotations has to be defined:

@doc.chapter

Start a chapter

@doc.section

Start a section inside of a chapter

@doc.subsection

Start a subsection inside of a section

Chapters and sections may also be taken from external files: the annotation @doc.include specifies a file name that must be a valid XML document including either chapters (tag <chapter>) or sections (tag <section>). The Mosel compiler will record the location of the inclusion that will be executed by the moseldoc processor.

In addition to the provided title a short title might also be defined (using @doc.shorttitle) that will be used in place of the (long) title in the table of contents. Whenever a new division starts, a unique ID is automatically generated based on the section number and any defined prefix specified in the header of the document with @doc.id. It is also possible to explicitly define an ID using @doc.id just after entering the section (this is required when the section has to be referenced using a <ref> tag).

From inside of any of these divisions a new paragraph is added with the @doc.p annotation. By default any new addition (paragraph or entity description) is appended to the current component but it is possible to select an alternative location. A target location has first to be defined using the annotation @doc.location: this creates a label associated with the current section. Defining the annotation @doc.relocate with this target elsewhere in the source file will move all subsequent additions to the target location; this relocation will continue up to the next division marker or relocation definition. Note that defining an empty relocation reverts to the effective current location. Example:

(!@doc.
  @chapter My first chapter
  @p some text related to the first chapter
  @location first_chap
  @section first section of first chapter
  @p something about the section
  @relocate first_chap
  @p this paragraph will be inserted directly under first chapter
  @relocate
  @p but this one will remain in the section
!)

Symbol definitions

The following sections list the various documentation annotations that can be defined depending on the kind of the entity (parameter, variable, type or subroutine) to be documented. Some of these annotations are automatically defined by the compiler: in the case of values (like the value of a constant) the automatic definition may not be performed if the value is the result of a calculation that cannot be evaluated at compile time ("runtime constant"). In this case it is required to explicitly specify the text that should be retained in the documentation.

Parameters

@doc.descr

Description (1-2 text lines)

@doc.default

Default value (automatically generated)

@doc.type

Type (automatically generated)

@doc.value

Possible value and explanation of its meaning (may be defined several times)

@doc.info

Some more detailed explanations (may be defined several times)

@doc.ignore

The symbol will be ignored by the documentation processor

@doc.deprecated

The parameter is deprecated and should no longer be used (an explanation can be given)

Types, constants and variables
This set of annotations apply to symbols declared in declarations blocks. Record fields (both for a type declaration and for a variable) can be described using @doc.recflddescr: the value of this annotation consists in the name of the field followed by its description (a space should separate these two components)

@doc.descr

Description (1-2 text lines)

@doc.const

For a constant: value (automatically generated)

@doc.type

Type (automatically generated)

@doc.typedef

For a type definition: type (automatically generated)

@doc.value

Possible value and explanation of its meaning (may be defined several times)

@doc.info

Some more detailed explanations (may be defined several times)

@doc.setby

Name of subroutines modifying this entity

@doc.recfldtype

Type of a record field (automatically generated)

@doc.recflddescr

Description of a record field

@doc.ignore

The symbol will be ignored by the documentation processor

@doc.deprecated

The type or variable is deprecated and should no longer be used (an explanation can be given)

Procedures and functions
Information from different overloaded versions of a given subroutine is merged automatically. The @doc.group annotation may be used to merge information of routines with different names but used for a similar task (up to 3 different subroutine names can be grouped). The @doc.param annotation is used to describe the parameters of the routine: the value of this annotation consists in the name of the parameter followed by its description (a space should separate these two components)

@doc.group

Name of another subroutine that this one should be grouped with

@doc.descr

Description (1-2 text lines)

@doc.shortdescr

Shortened description for table of contents and list display

@doc.syntax

Routine signature (automatically generated)

@doc.param

Name and meaning of a subroutine argument (may be defined several times)

@doc.paramval

Possible value and meaning of a subroutine argument (may be defined several times). The value of this annotation is the name of the parameter (as specified with a preceding @doc.param) followed by the value and the explanation

@doc.return

For functions only: what is returned

@doc.err

Possible error code (may be defined several times)

@doc.example

Example of use (may be defined several times)

@doc.info

Some more detailed explanations (may be defined several times)

@doc.related

List of related symbols

@doc.ignore

The subroutine will be ignored by the documentation processor

@doc.deprecated

The subroutine is deprecated and should no longer be used (an explanation can be given)

Annotation definitions

A special set of annotations (category @doc.annot) is available for documenting annotation definitions in Mosel packages (not supported for Mosel models). The annotations for documenting annotation definitions are global annotations, their value must start with an annotation name in order to associate them with the corresponding annotation definition.

@doc.annot.descr

Annotation name followed by a short description (1-2 text lines)

@doc.annot.default

Annotation name and default value

@doc.annot.value

Annotation name, possible value and explanation of its meaning (may be defined several times)

@doc.annot.type

Annotation type

@doc.annot.info

Annotation name and some more detailed explanations (may be defined several times)

@doc.annot.deprecated

Annotation name and optionally some explanatory text

@doc.annotcat

Annotation category to document (may be defined several times), if undefined all categories are documented

@doc.annotloc

Insertion point (specified via @doc.location) for annotations documentation

Package control parameters

A special set of annotations (category @doc.cparam) is available for documenting control parameters of Mosel packages. The annotations for documenting control parameters are global annotations, their value must start with a parameter name in order to associate them with the corresponding control parameter.

@doc.cparam.descr

Parameter name followed by a short description (1-2 text lines)

@doc.cparam.default

Parameter name and default value

@doc.cparam.value

Parameter name, possible value and explanation of its meaning (may be defined several times)

@doc.cparam.type

Parameter type (automatically generated by the compiler)

@doc.cparam.info

Parameter name and some more detailed explanations (may be defined several times)

@doc.cparam.deprecated

Parameter name and optionally some explanatory text

@doc.cparamloc

Insertion point (specified via @doc.location) for control parameters documentation

moseldoc documentation processor

Running moseldoc

The moseldoc program takes as input either a bim file produced from a Mosel model compiled with the -D compiler option or directly a Mosel source file (in which case a compilation step is automatically executed). Typically the generation of the documentation from a source file will be obtained with the following command:

>moseldoc mymodel.mos

The result of this process is an XML file ("mymodel_doc.xml") and a directory containing an HTML version of the documentation ("mymodel_html"). The program will produce only the XML file (from a bim or source file) if option -xml is used and only the HTML output (from an XML file) if -html is selected. The option -f is required to force the replacement of existing files.

As a Mosel program available in source form, moseldoc can be adapted to fit specific requirements. To re-generate the executable use this compilation command:

>mosel comp -s moseldoc.mos -o deploy.exe:moseldoc,css-z=moseldoc.css

Structure of the generated document

The resulting document respects the structure defined by the dedicated annotations (chapter, section, subsection). In each of these divisions, the paragraphs are exposed first, then the parameters and variables and finally the list of subroutines. If no structural elements have been defined, a chapter per entity type is automatically created to group similar objects (Parameters, Constants, Types, Variables and Subroutines).

Processing of annotation values

Values associated with descriptive text annotations (like section titles or descriptions) are interpreted as XML. Paragraphs (@doc.p) and examples (@doc.example) are handled in a specific way: by default the value is inserted as XML but, if the value starts with [TXT], the content is treated as plain text; if it starts with [SRC], the value is considered to be some example code and it is reproduced preserving spacing. If it starts with [NOD], it is interpreted as a self-contained XML node (i.e. it is not inserted in a paragraph block). In an XML block of text, the markers ref (chapter/section/subsection reference), fctRef (subroutine reference) and entRef (entity reference) are processed such that in the HTML document they are turned into hyperlinks to the corresponding objects. Similarly, the tt element type is replaced by an appropriate style for displaying code samples.