Generated Model Documentation

Home > Model Development Topics > Generated Model Documentation

This topic describes one of the two components of model documentation: the generated Symbol Reference.

This topic is under construction and/or revision.

Related topics

• Model Documentation: Home topic on model documentation
• Authored Model Documentation: The autonomous authored component of model documentation
• 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
• Symbol Reference - User Edition
• Symbol Reference - Developer Edition
• Customizing the Symbol Reference
• Navigation Aid Topics

Introduction and outline

Model Documentation has two components: An autonomous authored component and a generated Symbol Reference component. This topic describes the latter.

Human-language labels and notes for model symbols are combined with symbol metadata and cross-reference information to produce a Symbol Reference for a model. There are two versions of the Symbol Reference, one targeted to model users and one to model developers. Each version can be customized using options statements in model code.

The User Edition of the Symbol Reference is targeted to model users. It documents all symbols exposed in the UI and deliberately excludes symbols not exposed in the UI. For example, a parameter deliberately suppressed from the UI by its absence in parameters_retain statements in model code will be absent in the User Edition of the Symbol Reference. Symbols which are used only in model code are also absent, as are cross references for such symbols.

The Developer Edition of the Symbol Reference is targeted to model developers. It includes all content in the User Edition, and adds symbols and topics not exposed in the UI. For example, the Developer Edition includes a topic which lists all model code modules, as well as a topic for each module.

Independent of the Symbol Reference, labels and notes for all symbols exposed in the model UI are published to the model database, for all human languages declared in the model.

The Symbol Reference component of Model Documentation can be disabled by an option in model code:

options generated_documentation = off;

[back to topic contents]

Symbol Reference - User Edition

The User Edition of the Symbol Reference is perhaps best explored interactively. The model code options in RiskPaths model turn Developer Edition on, so those options must be turned off to explore the User Edition version of the Symbol Reference. To do that, open the RiskPaths project and turn off Developer Edition by commenting the following 2 lines in RiskPaths/code/ompp_options.ompp:

options symref_developer_edition = on;       // Comment this line to produce the User Edition.
options symref_unpublished_symbols = on;     // Comment this line to remove symbols which are absent from the UI.

Next, rebuild, run, and click the 'book' icon, and from the RiskPaths Home topic click Symbol Reference.

By default, a model's Symbol Reference documents only symbols which are exposed to users. Labels and notes for model symbols which are not available to users when the model is run are not published, and are not present in the Symbol Reference. 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, i.e. mode code contains the statement

options microdata_output = on;

Status of symbol topics in the User Edition of the Symbol Reference:

Symbol kind	Status
parameter	Complete
table	Complete
enumeration	Complete
attribute	incomplete

[back to topic contents]

Symbol Reference - Developer Edition

The Developer Edition of the Symbol Reference is best understood by exploring it interactively. To do so, open the RiskPaths project, build, run, and click the 'book' icon. From the RiskPaths Home topic, click Symbol Reference.

The Developer Edition version of the Symbol Reference is activated by including the following option statement in model code, for example in the model code module code/ompp_options.ompp:

options symref_developer_edition = on;       // Comment this line for production models.

The Developer Edition of the Symbol Reference includes all content in the User Edition as well as

• A topic for each model code module, with a table listing all symbols declared in the module.
• An alphabetic list of model code modules in the Navigation Aids table in the main topic.
• For each symbol topic, the summary line includes the module in which the symbol was declared.
• For each symbol topic, three cross-reference tables listing entity functions, global functions, and identity attributes which use the symbol.

The Developer Edition of the Symbol Reference does not, by default, include unpublished parameters, tables, and enumerations, i.e. those which are not exposed to users. To include them, add the following option statement to model code:

options symref_unpublished_symbols = on;       // Comment this line for production models.

[back to topic contents]

Customizing the Symbol Reference

The following table lists options which customize the content of the Symbol Reference.

Option	Default	Effect if changed from default
symref_developer_edition	off	Turns on symbols not exposed to users and appends "(Developer Edition)" to title in main topic.
symref_unpublished_symbols	on	Turns off unpublished symbols, e.g. those absent due to parameters_retain or tables_retain statements in model code.
symref_main_topic	on	Turns off the main topic including navigation aid table.
symref_model_symbol	on	Turns off the topic for the unique model symbol, if declared in the model.
symref_parameters_alphabetic	on	Turns off the parameters alphabetic list topic.
symref_parameter_major_groups	on	Turns off the parameter major groups topic.
symref_parameter_hierarchy	on	Turns off the parameter hierarchy topic and parameter hierarchy breadcrumbs in individual parameter topics.
symref_topic_parameters	on	Turns off individual parameter topics and parameter cross-reference sections in other topics.
symref_tables_alphabetic	on	Turns off the tables alphabetic list topic.
symref_table_major_groups	on	Turns off the table major groups topic.
symref_table_hierarchy	on	Turns off the table hierarchy topic and table hierarchy breadcrumbs in individual table topics.
symref_topic_tables	on	Turns off individual table topics and table cross-reference sections in other topics.
symref_enumerations_alphabetic	on	Turns off the enumerations alphabetic list topic.
symref_topic_enumerations	on	Turns off individual enumeration topics and enumeration cross-reference sections in other topics.
symref_global_functions	on	Turns off global function cross-reference sections in other topics.
symref_entity_functions	on	Turns off entity function cross-reference sections in other topics.
symref_identity_attributes	on	Turns off identity attribute cross-reference sections in other topics.
symref_topic_modules	on	Turns off module alphabetic list, module individual topics, and module cross-reference sections in other topics.
symref_topic_modules_use	off	Includes use modules as well as model code modules (if modules are turned on).
symref_topic_modules_symbols_declared	on	Turns off the alphabetic "symbols declared" section in individual module topics.
symref_attributes_alphabetic	on	Turns off the attributes alphabetic list topic.
symref_topic_attributes	on	Turns off attribute individual topics.
symref_topic_attributes_internal	off	Turns on attribute individual topics for internally-generated attributes.
symref_topic_notes	on	Turns off the note sections of all individual symbol topics.
symref_topic_notes_early	on	Places notes after other sections in individual symbol topics.
symref_topic_note_heading	on	Suppresses the Note: heading in individual symbol topics.

[back to topic contents]

Navigation Aid Topics

The following table lists navigation aid topics in the Symbol Reference.

Navigation aid	Topic name	Description and notes
Symbol Reference	symbol-reference	The Symbol Reference main topic.
Parameters in alphabetic order	parameters-alphabetic
Parameter hierarchy	parameter-hierarchy	Present if the model has at least one published parameter group. May contain a trailing 'Orphan parameters' group.
Parameter major groups	parameter-major_groups	Present if parameter hierarchy present.
Tables in alphabetic order	tables-alphabetic
Table hierarchy	table-hierarchy	Present if the model has at least one published table group. May contain a trailing 'Orphan tables' group.
Table major groups	table-major-groups	Present if table hierarchy present.
Enumerations in alphabetic order	enumerations-alphabetic
Modules in alphabetic order	modules-alphabetic
Attributes in alphabetic order	attributes-alphabetic

Note that derived parameters published as tables group with tables in the navigation aid topics, not with parameters.

[back to topic contents]