Documentation

Note, that without a good documentation, your code is very likely to be unreadable even for yourself in a year from now. So spend some time on documentation, as long as you still have an idea, what your code is doing.

Description String

Add a description string to all parameters and variables, including protected ones.

Graphical Documentation of Variables

Group similar variables using the group and tab annotation. For example use

parameter Modelica.SIunits.Time tau = 60 "Time constant at nominal flow"    
annotation (Dialog(group="Nominal condition"));

or use

parameter Types.Dynamics substanceDynamics=energyDynamics "Formulation of substance balance"   
annotation(Evaluate=true, Dialog(tab = "Assumptions", group="Dynamics"));

Info Section

Add model documentation to the infosection.

• To document equations, use the format: <p> The polynomial has the form </p> <p align="center" style="font-style:italic;"> y = a<sub>1</sub> + a<sub>2</sub> x + a<sub>3</sub> x<sup>2</sup> + ..., </p> <p> where <i>a<sub>1</sub></i> is ... which looks like:

The polynomial has the form

y = a₁ + a₂ x + a₃ x² + ...,

where a₁ is ...

• To denote time derivatives, such as for mass flow rate, use <code>m&#775;</code> which looks like ṁ.

• To format tables, use following format. Each table must have set a summary attribute. <p> <table summary="summary" border="0" cellspacing="0" cellpadding="2" style="border-collapse:collapse;"> <tr><th>Header 1</th> <th>Header 2</th> </tr> <tr><td>Data 1</td> <td>Data 2</td> </tr> </table> </p> which looks like:

Header 1	Header 2
Data 1	Data 2

• To include figures, place the figure into a directory in AixLib/Resources/Images/ that has the same name as the full package. Each figure must have set an alt attribute. To create new figures, put the source file for the figure, preferably in svg format, in the same directory as the png file. svg files can be created with http://inkscape.org/, which works on any operating system. See for example the file in Resources/Images/Examples/Tutorial/SpaceCooling/schematics.svg. For example, use </p> <p align="center"> <img alt="Image of ..." src="modelica://AixLib/Resources/Images/Fluid/FixedResistances/FixedResistanceDpM.png"/> </p> <p>

Author Information

When making a change to a model or adding a new model, please add a brief note into the model's revision history. If you added a new model, please use the following template to add to the model's revision section:

<ul>
  <li>
  January 1, 2017, by FirstName Surname:<br/>
  First implementation (see <a href=\"https://github.com/RWTH-EBC/AixLib/issues/XXX\">issue XXX</a>).
  </li>
</ul>

Please replace the correct date, FirstName and Surname with your name (if you want to stay anonymous, feel free to use your GitHub Nickname or similar) and XXX with the corresponding issue number.

If you modified an existing model, just add a new list entry with a brief description of what you did:

  <li>
  January 1, 2017, by FirstName Surname:<br/>
  Brief description of your changes... (see <a href=\"https://github.com/RWTH-EBC/AixLib/issues/XXX\">issue XXX</a>).
  </li>

In case you modified an existing model in which the previous entries did not use these templates, feel free to reformat them accordingly.

Spell check

Run a spell check.

Level of Headings

Start headings with <h4>.

Hyperlinks

Add hyperlinks to other models using their full name, i.e. use

see <a href=\modelica://AixLib.Fluid.Sensors.Density\">AixLib.Fluid.Sensors.Density</a>

References

To refer to names of parameters or variables in the documentation and revision sections, use the syntax <code>...</code>. Do not use <tt>...</tt>.

Default Component Name

Add a default component name, such as annotation(defaultComponentName="senDen", ...), to objects that will be used as drag and drop elements, as this automatically assigns them this name

Line Length

Keep the line length to no more than around 80 characters.

User Guide

For complex packages, provide a User's Guide, and reference the User's Guide in Annex60.UsersGuide.

FixMe

Use the string "fixme" within development branches to mark passages, that still needs to be revises (i.e. to improve code, to fix bugs, ...). Before merging a branch into the master, all "fixme"s must be removed. Within the master, no "fixme" shall exist.

HTML-Tags

Always use html-tags with lower case.

Template

All our models should use parts or all of the following template as applicable. This template is based on the template of the IBPSA Modelica Library

(Prefer to write your documentation in markdown and only copy the rendered html? Here's the template in markdown)

<p>
A short introduction.
</p>
<h4>Main equations</h4>
<p>
xxx
</p>
<h4>Assumptions and limitations</h4>
<p>
xxx
</p>
<h4>Typical use and important parameters</h4>
<p>
xxx
</p>
<h4>Options</h4>
<p>
xxx
</p>
<h4>Dynamics</h4>
<p>
Describe which states and dynamics are present in the model
and which parameters may be used to influence them.
This need not be added in partial classes.
</p>
<h4>Validation</h4>
<p>
Describe whether the validation was done using
analytical validation, comparative model validation
or empirical validation.
</p>
<h4>Implementation</h4>
<p>
xxx
</p>
<h4>References</h4>
<p>
xxx
</p>

which is rendered as:

A short introduction.

Main equations

xxx

Assumptions and limitations

xxx

Typical use and important parameters

xxx

Options

xxx

Validation

Describe whether the validation was done using analytical validation, comparative model validation or empirical validation.

Implementation

xxx

References

xxx

---