From 89db332f83da61ea318800af1f292a39a42e52fe Mon Sep 17 00:00:00 2001
From: Chris Keckler <ckeckler@terrapower.com>
Date: Fri, 19 Jan 2024 22:25:33 +0000
Subject: [PATCH] Add longer descriptions for fuelCycle impls

---
 .../physics/fuelCycle/fuelHandlerInterface.py | 17 +++++++
 armi/physics/fuelCycle/fuelHandlers.py        | 46 +++++++++++++++----
 2 files changed, 54 insertions(+), 9 deletions(-)

diff --git a/armi/physics/fuelCycle/fuelHandlerInterface.py b/armi/physics/fuelCycle/fuelHandlerInterface.py
index 31d17917f..a79f281c9 100644
--- a/armi/physics/fuelCycle/fuelHandlerInterface.py
+++ b/armi/physics/fuelCycle/fuelHandlerInterface.py
@@ -36,6 +36,23 @@ class FuelHandlerInterface(interfaces.Interface):
         :id: I_ARMI_SHUFFLE
         :implements: R_ARMI_SHUFFLE
 
+        This interface allows for a user to define custom shuffle logic that
+        modifies to the core model. Being based on the :py:class:`~armi.interfaces.Interface`
+        class, it has direct access to the current core model.
+
+        User logic is able to be executed from within the
+        :py:meth:`~armi.physics.fuelCycle.fuelHandlerInterface.FuelHandlerInterface.manageFuel` method,
+        which will use the :py:meth:`~armi.physics.fuelCycle.fuelHandlerFactory.fuelHandlerFactory`
+        to search for a Python file specified by the case settings
+        ``fuelHandlerName`` and ``shuffleLogic``. If it exists, the user-specified
+        fuel handler will be imported, and any actions in its ``outage`` method
+        will be executed at the :py:meth:`~armi.physics.fuelCycle.fuelHandlerInterface.FuelHandlerInterface.interactBOC`
+        hook.
+
+        If no class with the name specified by the ``fuelHandlerName`` setting is found
+        in the file with path ``shuffleLogic``, an error is returned.
+
+        See the user manual for how the custom shuffle logic file should be constructed.
     """
 
     name = "fuelHandler"
diff --git a/armi/physics/fuelCycle/fuelHandlers.py b/armi/physics/fuelCycle/fuelHandlers.py
index ac463bf5e..a70c14517 100644
--- a/armi/physics/fuelCycle/fuelHandlers.py
+++ b/armi/physics/fuelCycle/fuelHandlers.py
@@ -727,10 +727,31 @@ def swapAssemblies(self, a1, a2):
             :id: I_ARMI_SHUFFLE_MOVE
             :implements: R_ARMI_SHUFFLE_MOVE
 
+            For the two assemblies that are passed in, call to their :py:meth:`~armi.reactor.assemblies.Assembly.moveTo`
+            methods to transfer their underlying ``spatialLocator`` attributes to
+            each other. This will also update the ``childrenByLocator`` list on the
+            core as well as the assembly parameters ``numMoves`` and ``daysSinceLastMove``.
+
         .. impl:: User-specified blocks can be left in place and not moved.
             :id: I_ARMI_SHUFFLE_STATIONARY0
             :implements: R_ARMI_SHUFFLE_STATIONARY
 
+            Before assemblies are moved,
+            calls to the ``_transferStationaryBlocks`` class method to
+            check if there are any block types specified by the user as stationary
+            via the ``stationaryBlockFlags`` case setting. Using these flags, gather
+            blocks from each assembly which should remain stationary and check
+            to make sure that both assemblies have the same number and same
+            height of stationary blocks. If not, return an error.
+
+            If all checks pass, use the :py:meth:`~armi.reactor.assemblies.Assembly.remove`
+            and :py:meth:`~armi.reactor.assemblies.Assembly.insert``
+            methods to swap the stationary blocks between the two assemblies.
+
+            Once this process is complete, the actual assembly movement can take
+            place. Through this process, the stationary blocks remain in the same
+            core location.
+
         Parameters
         ----------
         a1 : :py:class:`Assembly <armi.reactor.assemblies.Assembly>`
@@ -738,11 +759,6 @@ def swapAssemblies(self, a1, a2):
         a2 : :py:class:`Assembly <armi.reactor.assemblies.Assembly>`
             The second assembly
 
-        Notes
-        -----
-        The implementation for ``R_ARMI_SHUFFLE_STATIONARY`` occurs within
-        :py:meth:`<armi.physics.fuelCyle.fuelHandlers.FuelHandler._transferStationaryBlocks`.
-
         See Also
         --------
         dischargeSwap : swap assemblies where one is outside the core and the other is inside
@@ -835,10 +851,22 @@ def dischargeSwap(self, incoming, outgoing):
             :id: I_ARMI_SHUFFLE_STATIONARY1
             :implements: R_ARMI_SHUFFLE_STATIONARY
 
-        Notes
-        -----
-        The implementation for ``R_ARMI_SHUFFLE_STATIONARY`` occurs within
-        :py:meth:`<armi.physics.fuelCyle.fuelHandlers.FuelHandler._transferStationaryBlocks`.
+            Before assemblies are moved,
+            calls to the ``_transferStationaryBlocks`` class method to
+            check if there are any block types specified by the user as stationary
+            via the ``stationaryBlockFlags`` case setting. Using these flags, gather
+            blocks from each assembly which should remain stationary and check
+            to make sure that both assemblies have the same number and same
+            height of stationary blocks. If not, return an error.
+
+            If all checks pass, use the :py:meth`~armi.reactor.assemblies.Assembly.remove`
+            and :py:meth:`~armi.reactor.assemblies.Assembly.insert``
+            methods to swap the stationary blocks between the two assemblies.
+
+            Once this process is complete, the actual assembly movement can take
+            place. Through this process, the stationary blocks from the outgoing
+            assembly remain in the original core position, while the stationary
+            blocks from the incoming assembly are discharged with the outgoing assembly.
 
         See Also
         --------