From 53c0cdc0c11d706f4220bfad70646134ed6c1e0d Mon Sep 17 00:00:00 2001
From: Harry Marr <harry.marr@gmail.com>
Date: Sun, 28 Feb 2010 23:29:42 +0000
Subject: [PATCH] Added recursive and undefined document ref docs

---
 docs/apireference.rst             |  6 ++++++
 docs/guide/defining-documents.rst | 20 ++++++++++++++++++++
 mongoengine/fields.py             |  8 +++++++-
 3 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/docs/apireference.rst b/docs/apireference.rst
index 1a243d2e..ec78efa0 100644
--- a/docs/apireference.rst
+++ b/docs/apireference.rst
@@ -36,10 +36,14 @@ Fields
 
 .. autoclass:: mongoengine.StringField
 
+.. autoclass:: mongoengine.URLField
+
 .. autoclass:: mongoengine.IntField
 
 .. autoclass:: mongoengine.FloatField
 
+.. autoclass:: mongoengine.DecimalField
+
 .. autoclass:: mongoengine.BooleanField
 
 .. autoclass:: mongoengine.DateTimeField
@@ -53,3 +57,5 @@ Fields
 .. autoclass:: mongoengine.ObjectIdField
 
 .. autoclass:: mongoengine.ReferenceField
+
+.. autoclass:: mongoengine.GenericReferenceField
diff --git a/docs/guide/defining-documents.rst b/docs/guide/defining-documents.rst
index bb0d6c81..b5655c7d 100644
--- a/docs/guide/defining-documents.rst
+++ b/docs/guide/defining-documents.rst
@@ -120,6 +120,20 @@ field::
 The :class:`User` object is automatically turned into a reference behind the
 scenes, and dereferenced when the :class:`Page` object is retrieved.
 
+To add a :class:`~mongoengine.ReferenceField` that references the document
+being defined, use the string ``'self'`` in place of the document class as the
+argument to :class:`~mongoengine.ReferenceField`'s constructor. To reference a
+document that has not yet been defined, use the name of the undefined document
+as the constructor's argument::
+
+    class Employee(Document):
+        name = StringField()
+        boss = ReferenceField('self')
+        profile_page = ReferenceField('ProfilePage')
+
+    class ProfilePage(Document):
+        content = StringField()
+
 Generic reference fields
 ''''''''''''''''''''''''
 A second kind of reference field also exists,
@@ -145,6 +159,12 @@ kind of :class:`~mongoengine.Document`, and hence doesn't take a
     Bookmark(bookmark_object=link).save()
     Bookmark(bookmark_object=post).save()
 
+.. note::
+   Using :class:`~mongoengine.GenericReferenceField`\ s is slightly less
+   efficient than the standard :class:`~mongoengine.ReferenceField`\ s, so if
+   you will only be referencing one document type, prefer the standard 
+   :class:`~mongoengine.ReferenceField`.
+
 Uniqueness constraints
 ----------------------
 MongoEngine allows you to specify that a field should be unique across a
diff --git a/mongoengine/fields.py b/mongoengine/fields.py
index 8456be2f..0793f44b 100644
--- a/mongoengine/fields.py
+++ b/mongoengine/fields.py
@@ -62,6 +62,8 @@ class StringField(BaseField):
 
 class URLField(StringField):
     """A field that validates input as a URL.
+
+    .. versionadded:: 0.3
     """
 
     URL_REGEX = re.compile(
@@ -140,6 +142,8 @@ class FloatField(BaseField):
 
 class DecimalField(BaseField):
     """A fixed-point decimal number field.
+
+    .. versionadded:: 0.3
     """
 
     def __init__(self, min_value=None, max_value=None, **kwargs):
@@ -308,7 +312,7 @@ class DictField(BaseField):
     """A dictionary field that wraps a standard Python dictionary. This is
     similar to an embedded document, but the structure is not defined.
 
-    .. versionadded:: 0.2.3
+    .. versionadded:: 0.3
     """
 
     def validate(self, value):
@@ -396,6 +400,8 @@ class ReferenceField(BaseField):
 class GenericReferenceField(BaseField):
     """A reference to *any* :class:`~mongoengine.document.Document` subclass
     that will be automatically dereferenced on access (lazily).
+
+    .. versionadded:: 0.3
     """
 
     def __get__(self, instance, owner):