ED2 Documentation with Doxygen

In order to generate code documentation with oxygen for ED2, simply install Doxygen on your working environment, go to the /ED/Doc folder and execute

doxygen Doxyfile

The most updated version of the documentation can be found here, where you can search variables/functions/subroutines/modules and their associated annotations (if written following Doxygen styles).

Some extended information on Doxygen is listed below

General Doxygen Info

The following info may be helpful for familiarizing one's self with Doxygen, an auto-documentation program which utilizes a system of tags in source code. To tag a subroutine in the ED model as required above, try taking ed_model.f90 as a template and/or browsing the first few links below.

NASA Doxygen Quickstart:

• https://modelingguru.nasa.gov/docs/DOC-1811
• Doxygen Keywords: https://www.doxygen.nl/manual/commands.html
• Doxygen Documentation: https://www.doxygen.nl/manual/index.html

More General Info

• http://www.msg.chem.iastate.edu/gamess/DoxygenRules.oct10.pdf
• http://stackoverflow.com/questions/51667/best-tips-for-documenting-code-using-doxygen
• https://www.rosettacommons.org/manuals/rosetta3.2_user_guide/doxygen_tips.html

Mainpage & custom file construction links:

• http://stackoverflow.com/questions/10136201/mainpage-in-doxygen-documentation?rq=1
• http://stackoverflow.com/questions/9502426/how-to-make-an-introduction-page-with-doxygen
• http://stackoverflow.com/questions/13368350/use-the-readme-md-file-as-main-page-in-doxygen
• http://stackoverflow.com/questions/3052036/how-to-include-custom-files-in-doxygen/6336368#6336368
• http://stackoverflow.com/questions/2337307/doxygen-adding-a-custom-link-under-the-related-pages-section

Using grouping:

https://www.doxygen.nl/manual/grouping.html

Configuration:

https://www.doxygen.nl/manual/starting.html#step1

Documentation generated by doxygen can be accessed (locally) on a machine with this repository under Doc/html/index.html

Doxygen and Git Commits:

In order for further pull requests to the mainline to be accepted, modified subroutines will require the following doxygen tags:

• Brief subroutine descriptions using the brief tag
• Detailed subroutine descriptions using the details tag
• Subroutine authorship statements using author tag
• Inline subroutine argument descriptions using "!< comment"

Please do not commit changes to model code and documentation together if high numbers of documentation files have been modified. Instead ...

• Submit a pull request to the mainline with a comment that docs needs regeneration or
• Seperately pull request code changes and documentation updates

Finally, please note:

• Seperating code and doc changes will make inter-branch comparison much easier when many files are modified.
• Regenerating documentation may produce many spurious line-end encoding differences which git will pick up on. "git add"-ing such files will often return them to the repo standard CRLF, and they will cease to be listed as modified.