docs(enums): add docs to Enum (#1271)

openfisca_core/indexed_enums/__init__.py

@@ -1,25 +1,15 @@
-# Transitional imports to ensure non-breaking changes.
-# Could be deprecated in the next major release.
-#
-# How imports are being used today:
-#
-#   >>> from openfisca_core.module import symbol
-#
-# The previous example provokes cyclic dependency problems
-# that prevent us from modularizing the different components
-# of the library so to make them easier to test and to maintain.
-#
-# How could them be used after the next major release:
-#
-#   >>> from openfisca_core import module
-#   >>> module.symbol()
-#
-# And for classes:
-#
-#   >>> from openfisca_core.module import Symbol
-#   >>> Symbol()
-#
-# See: https://www.python.org/dev/peps/pep-0008/#imports
+"""Enumerations for variables with a limited set of possible values.
+
+These include:
+    * Highest academic level: high school, associate degree, bachelor's degree,
+      master's degree, doctorate…
+    * A household housing occupancy status: owner, tenant, free-lodger,
+      homeless…
+    * The main occupation of a person: employee, freelancer, retired, student,
+      unemployed…
+    * Etc.
+
+"""
 
 from . import types
 from .config import ENUM_ARRAY_DTYPE

openfisca_core/indexed_enums/enum.py

@@ -8,38 +8,48 @@
 
 
 class Enum(t.Enum):
-    """Enum based on `enum34 <https://pypi.python.org/pypi/enum34/>`_, whose items
-    have an index.
+    """Enum based on `enum34 <https://pypi.python.org/pypi/enum34/>`_.
+
+    Its items have an :any:`int` index. This is useful and performant when
+    running simulations on large populations.
+
     """
 
-    # Tweak enums to add an index attribute to each enum item
-    def __init__(self, name: str) -> None:
-        # When the enum item is initialized, self._member_names_ contains the
-        # names of the previously initialized items, so its length is the index
-        # of this item.
+    #: The ``index`` of the ``Enum`` member.
+    index: int
+
+    def __init__(self, *__args: object, **__kwargs: object) -> None:
+        """Tweak :any:`~enum.Enum` to add an index to each enum item.
+
+        When the enum is initialised, ``_member_names_`` contains the names of
+        the already initialized items, so its length is the index of this item.
+
+        Args:
+            *__args: Positional arguments.
+            **__kwargs: Keyword arguments.
+
+        """
+
         self.index = len(self._member_names_)
 
-    # Bypass the slow Enum.__eq__
+    #: Bypass the slow :any:`~enum.Enum.__eq__` method.
     __eq__ = object.__eq__
 
-    # In Python 3, __hash__ must be defined if __eq__ is defined to stay
-    # hashable.
+    #: :meth:`.__hash__` must also be defined so as to stay hashable.
     __hash__ = object.__hash__
 
     @classmethod
     def encode(
         cls,
         array: EnumArray | numpy.int32 | numpy.float32 | numpy.object_,
     ) -> EnumArray:
-        """Encode a string numpy array, an enum item numpy array, or an int numpy
-        array into an :any:`EnumArray`. See :any:`EnumArray.decode` for
-        decoding.
+        """Encode an encodable array into an ``EnumArray``.
 
-        :param numpy.ndarray array: Array of string identifiers, or of enum
-                                    items, to encode.
+        Args:
+            array: Array to encode.
 
-        :returns: An :any:`EnumArray` encoding the input array values.
-        :rtype: :any:`EnumArray`
+        Returns:
+            EnumArray: An ``EnumArray`` with the encoded input values.
 
         For instance: