Docs replace asyncore with wasyncore as needed (#210)

* Fix name

* Use versionadded with context, improve reST syntax.

* improve reST syntax.

* Replace asyncore with wasyncore as appropriate

3 files changed, 27 insertions, 17 deletions

diff --git a/docs/arguments.rst b/docs/arguments.rst
index a205e16..dfdbc53 100644
--- a/docs/arguments.rst
+++ b/docs/arguments.rst
@@ -136,15 +136,16 @@ expose_tracebacks
     ``False``.
 
 asyncore_loop_timeout
-    The ``timeout`` value (seconds) passed to ``asyncore.loop`` to run the
-    mainloop.  Default: 1.  (New in 0.8.3.)
+    .. versionadded:: 0.8.3
+        The ``timeout`` value (seconds) passed to ``asyncore.loop`` to run the mainloop.
+        Default: 1.
 
 asyncore_use_poll
-    Boolean: switch from using select() to poll() in ``asyncore.loop``.
-    By default asyncore.loop() uses select() which has a limit of 1024
-    file descriptors. Select() and poll() provide basically the same
-    functionality, but poll() doesn't have the file descriptors limit.
-    Default: False (New in 0.8.6)
+    .. versionadded:: 0.8.6
+        Boolean: switch from using ``select()`` to ``poll()`` in ``asyncore.loop``.
+        By default ``asyncore.loop()`` uses ``select()`` which has a limit of 1024 file descriptors.
+        ``select()`` and ``poll()`` provide basically the same functionality, but ``poll()`` doesn't have the file descriptors limit.
+        Default: False.
 
 url_prefix
     String: the value used as the WSGI ``SCRIPT_NAME`` value.  Setting this to
diff --git a/docs/design.rst b/docs/design.rst
index 591a423..c0d13ef 100644
--- a/docs/design.rst
+++ b/docs/design.rst
@@ -1,11 +1,19 @@
 Design
 ------
 
-Waitress uses a combination of asynchronous and synchronous code to do its
-job.  It handles I/O to and from clients using the :term:`asyncore` library.
+Waitress uses a combination of asynchronous and synchronous code to do its job.
+It handles I/O to and from clients using the :term:`wasyncore`, which is :term:`asyncore` vendored into Waitress.
 It services requests via threads.
 
-The :term:`asyncore` module in the Python standard library:
+.. note::
+    :term:`asyncore` has been deprecated since Python 3.6.
+    Work continues on its inevitable removal from the Python standard library.
+    Its recommended replacement is :mod:`asyncio`.
+
+    Although :term:`asyncore` has been vendored into Waitress as :term:`wasyncore`, you may see references to "asyncore" in this documentation's code examples and API.
+    The terms are effectively the same and may be used interchangeably.
+
+The :term:`wasyncore` module:
 
 - Uses the ``select.select`` function to wait for connections from clients
   and determine if a connected client is ready to receive output.
@@ -37,10 +45,12 @@ channel, and can write back to the channel's output buffer.  When all worker
 threads are in use, scheduled tasks will wait in a queue for a worker thread
 to become available.
 
-I/O is always done asynchronously (by asyncore) in the main thread.  Worker
-threads never do any I/O.  This means that 1) a large number of clients can
-be connected to the server at once and 2) worker threads will never be hung
-up trying to send data to a slow client.
+I/O is always done asynchronously (by :term:`wasyncore`) in the main thread.
+Worker threads never do any I/O.
+This means that
+
+#.  a large number of clients can be connected to the server at once, and
+#.  worker threads will never be hung up trying to send data to a slow client.
 
 No attempt is made to kill a "hung thread".  It's assumed that when a task
 (application logic) starts that it will eventually complete.  If for some
diff --git a/docs/glossary.rst b/docs/glossary.rst
index d874748..d87cc31 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -14,8 +14,8 @@ Glossary
         A Python standard library module for asynchronous communications.  See :mod:`asyncore`.
 
         .. versionchanged:: 1.2.0
-            Waitress has now "vendored" asyncore into itself as ``waitress.wasyncore``.
-            This is to cope with the eventuality that asyncore will be removed from the Python standard library in Python 3.8 or so.
+            Waitress has now "vendored" ``asyncore`` into itself as ``waitress.wasyncore``.
+            This is to cope with the eventuality that ``asyncore`` will be removed from the Python standard library in Python 3.8 or so.
 
     middleware
         *Middleware* is a :term:`WSGI` concept.
@@ -32,4 +32,3 @@ Glossary
         .. versionchanged:: 1.2.0
             Waitress has now "vendored" :term:`asyncore` into itself as ``waitress.wasyncore``.
             This is to cope with the eventuality that ``asyncore`` will be removed from the Python standard library in Python 3.8 or so.
-