From d23fa7cf657c1bf902c078ad039cbddba33dab69 Mon Sep 17 00:00:00 2001
From: Andrew Johnson <drewej@protonmail.com>
Date: Mon, 15 Jul 2019 11:39:05 -0500
Subject: [PATCH] Improve documentation for Operator helpers

---
 openmc/deplete/abc.py     | 45 ++++++++++++++++++++++++++++-----------
 openmc/deplete/helpers.py | 10 ++++-----
 2 files changed, 37 insertions(+), 18 deletions(-)

diff --git a/openmc/deplete/abc.py b/openmc/deplete/abc.py
index 565a04089f..62db6915e4 100644
--- a/openmc/deplete/abc.py
+++ b/openmc/deplete/abc.py
@@ -214,10 +214,13 @@ class ReactionRateHelper(ABC):
     def get_material_rates(self, mat_id, nuc_index, react_index):
         """Return 2D array of [nuclide, reaction] reaction rates
 
-        ``nuc_index`` and ``react_index`` are orderings of nuclides
-        and reactions such that the ordering is consistent between
-        reaction tallies and energy deposition tallies"""
-        pass
+        Parameters
+        ----------
+        nuc_index : list of str
+            Ordering of desired nuclides
+        react_index : list of str
+            Ordering of reactions
+        """
 
     def divide_by_adens(self, number):
         """Normalize reaction rates by number of nuclides
@@ -230,12 +233,12 @@ class ReactionRateHelper(ABC):
         energy : float
             Energy produced in this region [W]
         number : iterable of float
-            Number density [#/b/cm] of each nuclide tracked in the calculation.
+            Number density [atoms/b/cm] of each nuclide tracked in the calculation.
             Ordered identically to :attr:`nuclides`
 
         Returns
         -------
-        results : :class:`numpy.ndarray`
+        results : `numpy.ndarray`
             2D array ``[n_nuclides, n_rxns]`` of reaction rates normalized by
             the number of nuclides
         """
@@ -265,16 +268,32 @@ class FissionEnergyHelper(ABC):
     def prepare(self, chain_nucs, rate_index, materials):
         """Perform work needed to obtain fission energy per material
 
-        ``chain_nucs`` is all nuclides tracked in the depletion chain,
-        while ``rate_index`` should be a mapping from nuclide name
-        to index in the reaction rate vector used in
-        :meth:`get_fission_energy`.
-        ``materials`` should be a list of all materials tracked
-        on the operator to which this object is attached"""
+        Parameters
+        ----------
+        chain_nucs : list of str
+            All nuclides to be tracked in this problem
+        rate_index : dict of str to int
+            Mapping from nuclide name to index in the
+            reaction rate vector used in :meth:`get_energy`.
+        materials : list of str
+            All materials tracked on the operator helped by this
+            object
+        """
 
     @abstractmethod
     def get_fission_energy(self, fission_rates, mat_index):
-        """Return fission energy in this material given fission rates"""
+        """Return fission energy in this material given fission rates
+
+        Parameters
+        ----------
+        fission_rates : numpy.ndarray
+            fission reaction rate for each isotope in the specified
+            material. Should be ordered corresponding to initial
+            ``rate_index`` used in :meth:`prepare`
+        mat_index : int
+            Index for the material requested.
+        """
+
 
     @property
     def nuclides(self):
diff --git a/openmc/deplete/helpers.py b/openmc/deplete/helpers.py
index f039eeb709..5e8b4146e8 100644
--- a/openmc/deplete/helpers.py
+++ b/openmc/deplete/helpers.py
@@ -102,16 +102,16 @@ class ChainFissHelper(FissionEnergyHelper):
         self._fission_E = fiss_E
 
     def get_fission_energy(self, fiss_rates, _mat_index):
-        """Return a vector of the isotopic fission energy for this material
+        """Return fission energy for this material
 
-        parameters
+        Parameters
         ----------
         fission_rates : numpy.ndarray
             fission reaction rate for each isotope in the specified
-            material. should be ordered corresponding to initial
-            ``rate_index`` used in :meth:`set_fission_q`
+            material. Should be ordered corresponding to initial
+            ``rate_index`` used in :meth:`prepare`
         _mat_index : int
-            index for the material requested. Unused, as all
+            index for the material requested. Unused, as identical
             isotopes in all materials have the same Q value.
         """
         return dot(fiss_rates, self._fission_E)