Doxygen comments in source code

[adcroft]

We have already agreed that we will use doxygen for documenting MOM6 APIs. Several comments (pun intended):

• The current coverage of doxygen comments in the code is quite low - you can see a recently generated documentation at http://adcroft.github.io/MOM6/APIs/namespaces.html where you'll note we only have a dozen fully doxygenized modules.
• We need to get into the habit of using doxygen style comments for any newly written functions.
• As a rule, we don't like answer-changing commits to be mixed up with aesthetic changes or re-factoring...
  • ...however, for non-answer changing commits, I suggest we take the extra minute to update the comments for routines that we're updating to further our progress towards documenting the code.
• We want updated comments to be correct. If in doubt we will still be better off with a WAG so I suggest using the \todo or \attention commands to label something as uncertain.
• We haven't completely figured out style/rules for doxygen comments. To that end:
  • I've created a wiki page with short examples of doxygen markup to use as a cheat sheet;
  • The wiki page also has the instructions at the bottom for generating the html documentation (which is best done on your local machine so you can easily view the results);
  • Any course changing discussions about style should happen sooner rather than later.
• My personal preference for camel case looks horrible in doxygen (because doxygen treats FORTRAN as the case insensitive language that it is). This alone has convinced me to return to snake case. I am now taking two extra minutes to both doxygenize and turn camels into snakes.

(Any devs feeling like they want to up their contributor standing could see this as an opportunity. 😉 )