FICO
FICO Xpress Optimization Examples Repository
FICO Optimization Community FICO Xpress Optimization Home
Back to examples browserPrevious exampleNext example

Using documentation annotations

Description
The file annotdoc.mos contains some examples of how to define documentation annotations. The model needs to be compiled with the option '-D' to make sure that the resulting BIM file contains the documentation annotations. As a second step, apply the tool 'moseldoc' to this BIM file to obtain a subdirectory with the model documentation in HTML format, for example using the command moseldoc annotdoc.bim

Further explanation of this example: 'Mosel User Guide', Section 18.2 moseldoc: Generating model documentation

ugannotdoc.zip[download all files]

Source Files
By clicking on a file name, a preview is opened at the bottom of this page.
annotdoc.mos[download]





annotdoc.mos

(!******************************************************
   Mosel User Guide Example Problems
   ================================= 

   file annotdoc.mos 
   `````````````````
   Defining documentation annotations.
 
   (c) 2015 Fair Isaac Corporation
       author: S. Heipcke, Mar. 2015, rev. Feb. 2022
*******************************************************!)
model "Using annotations"

(!@doc.
 @title An example of model documentation
 @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

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

!@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

 !@doc.descr Ignored by the documentation
 !@doc.ignore
 R: range
end-declarations

 !@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 following procedure will not be included into the documentation
!@doc.descr Ignored by the documentation
!@doc.ignore
public procedure hiddenproc
 a:=1
end-procedure

end-model

Back to examples browserPrevious exampleNext example