code documentation vs model documentation (docstrings parsers e.g., Doxygen, Javadocs, Sphinx)

[isaacullah]

A pretty common tool for documentation in the FOSS world is Doxygen: https://www.doxygen.nl/index.html

[alee]

So far when we have been discussing documentation we're primarily concerned with the content, not its format. So narrative documentation following the ODD protocol or similar with flow diagrams, decision trees, etc, that presents a 50km / 10km view into the model.

Of course it's great if a model has excellent in-code documentation using a docstrings parser like Doxygen, Javadocs, Sphinx + ReadTheDocs etc and this may indeed be the best way to keep the code tightly coupled & in sync with the documentation. These often need to be combined with dedicated module documentation though, and bear additional costs with their learning curves.

Instead of a listing of tools that may fall out of favor, I think we should be promoting the practice of commenting your code for clarity (e.g., something like every method has comments describing its inputs, outputs, and assumptions), with pointers at literate programming and perhaps an evolving list of useful tools.

[cmbarton]

Actually, that could be one of the fundamental goals and/or minimal standards. There must be sufficient documentation in the code for someone to understand it. As Ross reminded us today, we should probably differentiate between sufficient documentation of the model and documentation of the code.

[platipodium]

Actually, that could be one of the fundamental goals and/or minimal standards. There must be sufficient documentation in the code for someone to understand it. As Ross reminded us today, we should probably differentiate between sufficient documentation of the model and documentation of the code.

• It is good practice in our field to document the model within the code with the help of doxygen
• the documentation of a model could be a scientific paper accompanying the mode or a technical paper, user guide, reference guide; this is clearly not a documentation of the code

Do we want code documentation at all?

Code should be self-documenting as much as possible. Apt variable and function naming, explicit statements, short documentation only where functionality is obscured by code for exceptional reasons.

OMF as an organization should not delve into the code documentaiton but focus on model documentation (which could be in the code), new issue