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://Annex60/Resources/Images/Fluid/FixedResistances/FixedResistanceDpM.png"/> </p> <p>

Author Information

Add author information to the revision section.

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://Annex60.Fluid.Sensors.Density"> Annex60.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

Suggested Template:

<p> A short introduction. </p> <h4>Main equations</h4> <p> xxx </p> <h4>Assumption 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. </p> <h4>Implementation</h4> <p> xxx </p> <h4>References</h4> <p> xxx </p>

which looks like:

A short introduction.

Main equations

xxx

Assumption 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