Model Documentation

Home > Model Development Topics > Model Documentation

This topic describes how to incorporate documentation into model code, and how to use that documentation in an IDE or as doxygen-generated HTML content. Portions of this topic are UNDER CONSTRUCTION.

Related topics

• Model Code
• Model Code - Hiding syntactic islands

Topic contents

• Introduction and outline
• Symbol documentation in model code
• Doxygen brief descriptions for model symbols

Introduction and outline

Model documentation has two different audiences: model developers and model users.

Model developers use model documentation to navigate and understand the model's 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 the model's input parameters and output tables. They access model documentation through the model UI or through stand-alone user documentation.

This topic describes

Model documentation has several possible sources:

• Authored documents for developers,
• Authored documents for users,
• Symbol descriptions in model source code LABEL and NOTE statements,
• Model code.

[back to topic contents]

Symbol documentation in model code

This subtopic describes how to specify human-readable documentation of model symbols in model code. It contains the following sections:

• The languages statement
• Symbol labels
• Symbol notes

[back to topic contents]

The languages statement

Each human language supported by a model has an associated language code given in the languages statement, for example

languages
{
    EN, // English
    FR  // Français
};

In this example, the model supports two languages with codes EN and FR. The first language listed in the languages statement is the default language of the model, which in this example is EN.

[back to symbol documentation in model code]
[back to topic contents]

Symbol labels

A model symbol is declared in a syntactic island in model code. A model symbol can have a label for each human language supported by the model. A symbol label can be provided where the symbol is declared, for example

actor Person 
{
    //EN Union counter
    int unions = {0};	
...

In this example, a label is provided for the symbol unions by a comment on the line immediately preceding thesymbol declaration. It can also be provided on the same line as the declaration in a trailing comment.

A symbol label can also be provided in a LABEL comment in model code, for example

//LABEL ( Person.unions, FR ) Compteur d’unions

This example provides the label for the unions attribute in the Person entity for the human language FR.

Sometimes a model code construct has no explicit name but can have a label. 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
    }
};

specifies a label for each of the the three table expressions in the table declaration.

[back to symbol documentation in model code]
[back to topic contents]

Symbol notes

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 text of a note can contain formatting indicators which control how the text is rendered. The OpenM++ UI recognizes markdown formatting indicators 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 indicators when it encounters a note in model code.

If a model uses markdown exclusively in notes, disable this conversion with the following statement:

options convert_modgen_note_syntax = off;

[back to symbol documentation in model code]
[back to topic contents]

Doxygen brief descriptions for model symbols

This subtopic describes the doxygen labels created by the OpenM++ compiler for model symbols. An IDE (e.g. Visual Studio) can use these doxygen labels to improve understanding and navigating C++ model code. It contains the following sections:

• Background on doxygen
• RiskPaths example
• doxygen brief description examples

This subtopic contains the folliwng sections

Background on doxygen

Doxygen is a widely used tool which generates human-readable hyperlinked HTML documentation for a C++ project. It 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. Doxygen takes the first line of the comment block as a brief description of the symbol push_header.

Doxygen recognizes multiple 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]

RiskPaths example

The OpenM++ compiler generates C++ code to declare C++ symbols which implement 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 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 and a preceding doxygen comment with the brief description. The doxygen brief comment 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 : contains the symbol label from model code.

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, or the containing class (entity type). In this example, the first line gives the entity containing unions, namely Person. The second line of the popup displays the doxygen brief description for unions generated by the OpenM++ compiler. In this example, it says 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]

doxygen brief description examples

The following table shows, for each kind of model symbol, an example from RiskPaths.

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]