Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Doxygen formatting #1557

Merged
merged 3 commits into from
Aug 1, 2023
Merged

Doxygen formatting #1557

merged 3 commits into from
Aug 1, 2023

Conversation

ischoegl
Copy link
Member

@ischoegl ischoegl commented Jul 28, 2023

Changes proposed in this pull request

  • Add some Doxygen recommendations to CONTRIBUTING.md
  • Avoid creating unnecessary links to Cantera namespace
  • Use consistent Doxygen @ref command (about half of instances used \ref)
  • Switch from \ to @ for less commonly used Doxygen commands

Doxygen supports commands that either start with \ or @. As the former is also used for LaTeX, using the latter will better differentiate syntax. It is noted that this PR does not replace instances of \f[/\f] and \f$, as this would create significantly more churn (see #1558).

As an aside, there is a good "perfectionist" Doxygen style guide here. Note that I don't think it makes sense to be this rigid, but it was interesting enough to post a link here.

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

Partially Cantera/enhancements#179

Checklist

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

@ischoegl ischoegl marked this pull request as ready for review July 28, 2023 19:04
@ischoegl ischoegl requested a review from a team July 28, 2023 19:04
@codecov
Copy link

codecov bot commented Jul 28, 2023

Codecov Report

Merging #1557 (44049d5) into main (d01ce5a) will decrease coverage by 0.02%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##             main    #1557      +/-   ##
==========================================
- 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     
Files Changed Coverage Δ
include/cantera/base/AnyMap.h 80.00% <ø> (ø)
include/cantera/base/ExtensionManager.h 27.27% <ø> (ø)
include/cantera/base/ExtensionManagerFactory.h 100.00% <ø> (ø)
include/cantera/base/Solution.h 87.50% <ø> (ø)
include/cantera/base/SolutionArray.h 94.44% <ø> (ø)
include/cantera/base/Units.h 90.90% <ø> (ø)
include/cantera/base/ctexceptions.h 60.86% <ø> (ø)
include/cantera/base/global.h 81.81% <ø> (ø)
include/cantera/base/logger.h 78.57% <ø> (ø)
include/cantera/base/utilities.h 96.66% <ø> (ø)
... and 121 more

... and 3 files with indirect coverage changes

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

Writing %Cantera rather than Cantera in Doxygen docstrings
avoids creating a link to the Cantera namespace in the
generated documentation.
Use @ref rather than \ref for all cross-references (about half
of the references used one or the other style); also, replace
backslash in a couple of other less commonly used Doxygen commands.
@speth speth merged commit 5b07e7f into Cantera:main Aug 1, 2023
39 of 40 checks passed
@ischoegl ischoegl deleted the doxygen-fixes branch August 1, 2023 15:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
No open projects
Development

Successfully merging this pull request may close these issues.

2 participants