Adding description to impl tags in cases (#1596)

* Adding description to impl tags in `cases`

* Apply suggestions from code review

Co-authored-by: Michael Huang <lmichaelhuang3@gmail.com>

---------

Co-authored-by: Michael Huang <lmichaelhuang3@gmail.com>

armi/cases/case.py

@@ -331,16 +331,20 @@ def run(self):
         """
         Run an ARMI case.
 
-        This initializes an ``Operator``, a ``Reactor`` and invokes
-        :py:meth:`Operator.operate`!
-
-        It also activates supervisory things like code coverage checking, profiling,
-        or tracing, if requested by users during debugging.
 
         .. impl:: The case class allows for a generic ARMI simulation.
             :id: I_ARMI_CASE
             :implements: R_ARMI_CASE
 
+            This method is responsible for "running" the ARMI simulation
+            instigated by the inputted settings. This initializes an
+            :py:class:`~armi.operators.operator.Operator`, a
+            :py:class:`~armi.reactor.reactors.Reactor` and invokes
+            :py:meth:`Operator.operate
+            <armi.operators.operator.Operator.operate>`. It also activates
+            supervisory things like code coverage checking, profiling, or
+            tracing, if requested by users during debugging.
+
         Notes
         -----
         Room for improvement: The coverage, profiling, etc. stuff can probably be moved
@@ -565,6 +569,17 @@ def checkInputs(self):
             :id: I_ARMI_CASE_CHECK
             :implements: R_ARMI_CASE_CHECK
 
+            This method checks the validity of the current settings. It relies
+            on an :py:class:`~armi.operators.settingsValidation.Inspector`
+            object from the :py:class:`~armi.operators.operator.Operator` to
+            generate a list of
+            :py:class:`~armi.operators.settingsValidation.Query` objects that
+            represent potential issues in the settings. After gathering the
+            queries, this method prints a table of query "statements" and
+            "questions" to the console. If running in an interactive mode, the
+            user then has the opportunity to address the questions posed by the
+            queries by either addressing the potential issue or ignoring it.
+
         Returns
         -------
         bool

armi/cases/inputModifiers/inputModifiers.py

@@ -18,22 +18,22 @@ class InputModifier:
     """
     Object that modifies input definitions in some well-defined way.
 
-    (This class is abstract.)
-
-    Subclasses must implement a ``__call__`` method accepting a ``Settings``,
-    ``Blueprints``, and ``SystemLayoutInput``.
-
-    The class attribute ``FAIL_IF_AFTER`` should be a tuple defining what, if any,
-    modifications this should fail if performed after. For example, one should not
-    adjust the smear density (a function of Cladding ID) before adjusting the Cladding
-    ID.
-
-    Some subclasses are provided, but you are expected to make your own design-specific
-    modifiers in most cases.
-
     .. impl:: A generic tool to modify user inputs on multiple cases.
         :id: I_ARMI_CASE_MOD1
         :implements: R_ARMI_CASE_MOD
+
+        This class serves as an abstract base class for modifying the inputs of
+        a case, typically case settings. Child classes must implement a
+        ``__call__`` method accepting a
+        :py:class:`~armi.settings.caseSettings.Settings`,
+        :py:class:`~armi.reactor.blueprints.Blueprints`, and
+        :py:class:`~armi.reactor.systemLayoutInput.SystemLayoutInput` and return
+        the appropriately modified version of these objects. The class attribute
+        ``FAIL_IF_AFTER`` should be a tuple defining what, if any, modifications
+        this should fail if performed after. For example, one should not adjust
+        the smear density (a function of Cladding ID) before adjusting the
+        Cladding ID. Some generic child classes are provided in this module, but
+        it is expected that design-specific modifiers are built individually.
     """
 
     FAIL_IF_AFTER = ()

armi/cases/suite.py

@@ -44,15 +44,17 @@ class CaseSuite:
     """
     A CaseSuite is a collection of possibly related Case objects.
 
-    A CaseSuite is intended to be both a pre-processing and post-processing tool to
-    facilitate case generation and analysis. Under most circumstances one may wish to
-    subclass a CaseSuite to meet the needs of a specific calculation.
-
-    A CaseSuite is a collection that is keyed off Case titles.
-
     .. impl:: CaseSuite allows for one case to start after another completes.
         :id: I_ARMI_CASE_SUITE
         :implements: R_ARMI_CASE_SUITE
+
+        The CaseSuite object allows multiple, often related,
+        :py:class:`~armi.cases.case.Case` objects to be run sequentially. A
+        CaseSuite is intended to be both a pre-processing and post-processing
+        tool to facilitate case generation and analysis. Under most
+        circumstances one may wish to subclass a CaseSuite to meet the needs of
+        a specific calculation. A CaseSuite is a collection that is keyed off
+        Case titles.
     """
 
     def __init__(self, cs):

armi/cases/suiteBuilder.py

@@ -49,6 +49,18 @@ class SuiteBuilder:
         :id: I_ARMI_CASE_MOD0
         :implements: R_ARMI_CASE_MOD
 
+        This class provides the capability to create a
+        :py:class:`~armi.cases.suite.CaseSuite` based on programmatic
+        perturbations/modifications to case settings. It works by being
+        constructed with a base or nominal :py:class:`~armi.cases.case.Case`
+        object. Children classes then append the ``self.modifierSets`` member.
+        Each entry in ``self.modifierSets`` is a
+        :py:class:`~armi.cases.inputModifiers.inputModifiers.InputModifier`
+        representing a case to add to the suite by specifying modifications to
+        the settings of the base case. :py:meth:`SuiteBuilder.buildSuite` is
+        then invoked, returning an instance of the :py:class:`~armi.cases.suite.CaseSuite`
+        containing all the cases with modified settings.
+
     Attributes
     ----------
     baseCase : armi.cases.case.Case
@@ -213,14 +225,21 @@ def __call__(self, cs, bp, geom):
 
         would result in 6 cases:
 
+        +-------+------------------+------------------+
         | Index | ``settingName1`` | ``settingName2`` |
-        | ----- | ---------------- | ---------------- |
+        +=======+==================+==================+
         | 0     | 1                | 3                |
+        +-------+------------------+------------------+
         | 1     | 2                | 3                |
+        +-------+------------------+------------------+
         | 2     | 1                | 4                |
+        +-------+------------------+------------------+
         | 3     | 2                | 4                |
+        +-------+------------------+------------------+
         | 4     | 1                | 5                |
+        +-------+------------------+------------------+
         | 5     | 2                | 5                |
+        +-------+------------------+------------------+
 
         See Also
         --------
@@ -299,13 +318,19 @@ def __call__(self, cs, bp, geom):
 
         would result in 5 cases:
 
+        +-------+------------------+------------------+
         | Index | ``settingName1`` | ``settingName2`` |
-        | ----- | ---------------- | ---------------- |
+        +=======+==================+==================+
         | 0     | 1                | default          |
+        +-------+------------------+------------------+
         | 1     | 2                | default          |
+        +-------+------------------+------------------+
         | 2     | default          | 3                |
+        +-------+------------------+------------------+
         | 3     | default          | 4                |
+        +-------+------------------+------------------+
         | 4     | default          | 5                |
+        +-------+------------------+------------------+
 
         See Also
         --------