From 49bff5d544c30ba0a8433b07cda8f7d4e50c9d73 Mon Sep 17 00:00:00 2001
From: Benjamin Chrobot <benjamin.chrobot@alum.mit.edu>
Date: Thu, 12 Apr 2018 10:47:52 -0400
Subject: [PATCH] Add documentation for LazyReference and GenericLazyReference
 fields.

---
 docs/apireference.rst             |  2 ++
 docs/guide/defining-documents.rst |  2 ++
 mongoengine/fields.py             | 17 +++++++++++------
 3 files changed, 15 insertions(+), 6 deletions(-)

diff --git a/docs/apireference.rst b/docs/apireference.rst
index 625d4a8b..05ba3f73 100644
--- a/docs/apireference.rst
+++ b/docs/apireference.rst
@@ -87,7 +87,9 @@ Fields
 .. autoclass:: mongoengine.fields.DictField
 .. autoclass:: mongoengine.fields.MapField
 .. autoclass:: mongoengine.fields.ReferenceField
+.. autoclass:: mongoengine.fields.LazyReferenceField
 .. autoclass:: mongoengine.fields.GenericReferenceField
+.. autoclass:: mongoengine.fields.GenericLazyReferenceField
 .. autoclass:: mongoengine.fields.CachedReferenceField
 .. autoclass:: mongoengine.fields.BinaryField
 .. autoclass:: mongoengine.fields.FileField
diff --git a/docs/guide/defining-documents.rst b/docs/guide/defining-documents.rst
index 33b5292f..3ced284e 100644
--- a/docs/guide/defining-documents.rst
+++ b/docs/guide/defining-documents.rst
@@ -80,6 +80,7 @@ are as follows:
 * :class:`~mongoengine.fields.FloatField`
 * :class:`~mongoengine.fields.GenericEmbeddedDocumentField`
 * :class:`~mongoengine.fields.GenericReferenceField`
+* :class:`~mongoengine.fields.GenericLazyReferenceField`
 * :class:`~mongoengine.fields.GeoPointField`
 * :class:`~mongoengine.fields.ImageField`
 * :class:`~mongoengine.fields.IntField`
@@ -87,6 +88,7 @@ are as follows:
 * :class:`~mongoengine.fields.MapField`
 * :class:`~mongoengine.fields.ObjectIdField`
 * :class:`~mongoengine.fields.ReferenceField`
+* :class:`~mongoengine.fields.LazyReferenceField`
 * :class:`~mongoengine.fields.SequenceField`
 * :class:`~mongoengine.fields.SortedListField`
 * :class:`~mongoengine.fields.StringField`
diff --git a/mongoengine/fields.py b/mongoengine/fields.py
index f169f0f1..a661874a 100644
--- a/mongoengine/fields.py
+++ b/mongoengine/fields.py
@@ -2204,8 +2204,11 @@ class MultiPolygonField(GeoJsonBaseField):
 
 class LazyReferenceField(BaseField):
     """A really lazy reference to a document.
-    Unlike the :class:`~mongoengine.fields.ReferenceField` it must be manually
-    dereferenced using it ``fetch()`` method.
+    Unlike the :class:`~mongoengine.fields.ReferenceField` it will
+    **not** be automatically (lazily) dereferenced on access.
+    Instead, access will return a :class:`~mongoengine.base.LazyReference` class
+    instance, allowing access to `pk` or manual dereference by using
+    ``fetch()`` method.
 
     .. versionadded:: 0.15
     """
@@ -2331,10 +2334,12 @@ class LazyReferenceField(BaseField):
 
 
 class GenericLazyReferenceField(GenericReferenceField):
-    """A reference to *any* :class:`~mongoengine.document.Document` subclass
-    that will be automatically dereferenced on access (lazily).
-    Unlike the :class:`~mongoengine.fields.GenericReferenceField` it must be
-    manually dereferenced using it ``fetch()`` method.
+    """A reference to *any* :class:`~mongoengine.document.Document` subclass.
+    Unlike the :class:`~mongoengine.fields.GenericReferenceField` it will
+    **not** be automatically (lazily) dereferenced on access.
+    Instead, access will return a :class:`~mongoengine.base.LazyReference` class
+    instance, allowing access to `pk` or manual dereference by using
+    ``fetch()`` method.
 
     .. note ::
         * Any documents used as a generic reference must be registered in the