Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 74.99%. Comparing base (38fbee0) to head (4c1e3eb).
⚠️ Report is 9 commits behind head on main.

@@           Coverage Diff           @@
##             main    #1958   +/-   ##
=======================================
  Coverage   74.99%   74.99%           
=======================================
  Files         450      450           
  Lines       56235    56235           
  Branches     9300     9300           
=======================================
  Hits        42173    42173           
  Misses      10930    10930           
  Partials     3132     3132           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

Thanks for doing this @speth! Definitely an improvement for clarity.

Overall, the length has to meet the 'sweet spot' between being informative (important for CLib) while not being overwhelming in length (see various overviews produced by Doxygen, e.g., https://cantera.org/stable/cxx/modules.html, some of which run three lines)

I think the desired length for the "brief" docstrings depends a little bit on where they end up. In the tabular view of the Modules and Classes lists, some of the longer ones can look a little odd. On the other hand, I don't mind a 2-3 line description appearing on other pages like ones for a specific module or list of class members, as long as it's saying something useful.

Probably the main thing to explain in the developer guide is the fact that the "brief" documentation is used separately from the full docstring in many cases, so it shouldn't just be the start of a longer exposition (the docstring for the spthermo "Species Reference-State Thermodynamic Properties" group is a notable offender in this regard). I can certainly add something to the docs to help cover this.

Overall, the length has to meet the 'sweet spot' between being informative (important for CLib) while not being overwhelming in length (see various overviews produced by Doxygen, e.g., https://cantera.org/stable/cxx/modules.html, some of which run three lines)

I think the desired length for the "brief" docstrings depends a little bit on where they end up. In the tabular view of the Modules and Classes lists, some of the longer ones can look a little odd. On the other hand, I don't mind a 2-3 line description appearing on other pages like ones for a specific module or list of class members, as long as it's saying something useful.

Probably the main thing to explain in the developer guide is the fact that the "brief" documentation is used separately from the full docstring in many cases, so it shouldn't just be the start of a longer exposition (the docstring for the spthermo "Species Reference-State Thermodynamic Properties" group is a notable offender in this regard). I can certainly add something to the docs to help cover this.

Yes - this is a great direction. I don’t think that it’s realistic to capture the \details within sourcegen (see Cantera/enhancements#230), so what you suggest is spot on.

Yes - this is a great direction. I don’t think that it’s realistic to capture the \details within sourcegen (see Cantera/enhancements#230), so what you suggest is spot on.

Done.

As a nit, ending all \brief docstrings with a period . would make sure we're consistent irrespective of Doxygen docstring styles.

Doxygen adds the period in the generated output regardless, and I'm not sure pursuing this level of consistency in the code is worthwhile.