Hybrid Software Commentary Standard - idaholab/HYBRID GitHub Wiki

Each folder has a Readme.md, 00Readme.txt, or Readme.rst file that explains the contents of each directory. The primary section of the hybrid repository is the physical modelica models. Therefore, an in-depth conversation on the Modelica documentation is necessary.

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

2. 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"));
   

3. Add model documentation to the info section. 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 ...
   

   To denote time derivatives, such as mass flow rate, use

    <code>m&#775;</code>.
   

   To refer to parameters of the model, use the format

    To linearize the equation, set <code>linearize=true</code>.
   

   To format tables, use

    <p>
    <table summary=\"summary\" border=\"1\" 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>
   

   To include figures, place the figure into a directory in Electrolysis/Resources/Images/ that has the same name as the full package. For example, use

    </p>
    <p align=\"center\">
    <img alt=\"Image\"
    src=\"modelica://Electrolysis/Resources/Images/Electrolyzers/Electrolyzer.png\"/>
    </p>
    <p>
   

   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.

4. Add author information to the revision section.

5. Run a spell check.

6. Start headings with <h4>.

7. Add hyperlinks to other models using their full name. For example, use

    See <a href =\"modelica://Modelica.Fluid.Vessels.BaseClasses.VesselPortsData\"> Fluid.Vessels.BaseClasses.VesselPortsData </a>.
   

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

9. Always use lower case html tags.