[Units] Improve docstrings

interfaces/cython/cantera/_cantera.pxd

@@ -647,7 +647,7 @@ cdef extern from "cantera/base/YamlWriter.h" namespace "Cantera":
         void toYamlFile(string&) except +translate_exception
         void setPrecision(int)
         void skipUserDefined(cbool)
-        void setUnitSystem(CxxUnitSystem) except +translate_exception
+        void setUnitSystem(CxxUnitSystem&) except +translate_exception
 
 cdef extern from "cantera/equil/MultiPhase.h" namespace "Cantera":
     cdef cppclass CxxMultiPhase "Cantera::MultiPhase":

interfaces/cython/cantera/units.pyx

@@ -31,17 +31,13 @@ cdef class Units:
 
 cdef class UnitSystem:
     """
-    Unit conversion utility
+    Unit system used for YAML input and output.
 
-    Provides functions for converting dimensional values from a given unit system.
-    The main use is for converting values specified in input files to Cantera's
+    The `UnitSystem` class is used to specify dimensional values for a given unit
+    system. The main use is for converting values specified in input files to Cantera's
     native unit system, which is SI units except for the use of kmol as the base
     unit of quantity, i.e. kilogram, meter, second, kelvin, ampere, and kmol.
 
-    Special functions for converting activation energies allow these values to be
-    expressed as either energy per quantity, energy (e.g. eV), or temperature by
-    applying a factor of the Avogadro number or the gas constant where needed.
-
     The default unit system used by Cantera is SI+kmol::
 
         ct.UnitSystem({

src/base/Units.cpp

@@ -339,7 +339,9 @@ std::map<std::string, std::string> UnitSystem::defaults() const
         {"activation-energy", Units(m_activation_energy_factor, 1, 2, -2, 0, 0, -1)},
     };
 
-    // Retrieve known units (if applicable)
+    // Retrieve known units
+    // (replace combinations of base units used by the default system by by known
+    // secondary units, e.g. 'kg / m / s^2' is replaced by 'Pa')
     std::map<std::string, std::string> out;
     for (const auto& unit : units) {
         out[unit.first] = unit.second.str();
@@ -351,12 +353,14 @@ std::map<std::string, std::string> UnitSystem::defaults() const
         }
     }
 
-    // Overwrite entries that have buffered defaults
+    // Overwrite entries that have non-unity conversion factors
+    // (replace units deviating from default unit system with buffered values)
     for (const auto& defaults : m_defaults) {
         out[defaults.first] = defaults.second;
     }
 
     // Ensure compact output for activation energy
+    // (use appropriate abbreviations for activation energy)
     if (m_defaults.find("activation-energy") == m_defaults.end()) {
         out["activation-energy"] = fmt::format(
             "{} / {}", out["energy"], out["quantity"]);