From a54ab2f3efec19715039cd7c064902c5050eb2c1 Mon Sep 17 00:00:00 2001
From: Ray Speth <speth@mit.edu>
Date: Fri, 10 Aug 2018 10:47:05 -0400
Subject: [PATCH] [Doc] Update docs related to StFlow restructuring

---
 doc/sphinx/cython/onedim.rst         |  2 --
 include/cantera/oneD/StFlow.h        | 16 ++++++++++++++++
 interfaces/cython/cantera/onedim.pyx | 27 ++++++++++++++++++++++-----
 3 files changed, 38 insertions(+), 7 deletions(-)

diff --git a/doc/sphinx/cython/onedim.rst b/doc/sphinx/cython/onedim.rst
index 9fe6599d9..138fb0104 100644
--- a/doc/sphinx/cython/onedim.rst
+++ b/doc/sphinx/cython/onedim.rst
@@ -62,12 +62,10 @@ IonFlow
 FreeFlow
 ^^^^^^^^
 .. autoclass:: FreeFlow(thermo)
-    :inherited-members:
 
 AxisymmetricStagnationFlow
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 .. autoclass:: AxisymmetricStagnationFlow(thermo)
-    :inherited-members:
 
 Boundaries
 ----------
diff --git a/include/cantera/oneD/StFlow.h b/include/cantera/oneD/StFlow.h
index e0b08d61f..4963a63ea 100644
--- a/include/cantera/oneD/StFlow.h
+++ b/include/cantera/oneD/StFlow.h
@@ -147,16 +147,24 @@ public:
     virtual void restore(const XML_Node& dom, doublereal* soln,
                          int loglevel);
 
+    //! Set flow configuration for freely-propagating flames, using an internal
+    //! point with a fixed temperature as the condition to determine the inlet
+    //! mass flux.
     void setFreeFlow() {
         m_type = cFreeFlow;
         m_dovisc = false;
     }
 
+    //! Set flow configuration for axisymmetric counterflow or burner-stabilized
+    //! flames, using specified inlet mass fluxes.
     void setAxisymmetricFlow() {
         m_type = cAxisymmetricStagnationFlow;
         m_dovisc = true;
     }
 
+    //! Return the type of flow domain being represented, either "Free Flame" or
+    //! "Axisymmetric Stagnation".
+    //! @see setFreeFlow setAxisymmetricFlow
     virtual std::string flowType() {
         if (m_type == cFreeFlow) {
             return "Free Flame";
@@ -460,6 +468,10 @@ private:
 
 /**
  * A class for axisymmetric stagnation flows.
+ *
+ * @deprecated To be removed after Cantera 2.4. Use class StFlow with the
+ *     StFlow::setAxisymmetricFlow() method instead.
+ *
  * @ingroup onedim
  */
 class AxiStagnFlow : public StFlow
@@ -476,6 +488,10 @@ public:
 
 /**
  * A class for freely-propagating premixed flames.
+ *
+ * @deprecated To be removed after Cantera 2.4. Use class StFlow with the
+ *     StFlow::setFreeFlow() method instead.
+ *
  * @ingroup onedim
  */
 class FreeFlame : public StFlow
diff --git a/interfaces/cython/cantera/onedim.pyx b/interfaces/cython/cantera/onedim.pyx
index 157a4ff19..1080078a4 100644
--- a/interfaces/cython/cantera/onedim.pyx
+++ b/interfaces/cython/cantera/onedim.pyx
@@ -469,11 +469,18 @@ cdef class _FlowBase(Domain1D):
             self.flow.enableRadiation(<cbool>do_radiation)
 
     def set_free_flow(self):
-        """ Set flow type to free flow."""
+        """
+        Set flow configuration for freely-propagating flames, using an internal
+        point with a fixed temperature as the condition to determine the inlet
+        mass flux.
+        """
         self.flow.setFreeFlow()
 
     def set_axisymmetric_flow(self):
-        """ Set flow type to axisymmetric stagnation flow."""
+        """
+        Set flow configuration for axisymmetric counterflow or burner-stabilized
+        flames, using specified inlet mass fluxes.
+        """
         self.flow.setAxisymmetricFlow()
 
 
@@ -485,8 +492,8 @@ cdef CxxIdealGasPhase* getIdealGasPhase(ThermoPhase phase) except *:
 
 cdef class IdealGasFlow(_FlowBase):
     """
-    An ideal gas flow domain. Functions set_free_flow and set_axisymmetric_flow
-    can be used to set different type of flow.
+    An ideal gas flow domain. Functions `set_free_flow` and
+    `set_axisymmetric_flow` can be used to set different type of flow.
 
     For the type of axisymmetric flow, the equations solved are the similarity
     equations for the flow in a finite-height gap of infinite radial extent.
@@ -519,15 +526,25 @@ cdef class IdealGasFlow(_FlowBase):
 
 
 cdef class FreeFlow(IdealGasFlow):
+    """
+    .. deprecated:: 2.4
+        To be removed after Cantera 2.4. Use class `IdealGasFlow` instead and
+        call the ``set_free_flow()`` method.
+    """
     def __init__(self, *args, **kwargs):
         warnings.warn("Class FreeFlow is deprecated and will be removed after"
             " Cantera 2.4. Use class IdealGasFlow instead and call the"
-            " set_free_flow() method.")
+            " ``set_free_flow()`` method.")
         super().__init__(*args, **kwargs)
         self.set_free_flow()
 
 
 cdef class AxisymmetricStagnationFlow(IdealGasFlow):
+    """
+    .. deprecated:: 2.4
+        To be removed after Cantera 2.4. Use class `IdealGasFlow` instead and
+        call the ``set_axisymmetric_flow()`` method.
+    """
     def __init__(self, *args, **kwargs):
         warnings.warn("Class AxisymmetricStagnationFlow is deprecated and will"
             " be removed after Cantera 2.4. Use class IdealGasFlow instead and"