Update Doxygen style instructions

[ischoegl]

Additional guidance for Doxygen comments should help improve the quality of generated documentation.

Changes proposed in this pull request

The Doxygen C++ style instructions are updated as follows:

C++

Doxygen Comments

• All classes, member variables, and methods should use Doxygen-style comments.
• omments should provide brief and/or detailed descriptions. For example, comment blocks starting with /** or //! use the autobrief feature (comments are split into brief and detailed descriptions at the first dot '.'). For short comments, the C++ style //! is preferred; do not use /// or /*! comment styles in new code.
• Doxygen commands should use the @ prefix instead of \ in order to better differentiate from LaTeX input.
• Whenever appropriate, classes and functions should be added to Doxygen groupings using the @ingroup command. Alternatively, entire code sections can be added using the @addtogroup command, where grouped classes and functions are bracketed by @{ and @}.
• If applicable, new features should reference literature using the @cite command, with BibTeX-style entries added to cantera.bib. Equations can be added using LaTeX input bracketed by @f[ and @f]. In-line math expressions are enclosed by a pair of @f$ directives, for example @f$ \sin(x) @f$.
• Indicate the version added for new functions and classes with an annotation like @since New in %Cantera X.Y where X.Y is the next Cantera version. This notation should also be used to indicate significant changes in behavior.

Style Guide

• Avoid defining non-trivial functions in header files [...]

Also, add instructions on where std:: can be omitted.

If applicable, fill in the issue number this pull request is fixing

Addresses:

• Cantera/enhancements#179

Checklist

• [x] The pull request includes a clear description of this code change
• [x] Commit messages have short titles and reference relevant issues
• [x] Build passes (scons build & scons test) and unit tests address code coverage
• [x] Style & formatting of contributed code follows contributing guidelines
• [x] The pull request is ready for review

[codecov[bot]]

Codecov Report

Merging #1562 (e4b70c3) into main (d01ce5a) will decrease coverage by 0.02%. Report is 30 commits behind head on main. The diff coverage is n/a.

@@            Coverage Diff             @@
##             main    #1562      +/-   ##
==========================================
- Coverage   70.48%   70.47%   -0.02%     
==========================================
  Files         379      379              
  Lines       59093    59093              
  Branches    21230    21230              
==========================================
- Hits        41653    41643      -10     
- Misses      14360    14369       +9     
- Partials     3080     3081       +1     

see 8 files with indirect coverage changes

:mega: We’re building smart automated test selection to slash your CI/CD build times. Learn more