Clarify and update some more documentation.

Author: ubernostrum

README.rst

@@ -18,8 +18,7 @@ Two API clients are available from this library:
 
 Aside from one being sync and the other async, the two clients expose
 identical APIs, and implement all methods of `the Akismet web API
-<https://akismet.com/developers/>`_, including the v1.2 key and API
-usage metrics.
+<https://akismet.com/developers/>`_.
 
 To use this library, you will need to obtain an Akismet API key and
 register a site for use with the Akismet web service; you can do this
@@ -29,6 +28,9 @@ variables ``PYTHON_AKISMET_API_KEY`` and ``PYTHON_AKISMET_BLOG_URL``,
 and they will be automatically detected and used.
 
 You can then construct a client instance and call its methods. For
+creating a long-lived API client instance, it's recommended that you
+use the ``validated_client()`` constructor method, which will
+automatically validate your API key with the Akismet web service. For
 example, to check a submitted forum post for spam:
 
 .. code-block:: python
@@ -61,19 +63,9 @@ Or using the asynchronous client:
    ):
        # This piece of content was classified as spam; handle it appropriately.
 
-Note that in both cases the client instance is created via the
-alternate constructor ``validated_client()``. This is recommended
-instead of using the default constructor (i.e., directly calling
-``akismet.SyncClient()`` or ``akismet.AsyncClient()``); the
-``validated_client()`` constructor will perform automatic discovery of
-the environment-variable configuration and validate the configuration
-with the Akismet web service before returning the client, while
-directly constructing an instance will not (so if you do directly
-construct an instance, you must manually provide and validate its
-configuration).
-
-You can also use either client class as a context manager. This also
-will validate the configuration for you prior to returning the client:
+You can also use either client class as a context manager. This does
+*not* require the ``validated_client()`` constructor, because your API
+key is validated on entering the ``with`` block.
 
 .. code-block:: python
 

docs/usage.rst

@@ -41,12 +41,12 @@ API client creation and basic use
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To create an Akismet API client, call the ``validated_client()`` constructor
-method; this will automatically read your Akismet API key and site URL from the
-environment variables, and validate them with Akismet (see :ref:`the FAQ
-<alt-constructor>` for an explanation of why this is done through an alternate
-constructor). If they're not valid, or if they're not found in the environment
-variables mentioned above, you'll get an :exc:`akismet.ConfigurationError`
-exception.
+method of the appropriate client class; this will automatically read your
+Akismet API key and site URL from the environment variables, and validate them
+with Akismet (see :ref:`the FAQ <alt-constructor>` for an explanation of why
+this is done through an alternate constructor). If they're not valid, or if
+they're not found in the environment variables mentioned above, you'll get an
+:exc:`akismet.ConfigurationError` exception.
 
 .. tab:: Sync
 
@@ -65,9 +65,9 @@ exception.
       akismet_client = await akismet.AsyncClient.validated_client()
 
 
-If you're not able to, or don't want to, set the environment variables, you can
-create a :class:`~akismet.Config` instance and use that to manually configure
-your Akismet API client:
+If don't want to or can't set the environment variables you can use a
+:class:`~akismet.Config` instance and use that to manually configure your
+Akismet API client:
 
 .. tab:: Sync
 
@@ -103,8 +103,8 @@ following arguments:
   you can also pass other values depending on the type of user-submitted
   content you're dealing with.
 
-* ``comment_author`` and/or ``comment_email`` -- The identifier (such as a
-  username) and/or the email address of the user who submitted the content.
+* ``comment_author`` and/or ``comment_author_email`` -- The identifier (such as
+  a username) and/or the email address of the user who submitted the content.
 
 For example, suppose you're using `the Django web framework
 <https://www.djangoproject.com>`_ to build an online forum. You might write a
@@ -301,9 +301,9 @@ use, it's available as :data:`akismet.USER_AGENT`.
       )
 
 Finally, note that if all you want is to set a custom timeout value for
-connections to the Akismet web service, you *can* do this with a custom HTTP
-client, or you can simply set the environment variable
-``PYTHON_AKISMET_TIMEOUT`` as described above.
+connections to the Akismet web service, you do not need a custom HTTP client;
+you can set the environment variable ``PYTHON_AKISMET_TIMEOUT`` as described
+above.
 
 
 .. _usage-testing:

src/akismet/__init__.py

@@ -10,17 +10,18 @@
   (``async``/``await``/non-blocking) HTTP requests to the Akismet web service.
 
 Aside from one being sync and the other async, the two clients expose identical APIs,
-and implement all methods of `the Akismet web API <https://akismet.com/developers/>`_,
-including the v1.2 key and API usage metrics.
+and implement all methods of `the Akismet web API <https://akismet.com/developers/>`_.
 
 To use this library, you will need to obtain an Akismet API key and register a site for
 use with the Akismet web service; you can do this at <https://akismet.com>. Once you
 have a key and corresponding registered site URL to use with it, place them in the
 environment variables ``PYTHON_AKISMET_API_KEY`` and ``PYTHON_AKISMET_BLOG_URL``, and
 they will be automatically detected and used.
 
-You can then construct a client instance and call its methods. For example, to check a
-submitted forum post for spam:
+You can then construct a client instance and call its methods. For creating a long-lived
+API client instance, it's recommended that you use the ``validated_client()``
+constructor method, which will automatically validate your API key with the Akismet web
+service. For example, to check a submitted forum post for spam:
 
 .. code-block:: python
 
@@ -52,14 +53,9 @@
    ):
        # This piece of content was classified as spam; handle it appropriately.
 
-Note that in both cases the client instance is created via the alternate constructor
-``validated_client()``. This is recommended instead of using the default constructor
-(i.e., directly calling ``akismet.SyncClient()`` or ``akismet.AsyncClient()``); the
-``validated_client()`` constructor will validate the configuration with the Akismet web
-service before returning the client.
-
-You can also use either client class as a context manager. This also will validate the
-configuration for you prior to returning the client:
+You can also use either client class as a context manager. This does *not* require the
+``validated_client()`` constructor, because your API key is validated on entering the
+``with`` block.
 
 .. code-block:: python
 

src/akismet/_common.py

@@ -87,8 +87,8 @@ class Config(typing.NamedTuple):
     of a key and a URL.
 
     You only need to use this if you're manually configuring an Akismet API client
-    (which should be rare) rather than letting the ``validated_client()`` constructor
-    automatically read the configuration from environment variables.
+    rather than letting the configuration be read automatically from environment
+    variables.
 
     """
 

src/akismet/_test_clients.py

@@ -207,6 +207,17 @@ class TestAsyncClient(AsyncClient):
     and instead always uses its own custom HTTP client to produce the desired fixed
     responses.
 
+    For operations other than comment-check and verify-key, the response values will be:
+
+    * submit-ham and submit-spam: :data:`True`
+
+    * key-sites: the sample responses (depending on requested format) given in `the
+      Akismet web service documentation for key-sites
+      <https://akismet.com/developers/detailed-docs/key-sites-activity/>`_.
+
+    * usage-limit: the sample response given in `the Akismet web service documentation
+      for usage-limit <https://akismet.com/developers/detailed-docs/usage-limit/>`_.
+
     """
 
     comment_check_response: "akismet.CheckResponse" = _common.CheckResponse.HAM
@@ -260,6 +271,17 @@ class TestSyncClient(SyncClient):
     and instead always uses its own custom HTTP client to produce the desired fixed
     responses.
 
+    For operations other than comment-check and verify-key, the response values will be:
+
+    * submit-ham and submit-spam: :data:`True`
+
+    * key-sites: the sample responses (depending on requested format) given in `the
+      Akismet web service documentation for key-sites
+      <https://akismet.com/developers/detailed-docs/key-sites-activity/>`_.
+
+    * usage-limit: the sample response given in `the Akismet web service documentation
+      for usage-limit <https://akismet.com/developers/detailed-docs/usage-limit/>`_.
+
     """
 
     comment_check_response: "akismet.CheckResponse" = _common.CheckResponse.HAM