Update doxygen Chemical Kinetics/Numerics Documentation

doc/doxygen/Doxyfile

@@ -866,7 +866,8 @@ INPUT                  = src/base \
                          src/transport \
                          src/zeroD \
                          include \
-                         doc/doxygen
+                         doc/doxygen \
+                         doc/doxygen/mainpage.md
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1027,7 +1028,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE =
+USE_MDFILE_AS_MAINPAGE = mainpage.md
 
 #---------------------------------------------------------------------------
 # Configuration options related to source browsing
@@ -2508,7 +2509,7 @@ PLANTUML_INCLUDE_PATH  =
 # Minimum value: 0, maximum value: 10000, default value: 50.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOT_GRAPH_MAX_NODES    = 50
+DOT_GRAPH_MAX_NODES    = 100
 
 # The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the graphs
 # generated by dot. A depth value of 3 means that only nodes reachable from the

doc/doxygen/mainpage.md

@@ -0,0 +1,23 @@
+# %Cantera C++ Reference
+
+Use the menu at the top to view detailed documentation of the code, or use the
+following shortcuts:
+
+* Overview of [**Cantera Modules**](modules.html)
+* Index of [**Cantera Classes**](classes.html)
+
+A topical overview is provided as follows:
+
+* @ref compobj (interface to %Cantera core objects)
+* @ref thermoprops (temperature, pressure, energy, ...)
+* @ref chemkinetics (reactions, rates of progress, reaction path analysis, ...)
+* @ref tranprops (diffusion, viscosity, thermal conductivity, ...)
+* @ref ZeroD (reactors, walls, flow devices, ...)
+* @ref onedim (flames, flow domains, boundaries, ...)
+* @ref physConstants (universal constants, built into %Cantera for convenience)
+
+For fundamental scientific theory used for the implementation of %Cantera, refer to the
+[Cantera Science Section](https://cantera.org/science/index.html) of the
+[Cantera Website](https://cantera.org).
+
+The %Cantera source code is hosted on [GitHub](https://github.com/Cantera/cantera).

include/cantera/base/Array.h

@@ -25,6 +25,8 @@ namespace Cantera
  *     J(i,j) = data_start + index
  *         i = row
  *         j = column
+ *
+ * @ingroup matrices
  */
 class Array2D
 {

include/cantera/base/ExternalLogger.h

@@ -9,7 +9,7 @@
 namespace Cantera {
 
 //! Logger that delegates to an external source via a callback to produce log output.
-//! @ingroup textlogs
+//! @ingroup logGroup
 class ExternalLogger : public Logger
 {
 public:

include/cantera/base/NoExitLogger.h

@@ -10,7 +10,7 @@
 
 namespace Cantera {
 //! Logger that doesn't exit when an error is thrown.
-//! @ingroup textlogs
+//! @ingroup logGroup
 class NoExitLogger : public Logger {
 public:
     NoExitLogger() {}

include/cantera/base/Solution.h

@@ -17,8 +17,8 @@ class Kinetics;
 class Transport;
 class ExternalHandle;
 
-//! @defgroup compobj Composite Objects
-//! Composite objects create a high-level interface to Cantera's core objects.
+//! @defgroup compobj Objects Representing Phases
+//! High-level interface to %Cantera's core objects.
 
 //! A container class for chemically-reacting solutions.
 /*!

include/cantera/base/ct_defs.h

@@ -47,13 +47,20 @@ using std::function;
 using std::pair;
 
 /*!
- * All physical constants are stored here.
- *
  * @defgroup physConstants Physical Constants
+ * @brief Physical constants used by %Cantera.
+ *
  * %Cantera uses the MKS system of units. The unit for moles
  * is defined to be the kmol. All values of physical constants
  * are consistent with the 2018 CODATA recommendations.
  * @ingroup globalData
+ */
+
+//! @addtogroup physConstants
+//! @{
+
+/**
+ * @name Numerical Constants
  * @{
  */
 
@@ -66,8 +73,8 @@ const double Sqrt2 = 1.41421356237309504880;
 //! @}
 //! @name Defined Constants
 //!
-//! These constants are defined by CODATA to have a particular value.
-//! https://physics.nist.gov/cuu/Constants/index.html
+//! These constants are defined by CODATA to have a particular value; see
+//! [NIST Reference on Constants, Units, and Uncertainty](https://physics.nist.gov/cuu/Constants/index.html).
 //! @{
 
 //! Avogadro's Number \f$ N_{\mathrm{A}} \f$ [number/kmol]
@@ -130,6 +137,9 @@ const double permeability_0 = 2 * fineStructureConstant * Planck / (ElectronChar
 const double epsilon_0 = 1.0 / (lightSpeed * lightSpeed * permeability_0);
 
 //! @}
+
+//! @}
+
 //! @name Thermodynamic Equilibrium Constraints
 //!
 //! Integer numbers representing pairs of thermodynamic variables

include/cantera/base/ctexceptions.h

@@ -2,7 +2,7 @@
  * @file ctexceptions.h
  *   Definitions for the classes that are
  *   thrown when %Cantera experiences an error condition
- *   (also contains errorhandling module text - see \ref errorhandling).
+ *   (also contains errorhandling module text - see \ref errGroup).
  */
 
 // This file is part of Cantera. See License.txt in the top-level directory or
@@ -18,11 +18,14 @@
 namespace Cantera
 {
 
+/**
+ * @defgroup debugGroup Errors & Diagnostics
+*/
+
 /*!
- * @defgroup errorhandling Error Handling
+ * @defgroup errGroup Errors
  *
- * \brief These classes and related functions are used to handle errors and
- *        unknown events within Cantera.
+ * @brief Handling of errors and unknown events within %Cantera.
  *
  * The general idea is that exceptions are thrown using the common base class
  * called CanteraError. Derived types of CanteraError characterize what type of
@@ -47,6 +50,7 @@ namespace Cantera
  * is thrown, with descriptive information indicating where the error occurred.
  * The Assert* checks are skipped if the NDEBUG preprocessor symbol is defined,
  * for example with the compiler option -DNDEBUG.
+ * @ingroup debugGroup
  */
 
 
@@ -56,7 +60,7 @@ namespace Cantera
  * from std::exception so that normal error handling operations from
  * applications may automatically handle the errors in their own way.
  *
- * @ingroup errorhandling
+ * @ingroup errGroup
  */
 class CanteraError : public std::exception
 {
@@ -126,7 +130,7 @@ class CanteraError : public std::exception
  * This error is thrown if a supplied length to a vector supplied to Cantera is
  * too small.
  *
- * @ingroup errorhandling
+ * @ingroup errGroup
  */
 class ArraySizeError : public CanteraError
 {
@@ -156,7 +160,7 @@ class ArraySizeError : public CanteraError
 
 //! An array index is out of range.
 /*!
- *  @ingroup errorhandling
+ *  @ingroup errGroup
  */
 class IndexError : public CanteraError
 {
@@ -187,6 +191,7 @@ class IndexError : public CanteraError
 };
 
 //! An error indicating that an unimplemented function has been called
+//! @ingroup errGroup
 class NotImplementedError : public CanteraError
 {
 public:
@@ -238,7 +243,7 @@ class NotImplementedError : public CanteraError
  *
  * @param expr  Boolean expression that must be true
  *
- * @ingroup errorhandling
+ * @ingroup errGroup
  */
 #ifndef AssertTrace
 #  define AssertTrace(expr)  ((expr) ? (void) 0 : throw CanteraError(STR_TRACE, std::string("failed assert: ") + #expr))
@@ -252,7 +257,7 @@ class NotImplementedError : public CanteraError
  * @param expr  Boolean expression that must be true
  * @param procedure  Character string or std:string expression indicating the
  *     procedure where the assertion failed
- * @ingroup errorhandling
+ * @ingroup errGroup
  */
 #ifndef AssertThrow
 #  define AssertThrow(expr, procedure)   ((expr) ? (void) 0 : throw CanteraError(procedure, std::string("failed assert: ") + #expr))
@@ -269,7 +274,7 @@ class NotImplementedError : public CanteraError
  * Additional arguments are passed on to the constructor for CanteraError to
  * generate a formatted error message.
  *
- * @ingroup errorhandling
+ * @ingroup errGroup
  */
 #ifndef AssertThrowMsg
 #  define AssertThrowMsg(expr, procedure, ...)  ((expr) ? (void) 0 : throw CanteraError(procedure + std::string(":\nfailed assert: \"") + std::string(#expr) + std::string("\""), __VA_ARGS__))
@@ -278,6 +283,7 @@ class NotImplementedError : public CanteraError
 #endif
 
 //! Throw an exception if the specified exception is not a finite number.
+//! @ingroup errGroup
 #ifndef AssertFinite
 #  define AssertFinite(expr, procedure, ...) AssertThrowMsg(expr < BigNumber && expr > -BigNumber, procedure, __VA_ARGS__)
 #endif