Model Documentation

Home > Model Development Topics > Model Documentation

This topic describes how to author, build and access model documentation.

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
• Target audiences Users and developers
• Building documentation
• Accessing documentation Through the user interface, OpenM++ utilities, or a stand-alone file
• Documentation components Authored and generated
• Documentation editions User edition and developer edition
• Sources of documentation Where documentation comes from
• Exploring internals using doxygen Going down the rabbit hole of OpenM++ internals

Introduction and outline

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]

Target audiences

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

Model users use model documentation to understand how the model works, and the meaning and proper use of the model symbols exposed to them through the user interface, run downloads, or external tools like R or Python.

• input parameters
• output tables
• entity attributes in microdata
• enumerations associated with exposed parameters, tables, and attributes. Typically, only a subset of model symbols are exposed to model users. Model users typically access model documentation through the model UI.

Model developers use model documentation to navigate and understand model code. They access model documentation through the model UI, using an IDE like Visual Studio, or directly from the model source code. Typically, model developers access all of the models symbols, including symbols not directly relevant to model users such as entity sets or source code modules.

[back to topic contents]

Building documentation

Content to follow.

[back to topic contents]

Accessing documentation

Content to follow.

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 topic contents]

Documentation components

Model documentation consists of two components which can work synergistically:

1. A configurable Symbol Reference of generated cross-referenced content on parameters, tables, enumerations, etc.,
2. optional autonomous cross-linked authored model documentation which can include downloadable auxiliary material.

[back to topic contents]

Documentation editions

There are two versions of Model Documentation: user-oriented or developer-oriented, selected at build time using an option.

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.

[back to topic contents]

Sources of documentation

Content to follow.

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

[back to topic contents]

Exploring internals using doxygen

The wiki subtopic Background on doxygen mentions 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]