Model Documentation

Home > Model Development Topics > Model Documentation

This topic describes how to author, incorporate and use 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.

This topic is under construction and/or revision.

Related topics

• Authored Model Documentation: The autonomous authored component of model documentation
• Generated Model Documentation: The symbol reference component of model documentation
• Model Languages: The human languages supported by a model
• Model Symbols: Symbols in model code and in the user interface
• Symbol Labels and Notes: Human-language labels and notes for model symbols

Topic contents

• Introduction and outline
• Model user documentation How model users can access model documentation
• Model documentation produced by doxygen

Introduction and outline

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.

[back to topic contents]

Model user documentation

When a model is built, model labels and notes for selected symbols are published to the database, for all human languages declared 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 context 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]

Doxygen brief descriptions for model 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:

• Background on doxygen
• RiskPaths example
• Examples of doxygen brief descriptions

[back to topic contents]

Background on doxygen

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]

RiskPaths example

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]

Examples of doxygen brief descriptions

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]

Model documentation produced by doxygen

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.

[back to topic contents]