update rsa module docs

Author: bygu4

pyformlang/rsa/box.py

@@ -1,6 +1,4 @@
-"""
-Representation of a box for recursive automaton
-"""
+"""Representation of a box for recursive automaton."""
 
 from typing import Set, Hashable, Any
 
@@ -11,71 +9,70 @@
 
 
 class Box:
-    """ Represents a box for recursive automaton
-
-    This class represents a box for recursive automaton
+    """Representation of a box for recursive automaton.
 
     Parameters
     ----------
-    enfa : :class:`~pyformlang.finite_automaton.EpsilonNFA`
-        A epsilon nfa
-    nonterminal : :class:`~pyformlang.finite_automaton.Symbol`
-        A nonterminal for epsilon nfa
-
+    dfa:
+        The deterministic automaton to describe the box.
+    nonterminal:
+        A nonterminal for `dfa`.
     """
 
     def __init__(self,
                  dfa: DeterministicFiniteAutomaton,
                  nonterminal: Hashable) -> None:
+        """Initializes the box."""
         self._dfa = dfa
         self._nonterminal = to_symbol(nonterminal)
 
     @property
     def dfa(self) -> DeterministicFiniteAutomaton:
-        """ Box's dfa """
+        """Gets the deterministic automaton of the box."""
         return self._dfa
 
     @property
     def nonterminal(self) -> Symbol:
-        """ Box's nonterminal """
+        """Gets the nonterminal of the box."""
         return self._nonterminal
 
     @property
     def start_states(self) -> Set[State]:
-        """ The start states """
+        """Gets the start states of the box."""
         return self._dfa.start_states
 
     @property
     def final_states(self) -> Set[State]:
-        """ The final states """
+        """Gets the final states of the box."""
         return self._dfa.final_states
 
     def is_equivalent_to(self, other: "Box") -> bool:
-        """ Check whether two boxes are equivalent
+        """Checks whether two boxes are equivalent.
 
         Parameters
         ----------
-        other : :class:`~pyformlang.rsa.Box`
-            A sequence of input symbols
+        other:
+            An other box.
 
         Returns
-        ----------
-        are_equivalent : bool
-            Whether the two boxes are equivalent or not
+        -------
+        Whether the two boxes are equivalent or not.
         """
         return self._dfa.is_equivalent_to(other.dfa) \
             and self.nonterminal == other.nonterminal
 
     def __eq__(self, other: Any) -> bool:
+        """Checks whether the current box is equal to the given object."""
         if not isinstance(other, Box):
             return False
         return self.is_equivalent_to(other)
 
     def __hash__(self) -> int:
+        """Gets the hash of the box."""
         return hash(self.nonterminal)
 
     def to_subgraph_dot(self) -> str:
-        """Creates a named subgraph representing a box"""
+        """Creates a named subgraph representing a box."""
         graph = self._dfa.to_networkx()
         strange_nodes = []
         nonterminal = str(self.nonterminal) \

pyformlang/rsa/recursive_automaton.py

@@ -1,6 +1,4 @@
-"""
-Representation of a recursive automaton
-"""
+"""Representation of a recursive automaton."""
 
 from typing import Dict, Set, AbstractSet, Optional, Hashable, Any
 
@@ -13,22 +11,20 @@
 
 
 class RecursiveAutomaton:
-    """ Represents a recursive automaton
-
-    This class represents a recursive automaton.
+    """Representation of a recursive automaton.
 
     Parameters
     ----------
-    start_box : :class:`~pyformlang.rsa.Box`
-        Start box
-    boxes : set of :class:`~pyformlang.rsa.Box`
-        A finite set of boxes
-
+    start_box:
+        A start box of the recursive automaton.
+    boxes:
+        A finite set of boxes.
     """
 
     def __init__(self,
                  start_box: Box,
                  boxes: AbstractSet[Box]) -> None:
+        """Initializes the recursive automaton."""
         self._nonterminal_to_box: Dict[Symbol, Box] = {}
         self._start_nonterminal = start_box.nonterminal
         if start_box not in boxes:
@@ -38,62 +34,58 @@ def __init__(self,
 
     @property
     def nonterminals(self) -> Set[Symbol]:
-        """ The set of nonterminals """
+        """Gets the set of nonterminals of the automaton."""
         return set(self._nonterminal_to_box.keys())
 
     @property
     def boxes(self) -> Set[Box]:
-        """ The set of boxes """
+        """Gets the set of boxes of the automaton."""
         return set(self._nonterminal_to_box.values())
 
     @property
     def start_nonterminal(self) -> Symbol:
-        """ The start nonterminal """
+        """Gets the start nonterminal of the automaton."""
         return self._start_nonterminal
 
     @property
     def start_box(self) -> Box:
-        """ The start box """
+        """Gets the start box of the automaton."""
         return self._nonterminal_to_box[self.start_nonterminal]
 
     def get_box_by_nonterminal(self, nonterminal: Hashable) -> Optional[Box]:
-        """
-        Box by nonterminal
+        """Gets a box by the given nonterminal.
 
         Parameters
         ----------
-        nonterminal: :class:`~pyformlang.finite_automaton.Symbol` | str
-            the nonterminal of which represents a box
+        nonterminal:
+            A nonterminal representing a box.
 
         Returns
-        -----------
-        box : :class:`~pyformlang.rsa.Box` | None
-            box represented by given nonterminal
+        -------
+        The box represented by the given nonterminal.
         """
-
         nonterminal = to_symbol(nonterminal)
         return self._nonterminal_to_box.get(nonterminal, None)
 
     def get_number_boxes(self) -> int:
-        """ Size of set of boxes """
+        """Gets the number of boxes in the current automaton."""
         return len(self._nonterminal_to_box)
 
     @classmethod
     def from_regex(cls, regex: Regex, start_nonterminal: Hashable) \
             -> "RecursiveAutomaton":
-        """ Create a recursive automaton from regular expression
+        """Creates a recursive automaton from regular expression.
 
         Parameters
-        -----------
-        regex : :class:`~pyformlang.regular_expression.Regex`
-            The regular expression
-        start_nonterminal : :class:`~pyformlang.finite_automaton.Symbol` | str
-            The start nonterminal for the recursive automaton
+        ----------
+        regex:
+            The regular expression to create automaton from.
+        start_nonterminal:
+            The start nonterminal for the recursive automaton.
 
         Returns
-        -----------
-        rsa : :class:`~pyformlang.rsa.RecursiveAutomaton`
-            The new recursive automaton built from regular expression
+        -------
+        The new recursive automaton built from regular expression.
         """
         start_nonterminal = to_symbol(start_nonterminal)
         box = Box(regex.to_minimal_dfa(), start_nonterminal)
@@ -102,21 +94,18 @@ def from_regex(cls, regex: Regex, start_nonterminal: Hashable) \
     @classmethod
     def from_ebnf(cls, text: str, start_nonterminal: Hashable = "S") \
             -> "RecursiveAutomaton":
-        """ Create a recursive automaton from ebnf \
-            (ebnf = Extended Backus-Naur Form)
+        """Creates a recursive automaton from Extended Backus-Naur Form.
 
         Parameters
         -----------
-        text : str
-            The text of transform
-        start_nonterminal : \
-            :class:`~pyformlang.finite_automaton.Symbol` | str, optional
-            The start nonterminal, S by default
+        text:
+            The text of transform.
+        start_nonterminal:
+            The start nonterminal.
 
         Returns
-        -----------
-        rsa : :class:`~pyformlang.rsa.RecursiveAutomaton`
-            The new recursive automaton built from context-free grammar
+        -------
+        The new recursive automaton built from context-free grammar.
         """
         start_nonterminal = to_symbol(start_nonterminal)
         productions: Dict[Hashable, str] = {}
@@ -148,29 +137,34 @@ def from_ebnf(cls, text: str, start_nonterminal: Hashable = "S") \
         return RecursiveAutomaton(start_box, boxes)
 
     def is_equal_to(self, other: "RecursiveAutomaton") -> bool:
-        """
-        Check whether two recursive automata are equals by boxes.
+        """Check whether two recursive automata are equal by boxes.
+
         Not equivalency in terms of formal languages theory, just mapping boxes
 
         Parameters
         ----------
-        other : :class:`~pyformlang.rsa.RecursiveAutomaton`
-            The input recursive automaton
+        other:
+            The other recursive automaton.
 
         Returns
-        ----------
-        are_equivalent : bool
-            Whether the two recursive automata are equals or not
+        -------
+        Whether the two recursive automata are equal or not.
         """
         return self.boxes == other.boxes
 
     def __eq__(self, other: Any) -> bool:
+        """Checks if the current automaton is equal to the given object."""
         if not isinstance(other, RecursiveAutomaton):
             return False
         return self.is_equal_to(other)
 
     def to_dot(self) -> str:
-        """ Create dot representation of recursive automaton """
+        """Creates dot representation of recursive automaton.
+
+        Returns
+        -------
+        The dot representation of current recursive automaton.
+        """
         dot_string = 'digraph "" {'
         for box in self._nonterminal_to_box.values():
             dot_string += f'\n{box.to_subgraph_dot()}'