Update documentation.

docs/reference.rst

@@ -2,6 +2,14 @@ API Reference
 #############
 
 
+Note: these docs use ``sphinxcontrib_trio`` to autodetect async methods,
+however as of version 1.0.1 it doesn't correctly mark inherited async methods
+as async; see https://github.com/python-trio/sphinxcontrib-trio/issues/19 .
+For the class methods documented below, if the text starts with "(async)", then
+it is an async method and should be awaited, even if the call signature line
+does not show "await".
+
+
 The Main ``ptadapter`` Module
 =============================
 

ptadapter/__init__.py

@@ -1,14 +1,7 @@
-"""Implements Tor's "managed proxy protocol".
+"""Python interface for Pluggable Transports
 
-This package implements classes used to run a Tor Pluggable Transport
-as server or client. The primary goal is to run Pluggable Transports
-as standalone TCP tunnels.
-
-For more information on the managed proxy protocol, see Tor's official
-implementation of Pluggable Transport interface:
-https://gitweb.torproject.org/pluggable-transports/goptlib.git/tree/
-https://godoc.org/git.torproject.org/pluggable-transports/goptlib.git
-and any torspec documents linked from the above documentations.
+The main module exports the adapter classes, as well as several Named Tuple
+classes used as return values of adapter class methods.
 """
 
 from .adapters import *

ptadapter/adapters.py

@@ -241,7 +241,7 @@ async def _pre_start(self) -> None:
             self._logger.debug('Created tempdir for state: %s', self._state)
 
     async def start(self) -> None:
-        """Start the PT executable and wait until it's ready.
+        """(async) Start the PT executable and wait until it's ready.
 
         "Ready" means that all transports have finished initializing.
         """
@@ -265,7 +265,7 @@ async def start(self) -> None:
             raise
 
     async def stop(self) -> None:
-        """Stop the PT executable.
+        """(async) Stop the PT executable.
 
         First try to signal a graceful exit by closing PT's STDIN (if
         enabled) and wait, then call
@@ -307,7 +307,7 @@ async def stop(self) -> None:
             await self._stack.aclose()
 
     async def wait(self) -> None:
-        """Block until the PT process exit."""
+        """(async) Block until the PT process exit."""
         self._check_started()
         await self._process.wait()
 
@@ -417,7 +417,7 @@ async def open_transport_connection(
             args: Optional[Dict[str, str]],
             **kwargs,
     ) -> Tuple[asyncio.StreamReader, asyncio.StreamWriter]:
-        """Open a connection through a client transport.
+        """(async) Open a connection through a client transport.
 
         This method uses :meth:`get_transport` and
         :func:`asyncio.open_connection`, and their exceptions will not be
@@ -697,7 +697,7 @@ async def authenticate(
             reader: asyncio.StreamReader,
             writer: asyncio.StreamWriter,
     ) -> bool:
-        """Authenticate a connecting client.
+        """(async) Authenticate a connecting client.
 
         Returns:
             True if authentication is successful and False otherwise. The

ptadapter/exceptions.py

@@ -1,6 +1,6 @@
 """Exceptions raised by this package.
 
-The two Enums used in these exceptions are also imported in this module for
+Two Enums used in these exceptions are also imported in this module for
 convenience.
 """