#7035: improve docs of the various <method>_errors() functions, and give them docstrings.

2 files changed, 42 insertions, 20 deletions

diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst
index 072b19c..e842bf8 100644
--- a/Doc/library/codecs.rst
+++ b/Doc/library/codecs.rst
@@ -54,7 +54,7 @@ It defines the following functions:
    *incrementalencoder* and *incrementaldecoder*: These have to be factory
    functions providing the following interface:
 
-   ``factory(errors='strict')``
+      ``factory(errors='strict')``
 
    The factory functions must return objects providing the interfaces defined by
    the base classes :class:`IncrementalEncoder` and :class:`IncrementalDecoder`,
@@ -63,20 +63,24 @@ It defines the following functions:
    *streamreader* and *streamwriter*: These have to be factory functions providing
    the following interface:
 
-   ``factory(stream, errors='strict')``
+      ``factory(stream, errors='strict')``
 
    The factory functions must return objects providing the interfaces defined by
    the base classes :class:`StreamWriter` and :class:`StreamReader`, respectively.
    Stream codecs can maintain state.
 
-   Possible values for errors are ``'strict'`` (raise an exception in case of an
-   encoding error), ``'replace'`` (replace malformed data with a suitable
-   replacement marker, such as ``'?'``), ``'ignore'`` (ignore malformed data and
-   continue without further notice), ``'xmlcharrefreplace'`` (replace with the
-   appropriate XML character reference (for encoding only)) and
-   ``'backslashreplace'`` (replace with backslashed escape sequences (for encoding
-   only)) as well as any other error handling name defined via
-   :func:`register_error`.
+   Possible values for errors are
+
+   * ``'strict'``: raise an exception in case of an encoding error
+   * ``'replace'``: replace malformed data with a suitable replacement marker,
+     such as ``'?'`` or ``'\ufffd'``
+   * ``'ignore'``: ignore malformed data and continue without further notice
+   * ``'xmlcharrefreplace'``: replace with the appropriate XML character
+     reference (for encoding only)
+   * ``'backslashreplace'``: replace with backslashed escape sequences (for
+     encoding only
+
+   as well as any other error handling name defined via :func:`register_error`.
 
    In case a search function cannot find a given encoding, it should return
    ``None``.
@@ -177,27 +181,33 @@ functions which use :func:`lookup` for the codec lookup:
 
 .. function:: strict_errors(exception)
 
-   Implements the ``strict`` error handling.
+   Implements the ``strict`` error handling: each encoding or decoding error
+   raises a :exc:`UnicodeError`.
 
 
 .. function:: replace_errors(exception)
 
-   Implements the ``replace`` error handling.
+   Implements the ``replace`` error handling: malformed data is replaced with a
+   suitable replacement character such as ``'?'`` in bytestrings and
+   ``'\ufffd'`` in Unicode strings.
 
 
 .. function:: ignore_errors(exception)
 
-   Implements the ``ignore`` error handling.
+   Implements the ``ignore`` error handling: malformed data is ignored and
+   encoding or decoding is continued without further notice.
 
 
 .. function:: xmlcharrefreplace_errors(exception)
 
-   Implements the ``xmlcharrefreplace`` error handling.
+   Implements the ``xmlcharrefreplace`` error handling (for encoding only): the
+   unencodable character is replaced by an appropriate XML character reference.
 
 
 .. function:: backslashreplace_errors(exception)
 
-   Implements the ``backslashreplace`` error handling.
+   Implements the ``backslashreplace`` error handling (for encoding only): the
+   unencodable character is replaced by a backslashed escape sequence.
 
 To simplify working with encoded files or stream, the module also defines these
 utility functions:
diff --git a/Python/codecs.c b/Python/codecs.c
index 4b0f4cb..3849cf9 100644
--- a/Python/codecs.c
+++ b/Python/codecs.c
@@ -774,7 +774,9 @@ static int _PyCodecRegistry_Init(void)
 	    {
 		"strict_errors",
 		strict_errors,
-		METH_O
+		METH_O,
+		PyDoc_STR("Implements the 'strict' error handling, which "
+			  "raises a UnicodeError on coding errors.")
 	    }
 	},
 #ifdef Py_USING_UNICODE
@@ -783,7 +785,9 @@ static int _PyCodecRegistry_Init(void)
 	    {
 		"ignore_errors",
 		ignore_errors,
-		METH_O
+		METH_O,
+		PyDoc_STR("Implements the 'ignore' error handling, which "
+			  "ignores malformed data and continues.")
 	    }
 	},
 	{
@@ -791,7 +795,9 @@ static int _PyCodecRegistry_Init(void)
 	    {
 		"replace_errors",
 		replace_errors,
-		METH_O
+		METH_O,
+		PyDoc_STR("Implements the 'replace' error handling, which "
+			  "replaces malformed data with a replacement marker.")
 	    }
 	},
 	{
@@ -799,7 +805,10 @@ static int _PyCodecRegistry_Init(void)
 	    {
 		"xmlcharrefreplace_errors",
 		xmlcharrefreplace_errors,
-		METH_O
+		METH_O,
+		PyDoc_STR("Implements the 'xmlcharrefreplace' error handling, "
+			  "which replaces an unencodable character with the "
+			  "appropriate XML character reference.")
 	    }
 	},
 	{
@@ -807,7 +816,10 @@ static int _PyCodecRegistry_Init(void)
 	    {
 		"backslashreplace_errors",
 		backslashreplace_errors,
-		METH_O
+		METH_O,
+		PyDoc_STR("Implements the 'backslashreplace' error handling, "
+			  "which replaces an unencodable character with a "
+			  "backslashed escape sequence.")
 	    }
 	}
 #endif