inline docs improvements

txtorcon/controller.py

@@ -379,7 +379,20 @@ def config(self):
     # or ...?
     def create_onion_endpoint(self, port, private_key=None):
         """
-        for "real" args, see onion.py in the hidden-services API branch
+        Returns an object that implements IStreamServerEndpoint, which
+        will create an "ephemeral" Onion service when ``.listen()`` is
+        called. This uses the ``ADD_ONION`` tor control-protocol command.
+
+        :param private_key: if not None (the default), this should be
+            the same blob of key material that you received from a
+            previous call to this method. "Retrieved" here means by
+            accessing the ``.onion_private_key`` attribute of the
+            object returned from ``.listen()`` (see
+            :class:`txtorcon.IHiddenService` and
+            :meth:`txtorcon.TCPHiddenServiceEndpoint.listen`) which
+            will be a :class:`txtorcon.TorOnionListeningPort` -- and
+            therefore implments :class:`txtorcon.IOnionService` (XXX
+            FIXME it implements IHiddenService).
         """
         # note, we're just depending on this being The Ultimate
         # Everything endpoint. Which seems fine, because "normal"

txtorcon/endpoints.py

@@ -435,23 +435,19 @@ def _tor_progress_update(self, prog, tag, summary):
 
     @defer.inlineCallbacks
     def listen(self, protocolfactory):
-        """Implement :api:`twisted.internet.interfaces.IStreamServerEndpoint
+        """
+        Implement :api:`twisted.internet.interfaces.IStreamServerEndpoint
         <IStreamServerEndpoint>`.
 
         Returns a Deferred that delivers an
         :api:`twisted.internet.interfaces.IListeningPort` implementation.
 
-        This port can also be adapted to two other interfaces:
-
+        This port can also be adapted to
         :class:`txtorcon.IHiddenService` so you can get the
         `onion_uri` and `onion_private_key` members (these correspond
         to "hostname" and "private_key" from the HiddenServiceDir Tor
         is using).
 
-        :class:`txtorcon.IProgressProvider` can provide you progress
-        updates while Tor is launched. Note that Tor is not always
-        launched when calling this listen() method.
-
         At this point, Tor will have fully started up and successfully
         accepted the hidden service's config.
 
@@ -462,7 +458,6 @@ def listen(self, protocolfactory):
         It is "connection_dir_client_reached_eof(): Uploaded
         rendezvous descriptor (status 200 ("Service descriptor (v2)
         stored"))" at INFO level.
-
         """
 
         self.protocolfactory = protocolfactory
@@ -634,6 +629,8 @@ def __init__(self, onion_uri, private_key):
         self.private_key = private_key
 
 
+# XXX should implement IOnionService
+# ...so what shall implement IOnionClients etc? need multiple TorOnionListeningPort impls?
 @implementer(IListeningPort, IHiddenService)
 class TorOnionListeningPort(object):
     """