Adding information to init and apps impl tags

terrapower · Jan 17, 2024 · 4dfe974 · 4dfe974
1 parent bceafc9
commit 4dfe974
Show file tree

Hide file tree

Showing 2 changed files with 40 additions and 17 deletions.
diff --git a/armi/__init__.py b/armi/__init__.py
@@ -122,17 +122,29 @@ def init(choice=None, fName=None, cs=None):
         :id: I_ARMI_SETTING1
         :implements: R_ARMI_SETTING
 
+        This method initializes an ARMI run, and if successful returns
+        an Operator. That operator is designed to drive the reactor
+        simulation through time steps to simulate its operator. This
+        method takes in a settings file or object to initialize the
+        operator. Whether a settings file or object is supplied, the
+        operator will be built based on the those settings. Because
+        the total collection of settings can be modified by developers
+        of ARMI applications, providing these settings allow ARMI
+        end-users to define their simulation as granularly as they
+        need to.
+
     Parameters
     ----------
     choice : int, optional
         Automatically run with this item out of the menu
-        that would be produced of existing xml files.
+        that would be produced of existing YAML files.
 
     fName : str, optional
-        An actual case name to load. e.g. ntTwr1.xml
+        The path to a settings file to load: my_case.yaml
 
-    cs : object, optional
-        If supplied, supercede the other case input methods and use the object directly
+    cs : CaseSettings, optional
+        If supplied, this CS object will supercede the other case
+        input methods and use the object directly
 
     Examples
     --------

diff --git a/armi/apps.py b/armi/apps.py
@@ -42,23 +42,23 @@
 
 class App:
     """
-    The main point of customization for the ARMI Framework.
-
-    The App class is intended to be subclassed in order to customize the functionality
-    and look-and-feel of the ARMI Framework for a specific use case. An App contains a
-    plugin manager, which should be populated in ``__init__()`` with a collection of
-    plugins that are deemed suitable for a given application, as well as other methods
-    which provide further customization.
-
-    The base App class is also a good place to expose some more convenient ways to get
-    data out of the Plugin API; calling the ``pluggy`` hooks directly can sometimes be a
-    pain, as the results returned by the individual plugins may need to be merged and/or
-    checked for errors. Adding that logic here reduces boilerplate throughout the rest
-    of the code.
+    The highest-level of abstraction for defining what happens during an ARMI run.
 
     .. impl:: An App has a plugin manager.
         :id: I_ARMI_APP_PLUGINS
         :implements: R_ARMI_APP_PLUGINS
+
+        The App class is intended to be subclassed in order to customize the functionality
+        and look-and-feel of the ARMI Framework for a specific use case. An App contains a
+        plugin manager, which should be populated in ``__init__()`` with a collection of
+        plugins that are deemed suitable for a given application, as well as other methods
+        which provide further customization.
+
+        The base App class is also a good place to expose some more convenient ways to get
+        data out of the Plugin API; calling the ``pluggy`` hooks directly can sometimes be a
+        pain, as the results returned by the individual plugins may need to be merged and/or
+        checked for errors. Adding that logic here reduces boilerplate throughout the rest
+        of the code.
     """
 
     name = "armi"
@@ -130,6 +130,17 @@ def getSettings(self) -> Dict[str, Setting]:
         .. impl:: Applications will not allow duplicate settings.
             :id: I_ARMI_SETTINGS_UNIQUE
             :implements: R_ARMI_SETTINGS_UNIQUE
+
+            Each ARMI application includes a collection of Plugins. Among other
+            things, these plugins can register new settings, that are not amoung
+            the default settings that come with ARMI. This feature provides a
+            lot of utility, so application developers can easily configure
+            their ARMI appliction in customizable ways.
+
+            However, it would get confusing if two different plugins registered
+            a setting with the same name string. Or if a plugin registered a
+            setting with the same name as an ARMI default setting. So this
+            method throws an error if such a situation arises.
         """
         # Start with framework settings
         settingDefs = {