Add and improve docstrings

armi/bookkeeping/db/database3.py

@@ -988,7 +988,11 @@ def _writeParams(self, h5group, comps):
                 temp = [c.p.get(paramDef.name, paramDef.default) for c in comps]
                 if paramDef.serializer is not None:
                     data, sAttrs = paramDef.serializer.pack(temp)
-                    assert data.dtype.kind != "O"
+                    assert (
+                        data.dtype.kind != "O"
+                    ), "{} failed to convert {} to a numpy-supported type.".format(
+                        paramDef.serializer.__name__, paramDef.name
+                    )
                     attrs.update(sAttrs)
                     attrs[_SERIALIZER_NAME] = paramDef.serializer.__name__
                     attrs[_SERIALIZER_VERSION] = paramDef.serializer.version

armi/reactor/parameters/parameterDefinitions.py

@@ -157,6 +157,10 @@ def pack(data: Sequence[any]) -> Tuple[numpy.ndarray, Dict[str, any]]:
         The should perform the fundamental packing operation, returning the packed data
         and any metadata ("attributes") that would be necessary to unpack the data. The
         class's version is always stored, so no need to provide it as an attribute.
+
+        See Also
+        --------
+        armi.reactor.flags.FlagSerializer.pack
         """
         raise NotImplementedError()
 

armi/utils/flags.py

@@ -118,9 +118,9 @@ class Flag(metaclass=_FlagMeta):
         practically unlimited number of fields. *However*, including more flags than can
         be represented in the system-native integer types may lead to strange behavior
         when interfacing with non-pure Python code. For instance, exceeding 64 fields
-        makes the underlying value not trivially-storable in an HDF5 file. If we ever
-        want to store flags in an HDF5 file, we will need to develop some method of
-        encoding these when they are too wide.
+        makes the underlying value not trivially-storable in an HDF5 file. In such
+        circumstances, the ``from_bytes()`` and ``to_bytes()`` methods are available to
+        represent a Flag's values in smaller chunks.
     """
 
     # for pylint. Set by metaclass
@@ -185,14 +185,23 @@ def _resolveAutos(cls, fields: Sequence[str]) -> List[Tuple[str, int]]:
 
     @classmethod
     def width(cls):
+        """
+        Return the number of bytes needed to store all of the flags on this class.
+        """
         return cls._width
 
     @classmethod
     def fields(cls):
+        """
+        Return a dictionary containing a mapping from field name to integer value.
+        """
         return cls._nameToValue
 
     @classmethod
     def sortedFields(cls):
+        """
+        Return a list of all field names, sorted by increasing integer value.
+        """
         return [i[0] for i in sorted(cls._nameToValue.items(), key=lambda item: item[1])]
 
     @classmethod
@@ -233,6 +242,14 @@ def extend(cls, fields: Dict[str, Union[int, auto]]):
     def to_bytes(self, byteorder="little"):
         """
         Return a byte stream representing the flag.
+
+        This is useful when storing Flags in a data type of limited size. Python ints
+        can be of arbitrary size, while most other systems can only represent integers
+        of 32 or 64 bits. For compatibiliy, this function allows to convert the flags to
+        a sequence of single-byte elements.
+
+        Note that this uses snake_case to mimic the method on the Python-native int
+        type.
         """
         return self._value.to_bytes(self.width(), byteorder=byteorder)
 

armi/utils/tests/test_flags.py

@@ -47,6 +47,8 @@ class F(Flag):
         self.assertTrue(int(F.baz) > int(F.foo))
 
     def test_extend(self):
+        """Ensure the set of flags can be programmatically extended."""
+
         class F(Flag):
             foo = auto()
             bar = 1