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
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.
- 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
- 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
- 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
https://www.doxygen.nl/manual/grouping.html
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
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.