Model Documentation
Home > Model Development Topics > Model Documentation
This topic describes how to incorporate documentation into model code, how model developers can use it in an IDE or as doxygen-generated HTML content, and how model users can access it.
- Introduction and outline
- Symbol documentation in model code How to provide human-language descriptive information in model code
- Model user documentation How model users can access model documentation
- Identifying missing symbol documentation Describes options to identify missing symbol documentation
- Model documentation produced by doxygen
Model documentation has two different audiences: model developers and model users.
Model developers use model documentation to navigate and understand model code. They can access model documentation through an IDE like Visual Studio, through stand-alone developer documentation, or directly from the model source code.
Model users use model documentation to understand how the model works, and more specifically the meaning and proper use of a model's input parameters, output tables, and associated enumerations. They access model documentation through the model UI or through stand-alone user documentation.
Model documentation has several possible sources:
- Authored documents for developers
- Authored documents for users
- Symbol labels and notes in structured comments in model code
- Symbol declarations and use in model code
This topic focuses on the latter two of these sources.
Examples use the RiskPaths model which is included in OpenM++ distributions.
This subtopic describes how to provide human-readable documentation for model symbols in model code. Some of this documentation becomes available in the model's UI.
This subtopic contains the following sections:
Each human language supported by a model has an associated language code given
in the languages statement of the model.
A model is required to have a languages statement which declares at least one language.
For example,
languages
{
EN, //EN English
FR //FR Français
};
//LABEL(EN,FR) English
//LABEL(FR,EN) Françaisdeclares two languages EN and FR.
These codes can be used in model code
to provide language-specific documentation of model symbols.
The first language listed in the languages statement is the default language of the model,
which in this example is EN.
The default language of the model is usually the language in which the source code is written.
The language presented initially in the UI might not be the default language,
but instead the language of the locale on the end user's device.
An end user can switch languages dynamically in the UI.
The trailing single-line comment (//EN and //FR) after each language code provides
a language-specific label for the language code declared previously in the line.
The UI uses these labels to display human-language versions of the model's available languages
when a user selects or changes the UI language.
The single line comments following the languages statement which start with //LABEL are optional.
They are used to explicitly provide a language-specific version of each language name in the other language.
For example,
//LABEL(EN,FR) provides the label to use in the UI
for the language code EN when the UI is displaying in French (FR).
The French translation of English is Anglais,
and the English translation of Français is French.
However, in the context of language switching in the UI,
it makes sense to instead show human-language labels
which are recognized by a native user of that language, rather than a translated version.
For example, an English native speaker with no knowledge of French
would recognize the word English
in the language selection screen, whether the current language of that screen is English or French.
They might not recognize the word Anglais had it been used instead.
For more details on specifying language specific labels, see Symbol labels below.
[back to symbol documentation in model code]
[back to topic contents]
Model symbols are declared in syntactic islands in model code.
A model symbol can have a label for each human language
declared in the languages statement.
A symbol label can be provided where the symbol is declared, for example
actor Person
{
//EN Union counter
int unions = {0};
...To be recognized as a language label,
there must be no white space between // and the language code,
and white space is required between the language code and the label text.
In this example, a label is provided for the symbol unions by a comment
on the line immediately preceding the symbol declaration.
It can also be provided on the same line as the declaration by placing the trailing // comment there.
A symbol label can also be provided in a LABEL comment in model code.
This is particularly useful for models which support more than one language.
For example,
//LABEL( Person.unions, FR ) Compteur d’unionsprovides the label for the unions attribute in the Person entity for the human language FR.
To be recognized as a human-language label,
there must be no white space between // and LABEL.
Subsequent white space is optional.
Model code sometimes declares a symbol positionally rather than using a name.
A label can be provided for positional symbols on the same line
or on the immediately preceding line,
just like for symbols with names.
For example the table declaration
table Person T01_LifeExpectancy //EN Life Expectancy
{
{
unit, //EN Total simulated cases
duration(), //EN Total duration
duration()/unit //EN Life expectancy decimals=3
} //EN Quantities
};provides a label for the table itself,
for each of the the three expressions in the table,
and for the expression dimension of the table,
in the EN language of the model.
Notice that the positional location of the table expression dimension is
the trailing closing } of the expression dimension,
after all expressions.
The //LABEL syntax can also supply a label for the dimension of a parameter or table,
or for an expression of a table.
A LABEL comment for a parameter dimension has the form
//LABEL(ParameterName.DimN,LANG) text
where N is {0,1,...,rank-1},
rank is the number of parameter dimensions,
LANG is the language code,
and text is the label.
A LABEL comment for a table dimension has the form
//LABEL(TableName.DimN,LANG) text
where N is {0,1,...,rank},
rank is the number of classificatory dimensions in the table,
LANG is the language code,
and text is the label.
NB: The naming scheme for table dimensions differs from that used for default
External Names.
Unlike external names, it includes the expression dimension of the table in the numbering.
This was to support Modgen's naming scheme for LABEL for table dimensions.
A LABEL comment for a table expression has the form
//LABEL(TableName.ExprN,LANG) text
where N is {0,1,...,expressions},
expressions is the number of expressions in the table,
LANG is the language code,
and text is the label.
Note: The naming scheme for table dimensions differs from that used for default
External Names.
Unlike external names, it includes the expression dimension of the table in the numbering.
A LABEL comment for the expression dimension of a table has the form
TableName.expression_dimension.
Here's the French translation for the labels of the table in the previous example:
//LABEL( T01_LifeExpectancy, FR ) Espérance de vie
//LABEL( T01_LifeExpectancy.Expr0, FR ) Nombre total de cas simulés
//LABEL( T01_LifeExpectancy.Expr1, FR ) Durée totale
//LABEL( T01_LifeExpectancy.Expr2, FR ) Espérance de vie
//LABEL( T01_LifeExpectancy.expression_dimension, FR ) QuantitésA //LABEL can also use an
explicit short name
(if one was provided)
to identify what's being labelled.
The following example adapts a RiskPaths table declaration by supplying an explicit name for
the table dimensions (only one in this table)
and for each of the two table expressions.
table Person TotalPopulationByYear //EN Life table
{
//EN Curtate age
age => integer_age +
*
{
pop => unit, //EN Population start of year
py => duration() //EN Average population in year
} //EN Quantity
};
//LABEL(TotalPopulationByYear,FR) Tableau de vie
//LABEL(TotalPopulationByYear.expression_dimension,FR) QuantitéThe following //LABEL statements provide a French language label
for the table dimensions and expressions using their explicit names.
//LABEL(TotalPopulationByYear.age,FR) Âge intègre
//LABEL(TotalPopulationByYear.pop,FR) Population au début de l'année
//LABEL(TotalPopulationByYear.py,FR) Population moyenne pendant l'annéeHere's another example showing //LABEL comments with
explicit short name
to provide the translation for the dimensions
of the parameter UnionDurationBaseline in RiskPaths
double UnionDurationBaseline
union_order => [UNION_ORDER] //EN Union order
union_dur => [UNION_DURATION]; //EN Union duration
//LABEL(UnionDurationBaseline.union_order,FR) Ordre d'union
//LABEL(UnionDurationBaseline.union_dur,FR) Durée d'unionHere's an example showing //LABEL comments with
explicit short name
to provide the translation for the levels (enumerators)
of classification UnionDurationBaseline in RiskPaths.
classification UNION_ORDER //EN Union order
{
first => UO_FIRST, //EN First union
second => UO_SECOND //EN Second union
};
//LABEL(UNION_ORDER.first,FR) Première
//LABEL(UNION_ORDER.second,FR) DeuxièmeSee the subtopic identifying missing symbol documentation in this topic for functionality to help identify missing labels or translations.
The separator for two-part names in LABEL comments can be either :: or ..
Modgen-specific: Modgen recognizes only . as a separator in two-part names.
Modgen-specific: Modgen treats a LABEL comment with an unrecognized symbol or language as an error,
whereas OpenM++ does not.
OpenM++ has other mechanisms to identify missing or mistyped labels described
below.
[back to symbol documentation in model code].
[back to topic contents]
A model symbol can have an associated descriptive note,
which is given by a NOTE comment in model code.
For example
/*NOTE(Person.FirstPregEvent, EN)
The first pregnancy event. This is the main event of analysis and
censors all future union events.
*/provides a note in the human language EN for the event FirstPregEvent in the Person entity.
The rules for symbol names in NOTE comments are identical to those for
symbol labels.
To be recognized as a human-language note,
there must be no white space between /* and NOTE.
Subsequent white space is optional.
The text of a note can contain formatting indicators which control how the text is rendered. The OpenM++ UI recognizes markdown formatting in a note when it displays it in the UI. For an overview of basic markdown syntax with examples, please see Markdown Basic Syntax
Modgen formatting indicators in notes are described in the Modgen Developer’s Guide in section “Formatting of symbol notes” on page 217. By default, the OpenM++ compiler identifies and converts Modgen formatting indicators to equivalent markdown when it encounters a note in model code.
If a model uses markdown exclusively in notes, this conversion can be disabled using the following statement:
options convert_modgen_note_syntax = off;In practice, markdown and Modgen formatting indicators
can often co-exist in a NOTE comment without interfering.
[back to symbol documentation in model code]
[back to topic contents]
When a model is built, model labels and notes for selected symbols are published to the database, for all human language languages in the model. Labels and notes for model symbols which are not available to the end user when the model is run are not published. This includes parameters and tables suppressed from the model at build time and associated classifications, ranges, and partitions not used by other published symbols. Information on attributes is published only if the model was built with microdata output enabled.
Labels are used extensively in the OpenM++ UI, for example to label parameter and table names, dimensions, and the names of classification levels. Notes for parameters and tables are immediately available in the UI in contest by clicking the information icon. These notes are rendered in the UI using markdown indicators in the note text.
Label and note information for published symbols are in the model database and can be accessed outside of the model.
This information can be extracted using the dbcopy utility,
the oms application,
or (perhaps) using user-written utility functions in a language like R (using oms).
[back to symbol documentation in model code]
[back to topic contents]
A common issue for model developers is to identify undocumented symbols, and, once identified, insert the missing documentation in the model source code.
The OpenM++ compiler supports a family of options to aid that process.
Each member of the family targets a specific kind of missing documentation.
When an option is set to on,
the compiler will generate a warning for each occurrence of missing documentation of that kind.
The warning includes the model code file and line where the symbol was declared,
except for missing translation warnings which instead give the location of the untranslated text.
In an IDE like Visual Studio, double-clicking on the warning in the log window
navigates immediately to that model source code location in the IDE editor.
By default these options are off.
Multiple options can be turned on at the same time.
Here's an example to identify all published parameters in RiskPaths
which have no descriptive note in the model's default language.
Inserting the following line in ompp_framework.ompp
options missing_note_warning_published_parameter = on;causes the compiler to emit warnings like:
1>../code/Unions.mpp(39): warning : missing note for published parameter 'AgeBaselineForm1'
1>../code/Fertility.mpp(21): warning : missing note for published parameter 'AgeBaselinePreg1'
1>../code/Mortality.mpp(25): warning : missing note for published parameter 'CanDie'
1>../code/Mortality.mpp(26): warning : missing note for published parameter 'ProbMort'
1>../code/Unions.mpp(45): warning : missing note for published parameter 'SeparationDurationBaseline'
1>../code/Unions.mpp(42): warning : missing note for published parameter 'UnionDurationBaseline'
1>../code/Fertility.mpp(24): warning : missing note for published parameter 'UnionStatusPreg1'
Here's an example which identifies all published symbols in IDMM
which have a descriptive label or note in the default language,
but whose translation is missing in one of the model's other languages.
The source of IDMM was changed for this example to deliberately create missing translations.
Inserting the following lines in ompp_framework.ompp
options missing_translated_label_warning_published_any = on;
options missing_translated_note_warning_published_any = on;causes the compiler to emit warnings like:
1>../code/HostCore.mpp(89): warning : missing 'FR' translated label for published symbol 'event_count'
1>../code/HostCore.mpp(82): warning : missing 'FR' translated note for published symbol 'NumberOfHosts'
For missing translation warnings, the warning code location is the location of the label or note in the default language, not the location of the symbol declaration. That's so the warning can be used to navigate to the text to be translated.
The missing translated note warning above gave the code location HostCore.mpp(82).
Here's an extract of the code starting at that location (line 82):
/*NOTE(NumberOfHosts,EN)
This number does not change during the simulation
because there are no births, immigration, or deaths.
*/Double-clicking the warning in an IDE navigates directly to that NOTE in the IDE editor.
The associated parameter NumberOfHosts is declared elsewhere.
The following table lists the available options to emit warnings for missing symbol documentation, grouped by category.
| Option | Scope |
|---|---|
| Labels | |
| missing_label_warning_enumeration | classification, classification level, range, partition |
| missing_label_warning_parameter | parameter, parameter group |
| missing_label_warning_table | table, table expression, table group |
| missing_label_warning_attribute | attribute |
| Labels - Published | |
| missing_label_warning_published_enumeration | as above, but only if published |
| missing_label_warning_published_parameter | as above, but only if published |
| missing_label_warning_published_table | as above, but only if published |
| missing_label_warning_published_attribute | as above, but only if published |
| Notes - Published | |
| missing_note_warning_published_parameter | published parameter |
| missing_note_warning_published_table | published table |
| missing_note_warning_published_attribute | published attribute |
| Translated Labels and Notes | |
| missing_translated_label_warning_any | any symbol with an explicit label provided in the model's default language |
| missing_translated_note_warning_any | any symbol with a note provided in the model's default language |
| Translated Labels and Notes - Published | |
| missing_translated_label_warning_published_any | as above, but only for published symbols |
| missing_translated_note_warning_published_any | as above, but only for published symbols |
This subtopic describes doxygen brief descriptions created by the OpenM++ compiler for model symbols. An IDE such as Visual Studio can use these doxygen labels to provide information on model symbols used in C++ model code directly from the code editor. Syntactic islands in model code should be hidden so that doxygen and the IDE can correctly parse the C++ portions of the model project, as described in Model Code - Hiding syntactic islands.
This subtopic contains the following sections:
Doxygen is a widely used tool which generates human-readable hyperlinked HTML documentation for a C++ project. Doxygen fully parses the project's C++ source code for symbols and symbol references, and will incorporate descriptive information provided in specially-structured comments in the C++ source code. Here's an example of a structured doxygen comment in the C++ source code of the OpenM++ compiler:
class CodeBlock : public list<string>
{
public:
...
/**
* Push block of code at the top of the list.
* No indentation applied (assuming zero indent at the top)
*
* @param push_block The block of code to be inserted.
*/
void push_header(const CodeBlock & push_block);
...
};In this example the comment block starting with /** tells doxygen to parse the comment block for structured descriptive text about the C++ symbol whose declaration or definition follows in the code.
Doxygen takes the first line of the comment block as a brief description of the symbol push_header.
Doxygen recognizes several ways to supply information in structured comments.
For example, the following supplies only the doxygen 'brief description' for push_header:
class CodeBlock : public list<string>
{
public:
...
/// Push block of code at the top of the list.
void push_header(const CodeBlock & push_block);
...
};Doxygen is so widely used that some IDEs (e.g. Visual Studio) scan a project's C++ source code for doxygen comments to improve functionality.
For example, in the Visual Studio C++ project for the OpenM++ compiler, hovering the cursor over the symbol push_header in line 347 of the module CodeGen.cpp causes the IDE to display a pop-up which includes information extracted from the doxygen comment for push_header which the IDE found elsewhere in the project:
[back to doxygen brief descriptions for model symbols]
[back to topic contents]
The OpenM++ compiler generates C++ code which declare C++ symbols to implement model symbols declared in syntactic islands in model code.
For example, the model code which declares the unions attribute of the Person entity in the Unions.mpp module in RiskPaths is
actor Person
{
//EN Union counter
int unions = {0};
...The OpenM++ compiler parses this code and creates the following C++ code in om_declarations.h to implement the unions attribute:
class Person : public Entity<Person>
{
public:
...
/// attribute(simple) int: Union counter
unions_om_type unions;
...The OpenM++ compiler generated a line of C++ code to declare unions as well as a preceding doxygen comment containing the doxygen brief description. The doxygen brief description = generated by the OpenM++ compiler has two parts. The first part gives the kind of symbol (a simple attribute) and the the underlying type (int). The second part after the : is the symbol label provided in model code, in the default language of the model (EN for RiskPaths).
If the RiskPaths project is opened in Visual Studio and the model built, hovering the cursor over the symbol unions in line 148 of the module Unions.mpp causes the IDE to display a pop-up for that symbol:
The first line of the popup displays C++ information for unions, which can contain useful information like array shape, C++ type, and the containing class. In this example, the first line gives the kind of entity of the unions attribute, namely Person.
The second line of the popup displays the doxygen brief description for unions generated by the OpenM++ compiler. In this example, it shows that unions is a simple assignable attribute of type int, with label Union counter.
[back to doxygen brief descriptions for model symbols]
[back to topic contents]
The following table shows, for each kind of model symbol, an example from RiskPaths and the doxygen brief description generated by the OpenM++ compiler. The brief description will appear in a pop-up if the cursor is hovered over the symbol in the Visual Studio IDE, as illustrated above.
| Kind of symbol | RiskPaths symbol | Generated brief description | Remarks |
|---|---|---|---|
| attribute | age |
attribute(built-in) Time: age |
The type of the built-in attribute age is Time
|
| attribute | parity_status |
attribute(simple) PARITY_STATE: Parity status derived from the state parity |
parity_status is a simple assignable attribute of type PARITY_STATE (a classification) |
| attribute | integer_age |
attribute(identity) LIFE: Current integer age |
integer_age is an identity attribute whose RHS is the expression COERCE( LIFE, self_scheduling_int(age) )
|
| classification | PARITY_STATE |
Classification {0...1}: Parity status |
The range of possible values is shown. |
| classification level | PS_PREGNANT |
Classification PARITY_STATE(PS_PREGNANT): Pregnant |
The Visual Studio IDE also gives the integer value of the classification level. |
| range | LIFE |
Range {0...100}: Simulated age range |
The range of possible values is shown. |
| partition | AGEINT_STATE |
Partition {0...11}: 2.5 year age intervals |
The range of possible values is shown. |
| entity function | Union1DissolutionEvent |
Implement the event Union1DissolutionEvent when it occurs in the Person entity (model code) |
The label of the function from model code is shown, followed by (model code) to indicate the provenance of the function definition. |
| parameter | ProbMort |
Parameter double: Death probabilities |
The Visual Studio IDE also gives the shape of array parameters which for ProbMort is 101. |
[back to doxygen brief descriptions for model symbols]
[back to topic contents]
The section Background on doxygen mentioned that the doxygen application can generate hyperlinked HTML documentation for a C++ project. After the OpenM++ compiler has run and produced the C++ code to implement a model, a complete C++ project for that model exists. Doxygen can be run with this project as input to create hyperlinked HTML documentation of the C++ code of the model. An example doxygen input file for RiskPaths is located at OM_ROOT/models/RiskPaths.doxyfile. Below is a screenshot of a browser displaying the C++ documentation produced by doxygen for RiskPaths:
The screenshot shows information for the Person member function timeUnion1DissolutionEvent() which is an event time function supplied in model code.
Note that hovering over the symbol union_duration in the model source code gives summary information about the symbol, a bit like the display in the Visual Studio IDE. Note also the References section below the function body, which lists all non-local variables used in the function with each hyperlinked to its section elsewhere in the doxygen-generated HTML documentation.
The documentation generated by doxygen for RiskPaths is based not just on model code. It is also based on C++ code generated by the OpenM++ compiler and fixed framework OpenM++ code. That code is rarely pertinent to a model developer. Future enhancements may remove those superfluous portions from doxygen output and add customized doxygen sections targetted to model developers.