[3.0.x] Doc'd Model.MultipleObjectsReturned docs and improved documentation related with models exceptions.

Backport of bc4fea92b296a7eacbd5f89263ca67515feeb53f from master

4 files changed, 58 insertions, 34 deletions

diff --git a/docs/ref/exceptions.txt b/docs/ref/exceptions.txt
index 83869d6b42..8f276a993c 100644
--- a/docs/ref/exceptions.txt
+++ b/docs/ref/exceptions.txt
@@ -26,12 +26,12 @@ Django core exception classes are defined in ``django.core.exceptions``.
 
 .. exception:: ObjectDoesNotExist
 
-    The base class for :exc:`~django.db.models.Model.DoesNotExist` exceptions;
-    a ``try/except`` for ``ObjectDoesNotExist`` will catch
+    The base class for :exc:`Model.DoesNotExist
+    <django.db.models.Model.DoesNotExist>` exceptions. A ``try/except`` for
+    ``ObjectDoesNotExist`` will catch
     :exc:`~django.db.models.Model.DoesNotExist` exceptions for all models.
 
-    See :meth:`~django.db.models.query.QuerySet.get()` for further information
-    on :exc:`ObjectDoesNotExist` and :exc:`~django.db.models.Model.DoesNotExist`.
+    See :meth:`~django.db.models.query.QuerySet.get()`.
 
 ``EmptyResultSet``
 ------------------
@@ -56,13 +56,13 @@ Django core exception classes are defined in ``django.core.exceptions``.
 
 .. exception:: MultipleObjectsReturned
 
-    The :exc:`MultipleObjectsReturned` exception is raised by a query if only
-    one object is expected, but multiple objects are returned. A base version
-    of this exception is provided in :mod:`django.core.exceptions`; each model
-    class contains a subclassed version that can be used to identify the
-    specific object type that has returned multiple objects.
+    The base class for :exc:`Model.MultipleObjectsReturned
+    <django.db.models.Model.MultipleObjectsReturned>` exceptions. A
+    ``try/except`` for ``MultipleObjectsReturned`` will catch
+    :exc:`~django.db.models.Model.MultipleObjectsReturned` exceptions for all
+    models.
 
-    See :meth:`~django.db.models.query.QuerySet.get()` for further information.
+    See :meth:`~django.db.models.query.QuerySet.get()`.
 
 ``SuspiciousOperation``
 -----------------------
diff --git a/docs/ref/models/class.txt b/docs/ref/models/class.txt
index c41052788e..81414973a9 100644
--- a/docs/ref/models/class.txt
+++ b/docs/ref/models/class.txt
@@ -25,6 +25,20 @@ Attributes
     to catch exceptions for a particular model class. The exception is a
     subclass of :exc:`django.core.exceptions.ObjectDoesNotExist`.
 
+``MultipleObjectsReturned``
+---------------------------
+
+.. exception:: Model.MultipleObjectsReturned
+
+    This exception is raised by :meth:`.QuerySet.get` when multiple objects are
+    found for the given lookups.
+
+    Django provides a ``MultipleObjectsReturned`` exception as an attribute of
+    each model class to identify the class of object for which multiple objects
+    were found, allowing you to catch exceptions for a particular model class.
+    The exception is a subclass of
+    :exc:`django.core.exceptions.MultipleObjectsReturned`.
+
 ``objects``
 -----------
 
diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt
index 4acf47c188..03b713704b 100644
--- a/docs/ref/models/fields.txt
+++ b/docs/ref/models/fields.txt
@@ -1894,14 +1894,16 @@ your resulting ``User`` model will have the following attributes::
     >>> hasattr(user, 'supervisor_of')
     True
 
-A ``DoesNotExist`` exception is raised when accessing the reverse relationship
-if an entry in the related table doesn't exist. For example, if a user doesn't
-have a supervisor designated by ``MySpecialUser``::
+A ``RelatedObjectDoesNotExist`` exception is raised when accessing the reverse
+relationship if an entry in the related table doesn't exist. This is a subclass
+of the target model's :exc:`Model.DoesNotExist
+<django.db.models.Model.DoesNotExist>` exception. For example, if a user
+doesn't have a supervisor designated by ``MySpecialUser``::
 
     >>> user.supervisor_of
     Traceback (most recent call last):
         ...
-    DoesNotExist: User matching query does not exist.
+    RelatedObjectDoesNotExist: User has no supervisor_of.
 
 .. _onetoone-arguments:
 
diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt
index 4d41d0c390..6f0b74ec92 100644
--- a/docs/ref/models/querysets.txt
+++ b/docs/ref/models/querysets.txt
@@ -1823,34 +1823,42 @@ they query the database each time they're called.
 .. method:: get(**kwargs)
 
 Returns the object matching the given lookup parameters, which should be in
-the format described in `Field lookups`_.
+the format described in `Field lookups`_. You should use lookups that are
+guaranteed unique, such as the primary key or fields in a unique constraint.
+For example::
+
+    Entry.objects.get(id=1)
+    Entry.objects.get(blog=blog, entry_number=1)
+
+If you expect a queryset to already return one row, you can use ``get()``
+without any arguments to return the object for that row::
+
+    Entry.objects.filter(pk=1).get()
 
-``get()`` raises :exc:`~django.core.exceptions.MultipleObjectsReturned` if more
-than one object was found. The
-:exc:`~django.core.exceptions.MultipleObjectsReturned` exception is an
-attribute of the model class.
+If ``get()`` doesn't find any object, it raises a :exc:`Model.DoesNotExist
+<django.db.models.Model.DoesNotExist>` exception::
 
-``get()`` raises a :exc:`~django.db.models.Model.DoesNotExist` exception if an
-object wasn't found for the given parameters. This exception is an attribute
-of the model class. Example::
+    Entry.objects.get(id=-999) # raises Entry.DoesNotExist
 
-    Entry.objects.get(id='foo') # raises Entry.DoesNotExist
+If ``get()`` finds more than one object, it raises a
+:exc:`Model.MultipleObjectsReturned
+<django.db.models.Model.MultipleObjectsReturned>` exception::
 
-The :exc:`~django.db.models.Model.DoesNotExist` exception inherits from
-:exc:`django.core.exceptions.ObjectDoesNotExist`, so you can target multiple
-:exc:`~django.db.models.Model.DoesNotExist` exceptions. Example::
+    Entry.objects.get(name='A Duplicated Name') # raises Entry.MultipleObjectsReturned
+
+Both these exception classes are attributes of the model class, and specific to
+that model. If you want to handle such exceptions from several ``get()`` calls
+for different models, you can use their generic base classes. For example, you
+can use :exc:`django.core.exceptions.ObjectDoesNotExist`  to handle
+:exc:`~django.db.models.Model.DoesNotExist` exceptions from multiple models::
 
     from django.core.exceptions import ObjectDoesNotExist
+
     try:
-        e = Entry.objects.get(id=3)
-        b = Blog.objects.get(id=1)
+        blog = Blog.objects.get(id=1)
+        entry = Entry.objects.get(blog=blog, entry_number=1)
     except ObjectDoesNotExist:
-        print("Either the entry or blog doesn't exist.")
-
-If you expect a queryset to return one row, you can use ``get()`` without any
-arguments to return the object for that row::
-
-    entry = Entry.objects.filter(...).exclude(...).get()
+        print("Either the blog or entry doesn't exist.")
 
 ``create()``
 ~~~~~~~~~~~~