Doc'd Model.MultipleObjectsReturned docs and improved documentation related with models exceptions.

3 files changed, 48 insertions, 24 deletions

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 4e3cd108b9..fd7e88d168 100644
--- a/docs/ref/models/fields.txt
+++ b/docs/ref/models/fields.txt
@@ -1999,14 +1999,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 bef6938263..1c82f378b9 100644
--- a/docs/ref/models/querysets.txt
+++ b/docs/ref/models/querysets.txt
@@ -1844,34 +1844,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()``
 ~~~~~~~~~~~~