add docstring for consolidate_enactments function

authorityspoke/enactments.py

@@ -585,6 +585,16 @@ def __gt__(self, other) -> bool:
 
 
 def consolidate_enactments(enactments: List[Enactment]) -> List[Enactment]:
+    """
+    Consolidate any overlapping :class:`Enactment`\s in a :class:`list`.
+
+    :param enactments:
+        a list of :class:`Enactment`\s that may include overlapping
+        legislative text within the same section
+
+    :returns:
+        a list of :class:`Enactment`\s without overlapping text
+    """
     consolidated: List[Enactment] = []
     while enactments:
         match_made = False

authorityspoke/procedures.py

@@ -1,7 +1,8 @@
 """
-Descriptions of changes in litigation, without specifying
-whether they are mandatory or universal, or specifying the
-:class:`.Enactment`\s that might require them.
+Descriptions of procedural changes in litigation.
+
+Does not specify whether they are mandatory or universal,
+or specify the :class:`.Enactment`\s that might require them.
 """
 
 from __future__ import annotations
@@ -103,7 +104,7 @@ def __add__(self, other: Procedure) -> Optional[Procedure]:
 
     def __or__(self, other: Procedure) -> Optional[Procedure]:
         """
-        Combines two :class:`Procedure`\s into one.
+        Combine two :class:`Procedure`\s into one.
 
         The new :class:`Procedure` will have all of the ``inputs``, ``outputs``,
         and ``despite`` :class:`.Factor`\s of both ``self`` and ``other``.
@@ -208,6 +209,27 @@ def generic_factors(self) -> List[Optional[Factor]]:
             }
         )
 
+    def add_factor(self, incoming: Factor, role: str = "inputs") -> Procedure:
+        """
+        Add an output, input, or despite :class:`.Factor`.
+
+        :param incoming:
+            the new :class:`.Factor` to be added to input, output, or despite
+
+        :param role:
+            specifies whether the new :class:`.Factor` should be added to
+            input, output, or despite
+
+        :returns:
+            a new version of ``self`` with the specified change
+        """
+
+        if role not in self.context_factor_names:
+            raise ValueError(f"'role' must be one of {self.context_factor_names}")
+        old_factors = self.__dict__.get(role) or []
+        new_factors = list(old_factors) + [incoming]
+        return self.evolve({role: new_factors})
+
     def consistent_factor_groups(
         self,
         self_factors: Tuple[Factor],
@@ -251,13 +273,6 @@ def consistent_factor_groups(
                         return False
         return True
 
-    def add_factor(self, incoming: Factor, role: str = "inputs") -> Procedure:
-        if role not in self.context_factor_names:
-            raise ValueError(f"'role' must be one of {self.context_factor_names}")
-        old_factors = self.__dict__.get(role) or []
-        new_factors = list(old_factors) + [incoming]
-        return self.evolve({role: new_factors})
-
     def contradiction_between_outputs(
         self, other: Procedure, matches: Dict[Factor, Factor]
     ) -> bool:

authorityspoke/rules.py

@@ -24,7 +24,6 @@
 
 @dataclass(frozen=True)
 class Rule(Factor):
-
     """
     A statement of a legal doctrine about a :class:`.Procedure` for litigation.
 
@@ -131,7 +130,7 @@ def __post_init__(self):
 
     def __add__(self, other) -> Optional[Rule]:
         """
-        Create new :class:`Rule` if ``self`` can satisfy the :attr:`inputs` of ``other``
+        Create new :class:`Rule` if ``self`` can satisfy the :attr:`inputs` of ``other``.
 
         If both ``self`` and ``other`` have False for :attr:`universal`,
         or if either has ``False`` for :attr:`rule_valid'\,
@@ -680,7 +679,13 @@ def __len__(self):
 
     def has_all_same_enactments(self, other: Rule) -> bool:
         """
-        Test if ``self`` has :class:`.Enactment`\s with same meanings as ``other``\'s
+        Test if ``self`` has :class:`.Enactment`\s with same meanings as ``other``\'s.
+
+        :param other:
+            another :class:`Rule` to compare to ``self``.
+
+        :returns:
+            whether the :meth:`~.Enactment.means` test passes for all :class:`.Enactment`\s
         """
         for enactment_group in self.enactment_attr_names:
             if not all(

changelog.md

@@ -1,9 +1,8 @@
-=========
 Changelog
 =========
 
 dev
-===
+---
 
 - Merge ProceduralRule class with Rule
 - Ignore was/were differences in Predicate content text
@@ -15,7 +14,7 @@ dev
 - Create function to consolidate list of Enactments
 
 0.1.0 (2019-06-10)
-==================
+------------------
 
 - Add Regime and Jurisdiction classes to organize Enactments
 - Add TextQuoteSelector class to select text from Enactments