Model Symbols - openmpp/openmpp.github.io GitHub Wiki

Home > Model Development Topics > Model Symbols

Symbols in model code and in the user interface.

This topic is under construction and/or revision.

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

• Introduction and outline
• Doxygen brief descriptions for model symbols

Content to follow.

[back to topic contents]

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]

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]

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]

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.

[back to doxygen brief descriptions for model symbols]
[back to topic contents]