Model Symbols

Home > Model Development Topics > Model Symbols

Symbols in model code and in the user interface.

This topic is under construction and/or revision.

Related topics

• Model Documentation: Home topic on model documentation
• Symbol Labels and Notes: Human-language labels and notes for model symbols

Topic contents

• Introduction and outline
• Doxygen brief descriptions for model symbols

Introduction and outline

Content to follow.

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