moseldoc: Generating model documentation

The Mosel compiler reserves a special treatment to annotations belonging to the doc category. This annotation category will only be included into the BIM file if the source file is compiled with the option -D, such as

mosel comp -D mymodel.mos

To enable the -D compiler option in Xpress Workbench open the Run menu and select the entry Compiler Options, enable the Generate Doc Annotations option, and confirm with Save. When you next click the Compile button in the Workbench toolbar, the resulting BIM file will contain documentation annotations.

The tool moseldoc can be applied to the resulting BIM file to generate an XML file that is then processed into a set of HTML pages:

moseldoc mymodel                   ! Generates HTML and XML
moseldoc -html mymodel             ! HTML output only
moseldoc -o mydir -html mymodel    ! Specify HTML output directory
moseldoc -xml mymodel              ! XML output only
moseldoc -ixml mymodel             ! XML file for inclusion (omitting header+root)
moseldoc -f mymodel                ! Force output overwrite

Here are some examples of how to use the documentation annotations:

• Document structure:

  (!@doc.
   @title An example of model documentation
   @version 0.0.1
   @date March 2015
  
   @chapter Introduction
   @p
   This model needs to be compiled with the <tt>-D</tt> compiler option
   to include the documentation annotations into the BIM.
   The <tt>moseldoc</tt> program takes the resulting BIM file as input.
  !)
  
  !@doc.chapter The example
  !@doc.section Parameters

  The resulting cover page and table of contents generated by moseldoc look as follows (the contents listing also refers to the entity and subroutine annotations shown in the following items):
  
• Documenting parameters:

  parameters
   !@doc.descr Short parameter description
   !@doc.value v1 possible value
   !@doc.value v2 another possible value
   !@doc.info Some more explanation (longer text)
   MYPAR="some text"
  end-parameters

• Documenting entity declarations (type definitions, constants, variables):

  !@doc.section Constants and variables
  public declarations
   (!@doc.
     @descr Short description of the constant set
     @info Some additional information
   !)
   S=1..10
  
   !@doc.descr An error code constant
   MYERR=11
  
   (!@doc.
     @descr A record type
     @recflddescr fld1 field description
     @recflddescr fld2 another field description
     @info Several @doc.info tags can be used for a given entity
     @info Entities can be referenced: <entRef>rectype</entRef>
   !)
   rectype=public record
    fld1:integer
    fld2:string
   end-record
  end-declarations

  This is the HTML page generated by moseldoc from these parameter and entity annotations:
  
• Documenting subroutines:

  !@doc.section Subroutines
  
  (!@doc.
    @descr A short description
    @param i first parameter
    @paramval i value1 description of value1
    @paramval i value2 description of value2
    @param r second parameter
    @err MYERR reference to an error code constant
    @return The return value
    @example Some descriptive text for the example
    @example [SRC]
    the example code is here
    @info Some useful information for <tt>myfunct</tt>
    @related <fctRef>myotherfunct</fctRef>
  !)
  public function myfunct(i:integer,r:real):boolean
   returned:=i>r
  end-function
  
  !@doc.group myfunct
  !@doc.info <tt>myotherfunc</tt> is an alternative to <fctRef>myfunct</fctRef>
  public function myotherfunc(i:integer):boolean
   returned:=true
  end-function

  The HTML subroutine documentation page generated by moseldoc from these annotations is shown here:
  
• Relocating documentation contents:

  !@doc.section A section title
  !@doc.relocate newlocref
   ...   ! All doc annotations defined here will be inserted at marker 'newlocref'
  !@doc.relocate
   ...   ! All subsequently defined doc annotations remain where they are
  
  !@doc.section Destination location
  !@doc.location newlocref

• Excluding contents from generated documentation:

  !@doc.autogen=false
  public declarations
    ...  ! All doc annotations defined here will be ignored
  end-declarations
  !@doc.autogen=true
    ...  ! All subsequently defined doc annotations will get processed