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 Use cases for model documentation: end users, model developers, content developers
• Model documentation components and structure Autonomous authored documentation and the generated Symbol Reference
• Building model documentation How to build model documentation and control its content
• Using model documentation Through the user interface, OpenM++ utilities, or a stand-alone file
• Sources of documentation Where documentation comes from
• Exploring internals using doxygen Going down the rabbit hole of OpenM++ internals

Introduction and outline

Examples use the RiskPaths model which is included in OpenM++ distributions.

[back to topic contents]

Target audiences

Model documentation has several different audiences:

• model users
• model developers
• content developers

Model users

Model users need to understand the model in general, including its

• substance
• methods
• intended uses
• limitations

Users who run the model also need to understand the meaning and proper use of the model symbols exposed through the user interface, run downloads, or through external tools like R or Python. Those symbols consist of exposed

• 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 access model documentation through the model UI, or perhaps through a stand-alone PDF or HTML 'User Edition' file built and provided by a model developer.

[back to target audiences]
[back to topic contents]

Model developers

Model developers need to understand all aspects of the model:

• probe the model to understand or debug issues
• understand internal relationships and dependencies among symbols and model code
• develop new functionality coherent with existing code

Model developers access model documentation through the model UI, or perhaps by directly opening a previously built HTML 'Developer Edition' file. They may also access model documentation through an IDE when working with 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, functions, and model code modules, as well as parameters, tables, entity attributes, and enumerations not visible to users in the UI.

[back to target audiences]
[back to topic contents]

Content developers

Content developers use model documentation to review and author model documentation, focusing on

• introducing the model to new users
• presenting the subject matter of the model
• reviewing the coherence and coverage of model documentation

[back to target audiences]
[back to topic contents]

Model documentation components and structure

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., available in either a User Edition (default) or a Developer Edition.
2. Optional autonomous cross-linked authored model documentation which can include downloadable auxiliary material.

Both components consist of a collection of topics, where each topic can be the target of a link from elsewhere in the model documentation.

[back to topic contents]

Building model documentation

By default, model documentation is built and assembled as an intrinsic step in the model build. Building model documentation for a large model can take a noticeable amount of time, so a model developer might want to turn it off to speed development cycles, and turn it back on from time to time to refresh the Developer Edition of the Symbol Reference for their own use, or to build a final User Edition version of model documentation for a model release.

In Visual Studio, the Model project OpenM++ property page contains an option to turn building model documentation on or off:

In development environments using make, setting the MODEL_DOC_DISABLE variable will disable the model documentation build step.

The most recently built version of model documentation will continue to be available from the model UI, even after the model is rebuilt. If model documentation is disabled in the build, its content may not reflect the model code, and it may differ from context-sensitive help displayed in the UI.

Symbol labels and notes for symbols exposed to the user through the UI are always published, independent of build settings for model documentation. The model UI uses those labels and notes to display up-to-date context-specific information on exposed parameters, tables, attributes, and for any enumerations used by those exposed symbols.

Which of the two documentation components are built and assembled into the final model documentation can be controlled using the following options in model code, e.g. in the model code module code/ompp_options.ompp:

options authored_documentation = on;
options generated_documentation = on;

By default, both options are on. If a model has no autonomous authored content, by default model documentation consists of only the generated Symbol Reference component.

The content of the generated Symbol Reference, including the choice of User Edition or Developer Edition, can be controlled through options in model code, as described in customizing the Symbol Reference.

[back to topic contents]

Using model documentation

For each model language, the two components of model documentation are built and assembled into one .html file for each model language, to which the model UI links when a user requests model documentation by clicking the 'book' icon. The 'book' icon is available in several places in the UI:

• the landing page which lists the available models
• the title bar displayed at the top of the UI
• the information pop-up for a symbol

From a browser, the entire model documentation can be searched using the browser's Find on page command or Ctrl-F key combination to identify all occurrences of a word or phrase.

From a browser, the model documentation can be converted from .html to .pdf format by invoking the browser's Print command or Ctrl-P key combination and selecting pdf as the target printer. Model documentation is designed so that each topic starts on a new page in the resulting .pdf file (only tested on the Microsoft Edge browser).

The output .html files containing the model documentation can also be accessed directly in the file system used to build the model. They are located in a doc sub-directory of the bin directory of the model (not to be confused with the doc sub-directory of the model root used for authored content). For RiskPaths, the files are

RiskPaths/.../bin/doc/RiskPaths.doc.EN.html (English)
and
RiskPaths/.../bin/doc/RiskPaths.doc.FR.html (French)

The model documentation build also writes a json configuration file to tell the OpenM++ UI which file is to be used for which model language when a user requests model documentation. For RiskPaths, the file is RiskPaths/.../bin/RiskPaths.extra.json, and its contents look like this:

{
"ModelDoc": [
   {
   "LangCode": "EN",
   "Link": "RiskPaths.doc.EN.html"
   },
   {
   "LangCode": "FR",
   "Link": "RiskPaths.doc.FR.html"
   }
]
}

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).

The generated stand-alone documentation, in each of the model's supported languages, is written to files in the folder...

[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]