improve docstring of package visitors

Author: Deric-W

docs/api/visitors.rst

@@ -5,6 +5,7 @@ Package visitors
    :maxdepth: 2
 
    visitors/substitution
+   visitors/normalisation
    visitors/walking
 
 .. automodule:: lambda_calculus.visitors

docs/api/visitors/normalisation.rst

@@ -0,0 +1,8 @@
+Module normalisation
+====================
+
+.. toctree::
+   :maxdepth: 2
+
+.. automodule:: lambda_calculus.visitors.normalisation
+    :members:

lambda_calculus/visitors/__init__.py

@@ -22,49 +22,98 @@
 
 class Visitor(ABC, Generic[T, V]):
     """
-    ABC for Visitors visiting Terms
-    The visitor is responsible to visit child terms
+    ABC for Visitors visiting Terms.
+
+    The visitor is responsible for visiting child terms.
+
+    Type Variables:
+
+        T: represents the type of the result produced by visiting terms
+        V: represents the type of variables used in terms
     """
 
     __slots__ = ()
 
     @final
     def visit(self, term: terms.Term[V]) -> T:
-        """visit a term"""
+        """
+        Visit a term
+
+        :param  term: term to visit
+        :return: Result of calling :meth:`.terms.Term.accept` with self as argument
+        """
         return term.accept(self)
 
     @abstractmethod
     def visit_variable(self, variable: terms.Variable[V]) -> T:
-        """visit a Variable term"""
+        """
+        Visit a Variable term.
+
+        :param variable: variable term to visit
+        :return: value as required by its type variable
+        """
         raise NotImplementedError()
 
     @abstractmethod
     def visit_abstraction(self, abstraction: terms.Abstraction[V]) -> T:
-        """visit an Abstraction term"""
+        """
+        Visit an Abstraction term
+
+        The body is not automatically visited.
+
+        :param abstraction: abstraction term to visit
+        :return: value as required by its type variable
+        """
         raise NotImplementedError()
 
     @abstractmethod
     def visit_application(self, application: terms.Application[V]) -> T:
-        """visit an Application term"""
+        """
+        Visit an Application term
+
+        The abstraction and argument are not automatically visited.
+
+        :param appliation: application term to visit
+        :return: value as required by its type variable
+        """
         raise NotImplementedError()
 
 
 class BottomUpVisitor(Visitor[T, V]):
-    """ABC for visitors which visit child terms first"""
+    """
+    ABC for visitors which visit child terms first
+
+    Child terms are automatically visited.
+    """
 
     __slots__ = ()
 
     @final
     def visit_abstraction(self, abstraction: terms.Abstraction[V]) -> T:
-        """visit an Abstraction term"""
+        """
+        Visit an Abstraction term
+
+        The body is visited before calling :meth:`ascend_abstraction`.
+
+        :param abstraction: abstraction term to visit
+        :return: value returned by :meth:`ascend_abstraction`
+        """
         return self.ascend_abstraction(
             abstraction,
             abstraction.body.accept(self)
         )
 
     @final
     def visit_application(self, application: terms.Application[V]) -> T:
-        """visit an Application term"""
+        """
+        Visit an Application term
+
+        The abstraction and argument are visited
+        before calling :meth:`ascend_application`.
+
+        :param application: application term to visit
+        :return: value returned by :meth:`ascend_application`
+        """
         return self.ascend_application(
             application,
             application.abstraction.accept(self),
@@ -73,26 +122,53 @@ def visit_application(self, application: terms.Application[V]) -> T:
 
     @abstractmethod
     def ascend_abstraction(self, abstraction: terms.Abstraction[V], body: T) -> T:
-        """visit an Abstraction term after visiting its body"""
+        """
+        Visit an Abstraction term after visiting its body.
+
+        :param abstraction: abstraction term to visit
+        :param body: value produced by visiting its body
+        :return: value as required by its type variable
+        """
         raise NotImplementedError()
 
     @abstractmethod
     def ascend_application(self, application: terms.Application[V], abstraction: T, argument: T) -> T:
-        """visit an Application term after visiting its abstraction and argument"""
+        """
+        Visit an Application term after visiting its abstraction and argument.
+
+        :param application: application term to visit
+        :param abstraction: value produced by visiting its abstraction
+        :param argument: value produced by visiting its argument
+        :return: value as required by its type variable
+        """
         raise NotImplementedError()
 
 
 class DeferrableVisitor(Visitor[T, V]):
-    """ABC for visitors which can visit terms top down lazyly"""
+    """
+    ABC for visitors which can visit terms top down lazyly.
+    """
 
     __slots__ = ()
 
     @abstractmethod
     def defer_abstraction(self, abstraction: terms.Abstraction[V]) -> tuple[T, DeferrableVisitor[T, V] | None]:
-        """visit an Abstraction term and return the visitor used to visit its body"""
+        """
+        Visit an Abstraction term.
+
+        :param abstraction: abstraction term to visit
+        :return: tuple containing a value as required by its type variable
+                 and a visitor to be used for visiting its body
+        """
         raise NotImplementedError()
 
     @abstractmethod
     def defer_application(self, application: terms.Application[V]) -> tuple[T, DeferrableVisitor[T, V] | None, DeferrableVisitor[T, V] | None]:
-        """visit an Application term and return the visitors used to visit its abstraction and argument"""
+        """
+        Visit an Application term.
+
+        :param abstraction: application term to visit
+        :return: tuple containing a value as required by its type variable
+                 and visitors to be used for visiting its abstraction and argument
+        """
         raise NotImplementedError()

lambda_calculus/visitors/normalisation.py

@@ -1,6 +1,6 @@
 #!/usr/bin/python3
 
-"""Visitor for normalisation"""
+"""Visitor for term normalisation"""
 
 from __future__ import annotations
 from collections.abc import Iterator
@@ -22,7 +22,9 @@
 
 @unique
 class Conversion(Enum):
-    """Conversion performed by normalisation"""
+    """
+    Conversion performed by normalisation
+    """
     ALPHA = 0
     BETA = 1
 
@@ -32,28 +34,54 @@ class BetaNormalisingVisitor(Visitor[Iterator[Step], str]):
     """
     Visitor which transforms a term into its beta normal form,
     yielding intermediate steps until it is reached
+
+    No steps are yielded if the term is already in its beta normal form.
+
+    Remember that some terms dont thave a beta normal form and
+    can cause infinite recursion.
     """
 
     __slots__ = ()
 
     def skip_intermediate(self, term: terms.Term[str]) -> terms.Term[str]:
-        """return the beta normal form directly"""
+        """
+        Calculate the beta normal form directly.
+        
+        :param term: term which should be transformed into ist beta normal form
+        :return: new term representing the beta normal form if it exists
+        """
         result = term
         for _, intermediate in term.accept(self):
             result = intermediate
         return result
 
     def visit_variable(self, variable: terms.Variable[str]) -> Iterator[Step]:
-        """visit a Variable term"""
+        """
+        Visit a Variable term.
+
+        :param variable: variable term to visit
+        :return: empty Iterator, variables are already in beta normal form
+        """
         return iter(())
 
     def visit_abstraction(self, abstraction: terms.Abstraction[str]) -> Iterator[Step]:
-        """visit an Abstraction term"""
+        """
+        Visit an Abstraction term.
+
+        :param abstraction: abstraction term to visit
+        :return: Iterator yielding steps performed on its body
+        """
         results = abstraction.body.accept(self)
         return map(lambda s: (s[0], terms.Abstraction(abstraction.bound, s[1])), results)
 
     def beta_reducation(self, abstraction: terms.Abstraction[str], argument: terms.Term[str]) -> Generator[Step, None, terms.Term[str]]:
-        """perform beta reduction of an application"""
+        """
+        Perform beta reduction of an application.
+        
+        :param abstraction: abstraction of the application
+        :param argument: argument of the application
+        :return: Generator yielding steps and returning the reduced term
+        """
         conversions = CountingSubstitution.from_substitution(abstraction.bound, argument).trace()
         reduced = yield from map(
             lambda body: (
@@ -66,7 +94,15 @@ def beta_reducation(self, abstraction: terms.Abstraction[str], argument: terms.T
         return reduced      # type: ignore
 
     def visit_application(self, application: terms.Application[str]) -> Iterator[Step]:
-        """visit an Application term"""
+        """
+        Visit an Application term
+
+        The abstraction and argument are not automatically visited.
+
+        :param application: application term to visit
+        :return: steps for performing beta reduction if possible
+                 and performed on its result or abstraction and argument
+        """
         if isinstance(application.abstraction, terms.Abstraction):
             # normal order dictates we reduce the leftmost outermost redex first
             reduced = yield from self.beta_reducation(application.abstraction, application.argument)

lambda_calculus/visitors/walking.py

@@ -16,18 +16,35 @@
 
 
 class DepthFirstVisitor(BottomUpVisitor[Iterator["terms.Term[V]"], V]):
-    """Visitor yielding subterms depth first"""
+    """
+    Visitor yielding subterms depth first
+
+    Type Variables:
+
+        V: represents the type of variables used in terms
+    """
 
     def visit_variable(self, variable: terms.Variable[V]) -> Iterator[terms.Term[V]]:
-        """visit a Variable term"""
+        """
+        Visit a Variable term.
+
+        :param variable: variable term to visit
+        :return: Iterator yielding the term
+        """
         yield variable
 
     def ascend_abstraction(
         self,
         abstraction: terms.Abstraction[V],
         body: Iterator[terms.Term[V]]
     ) -> Iterator[terms.Term[V]]:
-        """visit an Abstraction term after visiting its body"""
+        """
+        Visit an Abstraction term after visiting its body.
+
+        :param abstraction: abstraction term to visit
+        :param body: Iterator produced by visiting its body
+        :return: term appended to its body Iterator
+        """
         yield from body
         yield abstraction
 
@@ -37,7 +54,14 @@ def ascend_application(
         abstraction: Iterator[terms.Term[V]],
         argument: Iterator[terms.Term[V]]
     ) -> Iterator[terms.Term[V]]:
-        """visit an Application term after visiting its abstraction and argument"""
+        """
+        Visit an Application term after visiting its abstraction and argument.
+
+        :param application: application term to visit
+        :param abstraction: Iterator produced by visiting its abstraction
+        :param argument: Iterator produced by visiting its argument
+        :return: term appended to its abstraction and argument Iterators
+        """
         yield from abstraction
         yield from argument
         yield application