From f0d4e76418ff3f02b3401ee41467356a939c39a0 Mon Sep 17 00:00:00 2001
From: Ross Lawley <ross.lawley@gmail.com>
Date: Fri, 7 Jun 2013 08:21:15 +0000
Subject: [PATCH] Documentation updates

---
 docs/apireference.rst      |  5 +++++
 mongoengine/base/fields.py |  3 +--
 mongoengine/common.py      | 14 +++++++++++++-
 3 files changed, 19 insertions(+), 3 deletions(-)

diff --git a/docs/apireference.rst b/docs/apireference.rst
index 0fa410e1..d0627278 100644
--- a/docs/apireference.rst
+++ b/docs/apireference.rst
@@ -88,3 +88,8 @@ Fields
 .. autoclass:: mongoengine.fields.GridFSProxy
 .. autoclass:: mongoengine.fields.ImageGridFsProxy
 .. autoclass:: mongoengine.fields.ImproperlyConfigured
+
+Misc
+====
+
+.. autofunction:: mongoengine.common._import_class
diff --git a/mongoengine/base/fields.py b/mongoengine/base/fields.py
index e4c88a79..eda9b3c9 100644
--- a/mongoengine/base/fields.py
+++ b/mongoengine/base/fields.py
@@ -82,8 +82,7 @@ class BaseField(object):
             BaseField.creation_counter += 1
 
     def __get__(self, instance, owner):
-        """Descriptor for retrieving a value from a field in a document. Do
-        any necessary conversion between Python and MongoDB types.
+        """Descriptor for retrieving a value from a field in a document.
         """
         if instance is None:
             # Document class being used rather than a document object
diff --git a/mongoengine/common.py b/mongoengine/common.py
index bff55ac5..20d51387 100644
--- a/mongoengine/common.py
+++ b/mongoengine/common.py
@@ -2,7 +2,19 @@ _class_registry_cache = {}
 
 
 def _import_class(cls_name):
-    """Cached mechanism for imports"""
+    """Cache mechanism for imports.
+
+    Due to complications of circular imports mongoengine needs to do lots of
+    inline imports in functions.  This is inefficient as classes are
+    imported repeated throughout the mongoengine code.  This is
+    compounded by some recursive functions requiring inline imports.
+
+    :mod:`mongoengine.common` provides a single point to import all these
+    classes.  Circular imports aren't an issue as it dynamically imports the
+    class when first needed.  Subsequent calls to the
+    :func:`~mongoengine.common._import_class` can then directly retrieve the
+    class from the :data:`mongoengine.common._class_registry_cache`.
+    """
     if cls_name in _class_registry_cache:
         return _class_registry_cache.get(cls_name)