More work to improve documentation generated by sphinx. Also fixes

[pyutils.git] / src / pyutils / parallelize / deferred_operand.py

diff --git a/src/pyutils/parallelize/deferred_operand.py b/src/pyutils/parallelize/deferred_operand.py
index 9edbb9e8072b451ffc13f447235e3da5505bcff6..c234c0574e7a6ba29e810210229cb08db9966c27 100644 (file)
--- a/src/pyutils/parallelize/deferred_operand.py
+++ b/src/pyutils/parallelize/deferred_operand.py
@@ -2,9 +2,20 @@
 
 # © Copyright 2021-2022, Scott Gasch
 
-"""This is a helper class that tries to define every __dunder__ method
-so as to defer that evaluation of an object as long as possible.  It
-is used by smart_future.py as a base class.
+"""This is the base class of
+:class:`pyutils.parallelize.smart_future.SmartFuture`, which is a
+piece of the simple parallelization framework.
+
+This base class is essentially tries to have every Python `__dunder__`
+method defined with a reasonabe default implementation so that, when
+it is used in a manner that requires the value to be known, it calls
+:meth:`DeferredOperand.resolve` and either gets the requisite value or
+blocks until the data necessary to resolve the value is ready.  This
+is meant to enable more transparent :class:`Future` objects that can
+be just used directly.
+
+See :class:`pyutils.parallelize.smart_future.SmartFuture` for more
+information.
 
 """
 
@@ -19,8 +30,10 @@ T = TypeVar('T')
 
 class DeferredOperand(ABC, Generic[T]):
     """A wrapper around an operand whose value is deferred until it is
-    needed (i.e. accessed).  See the subclass :class:`SmartFuture` for
-    an example usage and/or a more useful patten.
+    needed (i.e. accessed).  See the subclass
+    :class:`pyutils.parallelize.smart_future.SmartFuture` for an
+    example usage and/or a more useful patten.
+
     """
 
     @abstractmethod
@@ -29,6 +42,18 @@ class DeferredOperand(ABC, Generic[T]):
 
     @staticmethod
     def resolve(x: Any) -> Any:
+        """
+        When this object is used in a manner that requires it to know
+        its value, this method is called to either return the value or
+        block until it can do so.
+
+        Args:
+            x: the object whose value is required
+
+        Returns:
+            The value of x... immediately if possible, eventually if
+            not possible.
+        """
         while isinstance(x, DeferredOperand):
             x = x._resolve()
         return x