From f3dbc7dc19ba5703f8f5aa9bf8af3c491b3510f6 Mon Sep 17 00:00:00 2001
From: Scott Gasch <scott@gasch.org>
Date: Sun, 29 May 2022 17:53:26 -0700
Subject: Clean up more docs to work with sphinx.

---
 smart_future.py | 37 +++++++++++++++++++++++++++++++------
 1 file changed, 31 insertions(+), 6 deletions(-)

(limited to 'smart_future.py')

diff --git a/smart_future.py b/smart_future.py
index 7aac8eb..7768599 100644
--- a/smart_future.py
+++ b/smart_future.py
@@ -2,10 +2,11 @@
 
 # © Copyright 2021-2022, Scott Gasch
 
-"""A future that can be treated like the result that it contains and
-will not block until it is used.  At that point, if the underlying
-value is not yet available, it will block until it becomes
-available.
+"""
+A future that can be treated as a substutute for the result that it
+contains and will not block until it is used.  At that point, if the
+underlying value is not yet available yet, it will block until the
+internal result actually becomes available.
 
 """
 
@@ -34,6 +35,19 @@ def wait_any(
     callback: Callable = None,
     log_exceptions: bool = True,
 ):
+    """Await the completion of any of a collection of SmartFutures and
+    invoke callback each time one completes, repeatedly, until they are
+    all finished.
+
+    Args:
+        futures: A collection of SmartFutures to wait on
+        callback: An optional callback to invoke whenever one of the
+            futures completes
+        log_exceptions: Should we log (warning + exception) any
+            underlying exceptions raised during future processing or
+            silently ignore then?
+    """
+
     real_futures = []
     smart_future_by_real_future = {}
     completed_futures: Set[fut.Future] = set()
@@ -64,6 +78,16 @@ def wait_all(
     *,
     log_exceptions: bool = True,
 ) -> None:
+    """Wait for all of the SmartFutures in the collection to finish before
+    returning.
+
+    Args:
+        futures: A collection of futures that we're waiting for
+        log_exceptions: Should we log (warning + exception) any
+            underlying exceptions raised during future processing or
+            silently ignore then?
+    """
+
     real_futures = []
     for x in futures:
         assert isinstance(x, SmartFuture)
@@ -85,8 +109,9 @@ def wait_all(
 
 
 class SmartFuture(DeferredOperand):
-    """This is a SmartFuture, a class that wraps a normal Future and can
-    then be used, mostly, like a normal (non-Future) identifier.
+    """This is a SmartFuture, a class that wraps a normal :class:`Future`
+    and can then be used, mostly, like a normal (non-Future)
+    identifier of the type of that SmartFuture's result.
 
     Using a FutureWrapper in expressions will block and wait until
     the result of the deferred operation is known.
-- 
cgit v1.3