[docs] Improve doxygen documentation for composite objects

include/cantera/base/Interface.h

@@ -13,7 +13,12 @@
 namespace Cantera
 {
 
-//! A container class holding managers for all pieces defining an interface
+//! A container class for chemically-reacting interfaces.
+/*!
+ * Instances of class Interface represent reacting 2D surfaces between bulk 3D phases,
+ * or 1D edges where multiple surfaces (and bulk phases) meet.
+ * @ingroup compobj
+ */
 class Interface : public Solution
 {
 private:
@@ -61,6 +66,7 @@ class Interface : public Solution
  *                 phases kinetics. If empty, adjacent phases will be instantiated based
  *                 on the phase definition.
  * @returns an initialized Interface object.
+ * @ingroup compobj
  */
 shared_ptr<Interface> newInterface(const std::string& infile,
     const std::string& name="", const std::vector<std::string>& adjacent={});
@@ -76,6 +82,7 @@ shared_ptr<Interface> newInterface(const std::string& infile,
  * @param adjacent vector containing adjacent Solution objects. If empty, adjacent
  *                 phases will be instantiated based on the phase definition.
  * @returns an initialized Interface object.
+ * @ingroup compobj
  */
 shared_ptr<Interface> newInterface(const std::string& infile,
     const std::string& name, const std::vector<shared_ptr<Solution>>& adjacent);
@@ -91,6 +98,7 @@ shared_ptr<Interface> newInterface(const std::string& infile,
  * @param adjacent vector containing adjacent Solution objects. If empty, adjacent
  *                 phases will be instantiated based on the phase definition.
  * @returns an initialized Interface object.
+ * @ingroup compobj
  */
 shared_ptr<Interface> newInterface(AnyMap& phaseNode, const AnyMap& rootNode=AnyMap(),
     const std::vector<shared_ptr<Solution>>& adjacent={});

include/cantera/base/Solution.h

@@ -17,7 +17,29 @@ class Kinetics;
 class Transport;
 class ExternalHandle;
 
-//! A container class holding managers for all pieces defining a phase
+//! @defgroup compobj Composite Objects
+//! Composite objects create a high-level interface to Cantera's core objects.
+
+//! A container class for chemically-reacting solutions.
+/*!
+ * The Solution class collects all objects needed to describe a chemically-reacting
+ * solution. Instances can be created to represent any type of solution -- a mixture
+ * of gases, a liquid solution, or a solid solution, for example.
+ *
+ * Solution objects only define a small number of methods of their own, and are provided
+ * so that a single object can be used to access thermodynamic, kinetic, and transport
+ * properties of a solution:
+ *  - ThermoPhase manager; accessed via thermo()
+ *  - Kinetics manager; accessed via kinetics()
+ *  - Transport manager; accessed via transport()
+ *
+ * The most common way to instantiate Solution objects is by using a phase definition,
+ * species and reactions defined in an input file:
+ * @code
+ *    shared_ptr<Solution> sol = newSolution("gri30.yaml", "gri30");
+ * @endcode
+ * @ingroup compobj
+ */
 class Solution : public std::enable_shared_from_this<Solution>
 {
 protected:
@@ -160,6 +182,7 @@ class Solution : public std::enable_shared_from_this<Solution>
  *                 phases kinetics. If empty, adjacent phases will be instantiated based
  *                 on the phase definition.
  * @returns an initialized Solution object.
+ * @ingroup compobj
  */
 shared_ptr<Solution> newSolution(const std::string& infile, const std::string& name,
     const std::string& transport, const std::vector<std::string>& adjacent);
@@ -176,6 +199,7 @@ shared_ptr<Solution> newSolution(const std::string& infile, const std::string& n
  * @param adjacent vector containing adjacent Solution objects. If empty, adjacent
  *                 phases will be instantiated based on the phase definition.
  * @returns an initialized Solution object.
+ * @ingroup compobj
  */
 shared_ptr<Solution> newSolution(const std::string& infile,
                                  const std::string& name="",
@@ -199,6 +223,7 @@ shared_ptr<Solution> newSolution(const std::string& infile,
  *                 a phase may be adjacent to multiple other phases but should be
  *                 instantiated only once.
  * @returns an initialized Solution object.
+ * @ingroup compobj
  */
 shared_ptr<Solution> newSolution(
     const AnyMap& phaseNode, const AnyMap& rootNode=AnyMap(),

include/cantera/base/SolutionArray.h

@@ -15,13 +15,19 @@ namespace Cantera
 class Solution;
 class ThermoPhase;
 
+//! A container class holding arrays of state information.
 /*!
- *  A container class providing a convenient interface for representing many
- *  thermodynamic states using the same Solution object. C++ SolutionArray objects are
- *  one-dimensional by design; while shape information for multi-dimensional arrays is
- *  stored, reshaping operations need to be implemented in high-level API's.
+ * SolutionArray objects provide a convenient interface for representing many
+ * thermodynamic states using the same Solution object. C++ SolutionArray objects are
+ * one-dimensional by design; while shape information for multi-dimensional arrays is
+ * stored, reshaping operations need to be implemented in high-level API's.
  *
- *  @since  New in Cantera 3.0.
+ * The SolutionArray class implements the main interface for saving and restoring of
+ * Cantera simulation data. SolutionArray objects can be serialized to and from YAML and
+ * HDF container files using the save() and restore() methods. In addition, there is
+ * limited support for CSV files.
+ * @since  New in Cantera 3.0.
+ * @ingroup compobj
  */
 class SolutionArray
 {