Apply suggestions from code review

Co-authored-by: David Gardner <[email protected]>

doc/arkode/guide/source/Usage/ARKStep_c_interface/User_callable.rst

@@ -1815,7 +1815,7 @@ Explicit stability function                                 :c:func:`ARKStepSetS
       This should be called prior to calling :c:func:`ARKStepEvolve()`, and can only be
       reset following a call to :c:func:`ARKStepReInit()`.
 
-
+   .. versionadded:: x.x.x
 
 .. c:function:: int ARKStepSetCFLFraction(void* arkode_mem, realtype cfl_frac)
 

doc/arkode/guide/source/Usage/ERKStep_c_interface/User_callable.rst

@@ -1298,7 +1298,7 @@ the code, is provided in :numref:`ARKODE.Mathematics.Adaptivity`.
       This should be called prior to calling :c:func:`ERKStepEvolve()`, and can only be
       reset following a call to :c:func:`ERKStepReInit()`.
 
-
+   .. versionadded:: x.x.x
 
 .. c:function:: int ERKStepSetCFLFraction(void* arkode_mem, realtype cfl_frac)
 

doc/arkode/guide/source/sunadaptcontroller/index.rst

@@ -19,9 +19,9 @@ Time Step Adaptivity Controllers
 The SUNDIALS library comes packaged with a variety of :c:type:`SUNAdaptController`
 implementations, designed to support various forms of error-based time step
 adaptivity within SUNDIALS time integrators.  To support applications that may
-want to adjust or disable these heuristic controls, SUNDIALS provides a
-:c:type:`SUNAdaptController` base class, along with a variety of default
-implementations.
+want to adjust the controller parameters or provide their own implementations,
+SUNDIALS defines the :c:type:`SUNAdaptController` base class, along with a
+variety of default implementations.
 
 .. toctree::
    :maxdepth: 1

doc/shared/sunadaptcontroller/SUNAdaptController_Description.rst

@@ -25,7 +25,7 @@ temporal accuracy, while striving to maximize computational efficiency. We note
 that in the descriptions below, we frequently use *dsm* to represent
 temporal error. This is **not** the raw temporal error estimate; instead, it is
 a norm of the temporal error estimate after scaling by the user-supplied
-accuracy tolerances (the SUNDIALS WRMS-norm),
+accuracy tolerances (see :eq:`ARKODE_WRMS_NORM`),
 
 .. math::
    \text{dsm} = \left( \frac{1}{N} \sum_{i=1}^N
@@ -48,7 +48,7 @@ and the base class structure is defined as
 
    struct _generic_SUNAdaptController {
         void* content;
-        generic_SUNAdaptController_Ops_* ops;
+        generic_SUNAdaptController_Ops* ops;
         SUNContext sunctx;
     };
 
@@ -104,8 +104,8 @@ SUNAdaptController Operations
 The base SUNAdaptController class defines and implements all SUNAdaptController functions. Most
 of these routines are merely wrappers for the operations defined by a particular
 SUNAdaptController implementation, which are accessed through the *ops* field of the
-``SUNAdaptController`` structure. However, the base SUNAdaptController class also provides the
-convenience routine
+``SUNAdaptController`` structure. The base SUNAdaptController class provides the
+constructor
 
 .. c:function:: SUNAdaptController SUNAdaptController_NewEmpty(SUNContext sunctx)
 
@@ -118,11 +118,10 @@ convenience routine
   :returns: If successful, a generic :c:type:`SUNAdaptController` object. If
             unsuccessful, a ``NULL`` pointer will be returned.
 
-Each of the following routines are *optional* for any specific SUNAdaptController
+Each of the following methods are *optional* for any specific SUNAdaptController
 implementation, however some may be required based on the implementation's
 :c:type:`SUNAdaptController_Type` (see Section :numref:`SUNAdaptController.Description.controllerTypes`). We
-note these requirements, as well as the behavior of the base SUNAdaptController wrapper
-routine, below.
+note these requirements below. Additionally, we note the behavior of the base SUNAdaptController methods when they perform an action other than only a successful return.
 
 .. c:function:: SUNAdaptController_Type SUNAdaptController_GetType(SUNAdaptController C)
 
@@ -140,8 +139,8 @@ routine, below.
 
 .. c:function:: int SUNAdaptController_Destroy(SUNAdaptController C)
 
-   Deallocates the controller *C*. If this is not provided by the
-   implementation, the base wrapper routine will free both the *content* and
+   Deallocates the controller *C*. If this method is not provided by the
+   implementation, the base class method will free both the *content* and
    *ops* objects -- this should be sufficient unless a controller implementation
    performs dynamic memory allocation of its own (note that the
    SUNDIALS-provided SUNAdaptController implementations do not need to supply this
@@ -167,22 +166,20 @@ routine, below.
    :param h: the step size from the previous step attempt.
    :param p: the current order of accuracy for the time integration method.
    :param dsm: the local temporal estimate from the previous step attempt.
-   :param hnew: (output) pointer to the estimated step size.
+   :param hnew: (output) the estimated step size.
    :return: error code indicating success failure
             (see :numref:`SUNAdaptController.Description.errorCodes`).
 
    Usage:
 
    .. code-block:: c
 
-      retval = SUNAdaptController_EstimateStep(C, hcur, dsm, &hnew);
+      retval = SUNAdaptController_EstimateStep(C, hcur, p, dsm, &hnew);
 
 .. c:function:: int SUNAdaptController_Reset(SUNAdaptController C)
 
    Resets the controller to its initial state, e.g., if it stores a small number
-   of previous *dsm* or *h* values. The return value is an integer flag denoting
-   success/failure of the routine (see
-   :numref:`SUNAdaptController.Description.errorCodes`).
+   of previous *dsm* or *h* values.
 
    :param C:  the :c:type:`SUNAdaptController` object.
    :return: error code indicating success failure
@@ -198,7 +195,7 @@ routine, below.
 
    Sets the controller parameters to their default values.
 
-   :param C:  the :c:type:`SUNAdaptController` object..
+   :param C:  the :c:type:`SUNAdaptController` object.
    :return: error code indicating success failure
             (see :numref:`SUNAdaptController.Description.errorCodes`).
 
@@ -213,7 +210,7 @@ routine, below.
    Writes all controller parameters to the indicated file pointer.
 
    :param C:  the :c:type:`SUNAdaptController` object.
-   :param fptr:  the output stream to write the parameters.
+   :param fptr:  the output stream to write the parameters to.
    :return: error code indicating success failure
             (see :numref:`SUNAdaptController.Description.errorCodes`).
 
@@ -301,18 +298,18 @@ SUNAdaptController functions return one of the following set of error codes:
 
 .. note::
    The SUNDIALS time integrators do not rely on these specific return values (only
-   on whether the returned values are 0 (successful) or negative (failure).  Thus,
+   on whether the returned values are 0 (successful) or non-zero (failure).  Thus,
    user-defined implementations are not required to use these specific error codes,
-   so long as the zero/negative structure is followed.
+   so long as the zero/non-zero convention is followed.
 
 
 C/C++ API Usage
 ---------------
 
 Specific SUNDIALS adaptivity controller modules can be used in C and C++ programs by including
-the corresponding header file for that module, e.g. ``sunadaptcontroller/sunadaptcontrollerXYZ.h``.
+the corresponding header file for that module, e.g. ``sunadaptcontroller/sunadaptcontroller_XYZ.h``.
 
-Example usage (here ``SUNAdaptControllerXYZ`` is a placeholder for an actual SUNAdaptController
+Example usage (here ``SUNAdaptController_XYZ`` is a placeholder for an actual SUNAdaptController
 constructor):
 
 .. code-block:: c
@@ -321,15 +318,15 @@ constructor):
     #include <stdlib.h>
     #include <sundials/sundials_context.h>
     #include <sundials/sundials_types.h>
-    #include <sunadaptcontroller/sunadaptcontrollerXYZ.h>
+    #include <sunadaptcontroller/sunadaptcontroller_XYZ.h>
 
     int main()
     {
         /* Create a SUNContext object */
         SUNContext sunctx = ...;
 
         /* Create a SUNAdaptController object */
-        SUNAdaptController C = SUNAdaptControllerXYZ(sunctx);
+        SUNAdaptController C = SUNAdaptController_XYZ(sunctx);
 
         /* Use the control object */
 

doc/shared/sunadaptcontroller/SUNAdaptController_ImExGus.rst

@@ -88,15 +88,15 @@ The header file to be included when using this module is
 
 
 The SUNAdaptController_ImExGus class provides implementations of all operations
-relevant to a `SUN_ADAPTCONTROLLER_H` controller listed in
+relevant to a ``SUN_ADAPTCONTROLLER_H`` controller listed in
 :numref:`SUNAdaptController.Description.operations`. The
 SUNAdaptController_ImExGus class also provides the following additional user-callable
 routines:
 
 
 .. c:function:: SUNAdaptController SUNAdaptController_ImExGus(SUNContext sunctx)
 
-   This constructor function creates and allocates memory for a SUNAdaptController_ImExGus
+   This constructor creates and allocates memory for a SUNAdaptController_ImExGus
    object, and inserts its default parameters.
 
    :param sunctx: the current :c:type:`SUNContext` object.

doc/shared/sunadaptcontroller/SUNAdaptController_Soderlind.rst

@@ -19,18 +19,18 @@ The SUNAdaptController_Soderlind Module
 
 The Soderlind implementation of the SUNAdaptController class,
 SUNAdaptController_Soderlind, implements a general structure for temporal
-control proposed by G. Soderlind in :cite:p:`Sod:98`, :cite:p:`Sod:03`
+control proposed by G. Soderlind in :cite:p:`Sod:98`, :cite:p:`Sod:03`,
 and :cite:p:`Sod:06`.  This controller has the form
 
 .. math::
    h' = h_n \varepsilon_n^{-k_1/(p+1)} \varepsilon_{n-1}^{-k_2/(p+1)} \varepsilon_{n-2}^{-k_3/(p+1)} \left(\dfrac{h_n}{h_{n-1}}\right)^{k_4} \left(\dfrac{h_{n-1}}{h_{n-2}}\right)^{k_5}
 
 with default parameter values :math:`k_1 = 1.25`, :math:`k_2 = 0.5`,
-:math:`k_3 = -0.75`, :math:`k_4 = 0.25` and :math:`k_5 = 0.75`, where
+:math:`k_3 = -0.75`, :math:`k_4 = 0.25`, and :math:`k_5 = 0.75`, where
 :math:`p` is the global order of the time integration method.  In this estimate,
-a floor of :math:`\varepsilon > 10^{-10}` is enforced to avoid division-by-zero
+a floor of :math:`\varepsilon_* > 10^{-10}` is enforced to avoid division-by-zero
 errors.  During the first two steps (when :math:`\varepsilon_{n-2}`,
-:math:`\varepsilon_{n-1}`, :math:`h_{n-2}` and :math:`h_{n-2}` may be unavailable),
+:math:`\varepsilon_{n-1}`, :math:`h_{n-2}`, and :math:`h_{n-2}` may be unavailable),
 the corresponding terms are merely omitted during estimation of :math:`h'`.
 
 The SUNAdaptController_Soderlind controller is implemented as a derived
@@ -60,7 +60,7 @@ These entries of the *content* field contain the following information:
   estimate via :math:`\varepsilon = \text{bias}*\text{dsm}`.
 
 * ``ep, epp`` - storage for the two previous error estimates,
-  :math:`\varepsilon_{n-1}` and :math:`varepsilon_{n-2}`.
+  :math:`\varepsilon_{n-1}` and :math:`\varepsilon_{n-2}`.
 
 * ``hp, hpp`` - storage for the previous two step sizes, :math:`h_{n-1}`
   and :math:`h_{n-2}`.
@@ -71,22 +71,22 @@ These entries of the *content* field contain the following information:
 The header file to be included when using this module is
 ``sunadaptcontroller/sunadaptcontroller_soderlind.h``.
 
-We note that through appropriate selection of the parameters :math:`k_1 - k_5`,
+We note that through appropriate selection of the parameters :math:`k_*`,
 this controller may create a wide range of proposed temporal adaptivity controllers,
 including the PID, PI, I, as well as Gustafsson's explicit and implicit controllers,
 :cite:p:`Gust:91` and :cite:p:`Gust:94`.  As a convenience, utility routines to
 create these controllers and set their parameters (as special cases of the
 SUNAdaptController_Soderlind) are provided.
 
 The SUNAdaptController_Soderlind class provides implementations of all operations
-relevant to a `SUN_ADAPTCONTROLLER_H` controller listed in
+relevant to a ``SUN_ADAPTCONTROLLER_H`` controller listed in
 :numref:`SUNAdaptController.Description.operations`. This class
 also provides the following additional user-callable routines:
 
 
 .. c:function:: SUNAdaptController SUNAdaptController_Soderlind(SUNContext sunctx)
 
-   This constructor function creates and allocates memory for a SUNAdaptController_Soderlind
+   This constructor creates and allocates memory for a SUNAdaptController_Soderlind
    object, and inserts its default parameters.
 
    :param sunctx: the current :c:type:`SUNContext` object.
@@ -123,9 +123,9 @@ also provides the following additional user-callable routines:
 
 .. c:function:: SUNAdaptController SUNAdaptController_PID(SUNContext sunctx)
 
-   This constructor function creates and allocates memory for a SUNAdaptController_Soderlind
+   This constructor creates and allocates memory for a SUNAdaptController_Soderlind
    object, set up to replicate a PID controller, and inserts its default parameters
-   (:math:`k_1=0.58`, :math:`k_2=-0.21`, :math:`k_3=0.1`, and :math:`k_4=k_5=0`).
+   :math:`k_1=0.58`, :math:`k_2=-0.21`, :math:`k_3=0.1`, and :math:`k_4=k_5=0`.
 
    :param sunctx: the current :c:type:`SUNContext` object.
    :return: if successful, a usable :c:type:`SUNAdaptController` object;
@@ -140,8 +140,8 @@ also provides the following additional user-callable routines:
 .. c:function:: int SUNAdaptController_SetParams_PID(SUNAdaptController C, sunrealtype k1, sunrealtype k2, sunrealtype k3)
 
    This user-callable function provides control over the relevant parameters
-   above, setting :math:`k_4 = k_5 = 0`.  This should be called *before* the
-   time integrator is called to evolve the problem.
+   above for a PID controller, setting :math:`k_4 = k_5 = 0`.  This should be
+   called *before* the time integrator is called to evolve the problem.
 
    :param C: the SUNAdaptController_Soderlind object.
    :param k1: parameter used within the controller time step estimate.
@@ -158,9 +158,9 @@ also provides the following additional user-callable routines:
 
 .. c:function:: SUNAdaptController SUNAdaptController_PI(SUNContext sunctx)
 
-   This constructor function creates and allocates memory for a SUNAdaptController_Soderlind
+   This constructor creates and allocates memory for a SUNAdaptController_Soderlind
    object, set up to replicate a PI controller, and inserts its default parameters
-   (:math:`k_1=0.8`, :math:`k_2=-0.31`, and :math:`k_3=k_4=k_5=0`).
+   :math:`k_1=0.8`, :math:`k_2=-0.31`, and :math:`k_3=k_4=k_5=0`.
 
    :param sunctx: the current :c:type:`SUNContext` object.
    :return: if successful, a usable :c:type:`SUNAdaptController` object;
@@ -175,8 +175,8 @@ also provides the following additional user-callable routines:
 .. c:function:: int SUNAdaptController_SetParams_PI(SUNAdaptController C, sunrealtype k1, sunrealtype k2)
 
    This user-callable function provides control over the relevant parameters
-   above, setting :math:`k_3 = k_4 = k_5 = 0`.  This should be called *before* the
-   time integrator is called to evolve the problem.
+   above for a PI controller, setting :math:`k_3 = k_4 = k_5 = 0`.  This should
+   be called *before* the time integrator is called to evolve the problem.
 
    :param C: the SUNAdaptController_Soderlind object.
    :param k1: parameter used within the controller time step estimate.
@@ -192,9 +192,9 @@ also provides the following additional user-callable routines:
 
 .. c:function:: SUNAdaptController SUNAdaptController_I(SUNContext sunctx)
 
-   This constructor function creates and allocates memory for a SUNAdaptController_Soderlind
+   This constructor creates and allocates memory for a SUNAdaptController_Soderlind
    object, set up to replicate an I controller, and inserts its default parameters
-   (:math:`k_1=1.0` and :math:`k_2=k_3=k_4=k_5=0`).
+   :math:`k_1=1.0` and :math:`k_2=k_3=k_4=k_5=0`.
 
    :param sunctx: the current :c:type:`SUNContext` object.
    :return: if successful, a usable :c:type:`SUNAdaptController` object;
@@ -209,8 +209,8 @@ also provides the following additional user-callable routines:
 .. c:function:: int SUNAdaptController_SetParams_I(SUNAdaptController C, sunrealtype k1)
 
    This user-callable function provides control over the relevant parameters
-   above, setting :math:`k_2 = k_3 = k_4 = k_5 = 0`.  This should be called *before* the
-   time integrator is called to evolve the problem.
+   above for an I controller, setting :math:`k_2 = k_3 = k_4 = k_5 = 0`.  This
+   should be called *before* the time integrator is called to evolve the problem.
 
    :param C: the SUNAdaptController_Soderlind object.
    :param k1: parameter used within the controller time step estimate.
@@ -225,10 +225,10 @@ also provides the following additional user-callable routines:
 
 .. c:function:: SUNAdaptController SUNAdaptController_ExpGus(SUNContext sunctx)
 
-   This constructor function creates and allocates memory for a SUNAdaptController_Soderlind
+   This constructor creates and allocates memory for a SUNAdaptController_Soderlind
    object, set up to replicate Gustafsson's explicit controller :cite:p:`Gust:91`, and
-   inserts its default parameters (:math:`k_1=0.635`, :math:`k_2=-0.268`, and
-   :math:`k_3=k_4=k_5=0`).
+   inserts its default parameters :math:`k_1=0.635`, :math:`k_2=-0.268`, and
+   :math:`k_3=k_4=k_5=0`.
 
    :param sunctx: the current :c:type:`SUNContext` object.
    :return: if successful, a usable :c:type:`SUNAdaptController` object;
@@ -243,8 +243,8 @@ also provides the following additional user-callable routines:
 .. c:function:: int SUNAdaptController_SetParams_ExpGus(SUNAdaptController C, sunrealtype k1_hat, sunrealtype k2_hat)
 
    This user-callable function provides control over the relevant parameters
-   above, setting :math:`k_3 = k_4 = k_5 = 0`.  This should be called *before* the
-   time integrator is called to evolve the problem.
+   above for the explicit Gustafsson controller, setting :math:`k_3 = k_4 = k_5 = 0`. 
+   This should be called *before* the time integrator is called to evolve the problem.
 
    .. note::
 
@@ -271,10 +271,10 @@ also provides the following additional user-callable routines:
 
 .. c:function:: SUNAdaptController SUNAdaptController_ImpGus(SUNContext sunctx)
 
-   This constructor function creates and allocates memory for a SUNAdaptController_Soderlind
+   This constructor creates and allocates memory for a SUNAdaptController_Soderlind
    object, set up to replicate Gustafsson's implicit controller :cite:p:`Gust:94`, and
-   inserts its default parameters (:math:`k_1=1.93`, :math:`k_2=-0.95`, :math:`k_4=1`, and
-   :math:`k_3=k_5=0`).
+   inserts its default parameters :math:`k_1=1.93`, :math:`k_2=-0.95`, :math:`k_4=1`, and
+   :math:`k_3=k_5=0`.
 
    :param sunctx: the current :c:type:`SUNContext` object.
    :return: if successful, a usable :c:type:`SUNAdaptController` object;
@@ -289,8 +289,8 @@ also provides the following additional user-callable routines:
 .. c:function:: int SUNAdaptController_SetParams_ImpGus(SUNAdaptController C, sunrealtype k1_hat, sunrealtype k2_hat)
 
    This user-callable function provides control over the relevant parameters
-   above, setting :math:`k_3 = k_4 = k_5 = 0`.  This should be called *before* the
-   time integrator is called to evolve the problem.
+   above for the implicit Gustafsson controller, setting :math:`k_3 = k_4 = k_5 = 0`.
+   This should be called *before* the time integrator is called to evolve the problem.
 
    .. note::