Annotations

Annotations are meta data expressed in a Mosel source file (model or package) that are stored in the resulting BIM file after compilation. This additional information is either global or associated with public globally declared objects (including subroutines). Annotations do not have any direct impact on the model itself as they are treated like comments. Typical uses of annotations include model documentation or application configuration information.

Mosel annotations have the following format:

• a single-line annotation starts with '!@' and a name

  !@doc.name This is my document title

• multi-line annotations are surrounded by '(!@' and '!)'

  (!@mynote Some annotation text.
  Another line of text.
  !)

• '!@' is followed by the annotation name (identifier)
  • no space between '!' and '@' characters
  • space is allowed between '@' and the name
• value assignment operators are ' ' (space), ':', or '='
  • no space between annotation name and operator

  !@mynote contents for 'mynote'
  !@ another=contents of 'another'
  !@third: contents of 'third'

• association with symbols:

  !@mynote This annotation is applied to all objects declared below
  public declarations
    val: integer            !@doc.descr Explanation of 'val'
    !@doc.descr Text associated with 'msg'
    msg: string             ! A standard comment
    !@mynote2 This annotation is ignored (no associated object)
  end-declarations

Annotations are organized in categories. A category groups a set of annotations and other categories (or sub-categories). For example

doc.name

will be used to select the annotation name member of the doc category. Predefined category names include mc (Mosel compiler) and doc (model documentation). Models can also define/employ new annotations and categories—these must be valid Mosel identifiers, that is, their names can only use alpha-numeric symbols and '_'.

We show some examples of the doc category in Section moseldoc: Generating model documentation below. The category mc is used to pass information to the compiler during the compilation, including the (optional) declaration of new annotations with the mc.def annotation or the definition of aliases, such as

!@mc.def descr alias doc.descr insight.descr

that redirects onto two different annotations (see section 'Annotations' of the Mosel Language Reference Manual for further detail).