Fixed #8730: Incorporated (with minor changes) additions/enhancements to one-to-one docs

git-svn-id: http://code.djangoproject.com/svn/django/trunk@8787 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/ref/models/fields.txt

@@ -883,6 +883,8 @@ that control how the relationship functions.
     is not provided, Django will assume a default name based upon the names of
     the two tables being joined.
 
+.. _ref-onetoone:
+
 ``OneToOneField``
 -----------------
 
@@ -897,13 +899,17 @@ another model in some way; :ref:`multi-table-inheritance` is
 implemented by adding an implicit one-to-one relation from the child
 model to the parent model, for example.
 
-One positional argument is required: the class to which the model will
-be related.
+One positional argument is required: the class to which the model will be
+related. This works exactly the same as it does for :class:`ForeignKey`,
+including all the options regarding :ref:`recursive <recursive-relationships>`
+and :ref:`lazy <lazy-relationships>` relationships.
+
+.. _onetoone-arguments:
 
 Additionally, ``OneToOneField`` accepts all of the extra arguments
 accepted by :class:`ForeignKey`, plus one extra argument:
 
-.. attribute: OneToOneField.parent_link
+.. attribute:: OneToOneField.parent_link
 
     When ``True`` and used in a model which inherits from another
     (concrete) model, indicates that this field should be used as the

docs/topics/db/models.txt

@@ -499,40 +499,55 @@ of the intermediate model::
     
 
 One-to-one relationships
-------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-One-to-one relationships are very similar to many-to-one relationships. If you
-define a :class:`~django.db.models.OneToOneField` on your model, instances of
-that model will have access to the related object via a simple attribute of the
-model.
+To define a one-to-one relationship, use
+:class:`~django.db.models.OneToOneField`. You use it just like any other
+``Field`` type: by including it as a class attribute of your model.
 
-For example::
+This is most useful on the primary key of an object when that object "extends"
+another object in some way.
 
-    class EntryDetail(models.Model):
-        entry = models.OneToOneField(Entry)
-        details = models.TextField()
+:class:`~django.db.models.OneToOneField` requires a positional argument: the
+class to which the model is related.
 
-    ed = EntryDetail.objects.get(id=2)
-    ed.entry # Returns the related Entry object.
+For example, if you were building a database of "places", you would
+build pretty standard stuff such as address, phone number, etc. in the
+database. Then, if you wanted to build a database of restaurants on
+top of the places, instead of repeating yourself and replicating those
+fields in the ``Restaurant`` model, you could make ``Restaurant`` have
+a :class:`~django.db.models.OneToOneField` to ``Place`` (because a
+restaurant "is a" place; in fact, to handle this you'd typically use
+:ref:`inheritance <model-inheritance>`, which involves an implicit
+one-to-one relation).
+
+As with :class:`~django.db.models.ForeignKey`, a
+:ref:`recursive relationship <recursive-relationships>`
+can be defined and
+:ref:`references to as-yet undefined models <lazy-relationships>`
+can be made; see
+:class:`the model field reference <django.db.models.fields.OneToOneField>`
+for details.
 
-The difference comes in "reverse" queries. The related model in a one-to-one
-relationship also has access to a :class:`~django.db.models.Manager` object, but
-that :class:`~django.db.models.Manager` represents a single object, rather than
-a collection of objects::
+.. seealso::
 
-    e = Entry.objects.get(id=2)
-    e.entrydetail # returns the related EntryDetail object
+    See the `One-to-one relationship model example`_ for a full example.
 
-If no object has been assigned to this relationship, Django will raise
-a ``DoesNotExist`` exception.
+.. _One-to-one relationship model example: http://www.djangoproject.com/documentation/models/one_to_one/
 
-Instances can be assigned to the reverse relationship in the same way as
-you would assign the forward relationship::
+**New in Django development version**
+
+:class:`~django.db.models.OneToOneField` fields also accept one optional argument
+described in the :ref:`model field reference <ref-onetoone>`.
 
-    e.entrydetail = ed
+:class:`~django.db.models.OneToOneField` classes used to automatically become
+the primary key on a model. This is no longer true (although you can manually
+pass in the :attr:`~django.db.models.Field.primary_key` argument if you like).
+Thus, it's now possible to have multiple fields of type
+:class:`~django.db.models.OneToOneField` on a single model.
 
 Models across files
-~~~~~~~~~~~~~~~~~~~
+-------------------
 
 It's perfectly OK to relate a model to one from another app. To do this, just
 import the related model at the top of the model that holds your model. Then,

docs/topics/db/queries.txt

@@ -916,8 +916,35 @@ above example, if the ``ManyToManyField`` in ``Entry`` had specified
 One-to-one relationships
 ------------------------
 
-The semantics of one-to-one relationships will be changing soon, so we don't
-recommend you use them.
+One-to-one relationships are very similar to many-to-one relationships. If you
+define a :class:`~django.db.models.OneToOneField` on your model, instances of
+that model will have access to the related object via a simple attribute of the
+model.
+
+For example::
+
+    class EntryDetail(models.Model):
+        entry = models.OneToOneField(Entry)
+        details = models.TextField()
+
+    ed = EntryDetail.objects.get(id=2)
+    ed.entry # Returns the related Entry object.
+
+The difference comes in "reverse" queries. The related model in a one-to-one
+relationship also has access to a :class:`~django.db.models.Manager` object, but
+that :class:`~django.db.models.Manager` represents a single object, rather than
+a collection of objects::
+
+    e = Entry.objects.get(id=2)
+    e.entrydetail # returns the related EntryDetail object
+
+If no object has been assigned to this relationship, Django will raise
+a ``DoesNotExist`` exception.
+
+Instances can be assigned to the reverse relationship in the same way as
+you would assign the forward relationship::
+
+    e.entrydetail = ed
 
 How are the backward relationships possible?
 --------------------------------------------