[docs] Clarify the use cases of NotImplemented in the docs (issue 27242)

[barry at dadadata.net]

Reviewers: gvanrossum, stoneleaf, Jelle Zijlstra, SilentGhost,

Message:
A few typos and some nits. Mostly good otherwise.


http://bugs.python.org/review/27242/diff/18040/Doc/library/constants.rst
File Doc/library/constants.rst (right):

http://bugs.python.org/review/27242/diff/18040/Doc/library/constants.rst#newcode50
Doc/library/constants.rst:50: even though they have similar purposes. 
See :exc:`NotImplementedError`
Typo: Implented. Otherwise I'd use :exc:`NotImplementedError` on the
above line instead of ``NotImplementedError``

Also s/similar purposes/similar names/ here too.

http://bugs.python.org/review/27242/diff/18040/Doc/library/exceptions.rst
File Doc/library/exceptions.rst (right):

http://bugs.python.org/review/27242/diff/18040/Doc/library/exceptions.rst#newcode244
Doc/library/exceptions.rst:244: even though they have similar purposes. 
See :data:`NotImplemented` for
s/similar purposes/similar names/ IMO. I'd also use
:data:`NotImplemented` instead of ``NotImplemented`` on the above line.

Also, there's not really a need to reference NotImplementedError from
within its own block; but if you do it, please also do this in
NotImplemented.

Typo: "Implented" on the above line.



Please review this at http://bugs.python.org/review/27242/

Affected files:
  Doc/library/constants.rst
  Doc/library/exceptions.rst


diff --git a/Doc/library/constants.rst b/Doc/library/constants.rst
--- a/Doc/library/constants.rst
+++ b/Doc/library/constants.rst
@@ -26,30 +26,36 @@ A small number of constants live in the 
 
 .. data:: NotImplemented
 
    Special value which should be returned by the binary special methods
    (e.g. :meth:`__eq__`, :meth:`__lt__`, :meth:`__add__`, :meth:`__rsub__`,
    etc.) to indicate that the operation is not implemented with respect to
    the other type; may be returned by the in-place binary special methods
    (e.g. :meth:`__imul__`, :meth:`__iand__`, etc.) for the same purpose.
    Its truth value is true.
 
-.. note::
+   .. note::
 
-   When ``NotImplemented`` is returned, the interpreter will then try the
-   reflected operation on the other type, or some other fallback, depending
-   on the operator.  If all attempted operations return ``NotImplemented``, the
-   interpreter will raise an appropriate exception.
+      When a binary (or in-place) method returns ``NotImplemented`` the
+      interpreter will try the reflected operation on the other type (or some
+      other fallback, depending on the operator).  If all attempts return
+      ``NotImplemented``, the interpreter will raise an appropriate exception.
+      Incorrectly returning `NotImplemented` will result in a misleading
+      error message or the ``NotImplemented`` value being returned to Python code.
 
-   See
-   :ref:`implementing-the-arithmetic-operations`
-   for more details.
+      See :ref:`implementing-the-arithmetic-operations` for examples.
+
+   .. note::
+
+      ``NotImplentedError`` and ``NotImplemented`` are not interchangeable,
+      even though they have similar purposes.  See :exc:`NotImplementedError`
+      for details on when to use it.
 
 
 .. data:: Ellipsis
 
    The same as ``...``.  Special value used mostly in conjunction with extended
    slicing syntax for user-defined container data types.
 
 
 .. data:: __debug__
 
diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
--- a/Doc/library/exceptions.rst
+++ b/Doc/library/exceptions.rst
@@ -221,23 +221,35 @@ The following exceptions are the excepti
 .. exception:: NameError
 
    Raised when a local or global name is not found.  This applies only to
    unqualified names.  The associated value is an error message that includes the
    name that could not be found.
 
 
 .. exception:: NotImplementedError
 
    This exception is derived from :exc:`RuntimeError`.  In user defined base
-   classes, abstract methods should raise this exception when they require derived
-   classes to override the method.
+   classes, abstract methods should raise this exception when they require
+   derived classes to override the method, or while the class is being
+   developed to indicate that the real implementation still needs to be added.
 
+   .. note::
+
+      It should not be used to indicate that an operater or method is not
+      meant to be supported at all -- in that case either leave the operator /
+      method undefined or, if a subclass, set it to :data:`None`.
+
+   .. note::
+
+      :exc:`NotImplentedError` and ``NotImplemented`` are not interchangeable,
+      even though they have similar purposes.  See :data:`NotImplemented` for
+      details on when to use it.
 
 .. exception:: OSError([arg])
                OSError(errno, strerror[, filename[, winerror[, filename2]]])
 
    .. index:: module: errno
 
    This exception is raised when a system function returns a system-related
    error, including I/O failures such as "file not found" or "disk full"
    (not for illegal argument types or other incidental errors).
 
@@ -429,20 +441,29 @@ The following exceptions are the excepti
 
       The exit status or error message that is passed to the constructor.
       (Defaults to ``None``.)
 
 
 .. exception:: TypeError
 
    Raised when an operation or function is applied to an object of inappropriate
    type.  The associated value is a string giving details about the type mismatch.
 
+   This exception may be raised by user code to indicate that an attempted
+   operation on an object is not supported, and is not meant to. If an object
+   is meant to support a given operation but has not yet provided an
+   implementation, :exc:`NotImplementedError` is the proper exception to raise.
+
+   Passing arguments of the wrong type (e.g. passing a :class:`list` when an
+   :class:`int` is expected) should result in a :exc:`TypeError`, but passing
+   arguments with the wrong value (e.g. a number outside expected boundaries)
+   should be a :exc:`ValueError`.
 
 .. exception:: UnboundLocalError
 
    Raised when a reference is made to a local variable in a function or method, but
    no value has been bound to that variable.  This is a subclass of
    :exc:`NameError`.
 
 
 .. exception:: UnicodeError