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
```Modelica
parameter Modelica.SIunits.Time tau = 60 "Time constant at nominal flow"
annotation (Dialog(group="Nominal condition"));
```
or use
```Modelica
parameter Types.Dynamics substanceDynamics=energyDynamics "Formulation of substance balance"
* 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
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:
```html
<ul>
<li>
January 1, 2017, by FirstName Surname:<br/>
First implementation (see <ahref=\"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:
```html
<li>
January 1, 2017, by FirstName Surname:<br/>
Brief description of your changes... (see <ahref=\"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://LTT_Adsorption_Library.Media.Functions.CharCurve1Arctan">LTT_Adsorption_Library.Media.Functions.CharCurve1Arctan</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](https://github.com/ibpsa/modelica-ibpsa/wiki/Style-Guide#documentation)
```html
<html>
<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>
<h4>Author Information</h4>
<p>
<ul>
<li>
January 01, 2017, by FirstName Surname:<br/>
Short description of changes.
</li>
</ul>
</p>
</html>
```
which is rendered as:
---------------------
<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>Validation</h4>
<p>
Describe whether the validation was done using analytical validation, comparative model validation or empirical validation.
