Adding impl text to settings

armi/settings/caseSettings.py

@@ -48,16 +48,17 @@ class Settings:
     """
     A container for run settings, such as case title, power level, and many more.
 
-    It is accessible to most ARMI objects through self.cs (for 'Case Settings').
-    It acts largely as a dictionary, and setting values are accessed by keys.
-
-    The Settings object has a 1-to-1 correspondence with the ARMI settings input file.
-    This file may be created by hand or by the GUI in submitter.py.
-
     .. impl:: Settings are used to define an ARMI run.
         :id: I_ARMI_SETTING0
         :implements: R_ARMI_SETTING
 
+        The Settings object is accessible to most ARMI objects through self.cs
+        (for 'case settings'). It acts largely as a dictionary, and setting values
+        are accessed by keys.
+
+        The Settings object has a 1-to-1 correspondence with the ARMI settings
+        input file. This file may be created by hand or by a GUI.
+
     Notes
     -----
     The actual settings in any instance of this class are immutable.
@@ -112,6 +113,15 @@ def caseTitle(self):
         .. impl:: Define a case title to go with the settings.
             :id: I_ARMI_SETTINGS_META0
             :implements: R_ARMI_SETTINGS_META
+
+            Every Settings object has a "case title"; a string for users to
+            help identify their run. This case title is used in log file
+            names, it is printed during a run, it is frequently used to
+            name the settings file. It is designed to be an easy-to-use
+            and easy-to-understand way to keep track of simulations. The
+            general idea here is that the average analyst that is using
+            ARMI will run many ARMI-based simulations, and there needs
+            to be an easy to identify them all.
         """
         if not self.path:
             return self.defaultCaseTitle

armi/settings/fwSettings/globalSettings.py

@@ -15,8 +15,9 @@
 """
 Framework-wide settings definitions and constants.
 
-This should contain Settings definitions for general-purpose "framework" settings. These
-should only include settings that are not related to any particular physics or plugins.
+This should contain Settings definitions for general-purpose "framework"
+settings. These should only include settings that are not related to any
+particular physics or plugins.
 """
 import os
 from typing import List
@@ -126,9 +127,32 @@ def defineSettings() -> List[setting.Setting]:
         :id: I_ARMI_SETTINGS_POWER
         :implements: R_ARMI_SETTINGS_POWER
 
+        ARMI defines a collection of settings by default to be associated
+        with all runs, and one such setting is ``power``. This is the
+        total thermal power of the reactor. This is designed to be the
+        standard power of the reactor core, to be easily set by the user.
+        There is frequently the need to adjust the power of the reactor
+        at different cycles. That is done by setting the ``powerFractions``
+        setting to a list of fractions of this power.
+
     .. impl:: Define a comment and a versions list to go with the settings.
         :id: I_ARMI_SETTINGS_META1
         :implements: R_ARMI_SETTINGS_META
+
+        Because nuclear analysts have a lot to keep track of when doing
+        various simulations of a reactor, ARMI provides a ``comment``
+        setting that takes an arbitrary string and stores it. This string
+        will be preserved in the settings file and thus in the database,
+        and can provide helpful notes for analysts in the future.
+
+        Likewise, it is helpful to know what versions of software were
+        used in an ARMI application. There is a dictionary-like setting
+        called ``versions`` that allows users to track the versions of:
+        ARMI, their ARMI application, and the versions of all the plugins
+        in their simulation. While it is always helpful to know what
+        versions of software you run, it is particularly needed in nuclear
+        engineering where demands will be made to track the exact
+        versions of code used in simulations.
     """
     settings = [
         setting.Setting(

armi/settings/setting.py

@@ -50,9 +50,10 @@ class Setting:
         :id: I_ARMI_SETTINGS_DEFAULTS
         :implements: R_ARMI_SETTINGS_DEFAULTS
 
-        A Setting object holds all associated information of a setting in ARMI
+        Setting objects hold all associated information of a setting in ARMI
         and should typically be accessed through the Settings class methods
-        rather than directly.
+        rather than directly. The exception being the SettingAdapter class
+        designed for additional GUI related functionality.
 
         Setting subclasses can implement custom ``load`` and ``dump`` methods
         that can enable serialization (to/from dicts) of custom objects. When