Doc: LDAPBytesWarning doc improvements

encukou · encukou · commit 829027081d8c · 2017-12-07T14:40:51.000+01:00
- Make filtering note apply to both causes of the warning
- Add formal class documentation
- Add cross-references
diff --git a/Doc/bytes_mode.rst b/Doc/bytes_mode.rst
@@ -66,9 +66,11 @@ Unspecified: relaxed mode with warnings
 
     Text values returned from python-ldap are always ``unicode``.
     Text values supplied to python-ldap should be ``unicode``;
-    warnings of type :class:`ldap.LDAPBytesWarning` are emitted when they
-    are not. :class:`ldap.LDAPBytesWarning` is a subclass of
-    :class:`BytesWarning`.
+    warnings are emitted when they are not.
+
+    The warnings are of type :class:`~ldap.LDAPBytesWarning`, which
+    is a subclass of :class:`BytesWarning` designed to be easily
+    :ref:`filtered out <filter-bytes-warning>` if needed.
 
 Backwards-compatible behavior is not scheduled for removal until Python 2
 itself reaches end of life.
@@ -107,8 +109,10 @@ Note that only the result's *values* are of the ``bytes`` type:
     ]
 
 
-Filter warning
---------------
+.. _filter-bytes-warning:
+
+Filtering warnings
+------------------
 
 The bytes mode warnings can be filtered out and ignored with a
 simple filter.
diff --git a/Doc/reference/ldap.rst b/Doc/reference/ldap.rst
@@ -564,6 +564,18 @@ The above exceptions are raised when a result code from an underlying API
 call does not indicate success.
 
 
+Warnings
+========
+
+.. py:class:: LDAPBytesWarning
+
+    Raised when bytes/text mismatch in non-strict bytes mode.
+
+    See :ref:`bytes_mode` for details.
+
+    .. versionadded:: 3.0.0
+
+
 .. _ldap-objects:
 
 LDAPObject classes
