From b6fe08a6343ed72e7d32f50e1f3165e2d4b6a4ce Mon Sep 17 00:00:00 2001
From: Tim Heap <tim@timheap.me>
Date: Thu, 13 Oct 2016 11:55:21 +0200
Subject: [PATCH] Docs for get_image_model/get_image_model_string

---
 docs/advanced_topics/images/custom_image_model.rst | 12 +++++++++++-
 wagtail/wagtailimages/__init__.py                  | 13 +++++++++++--
 2 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/docs/advanced_topics/images/custom_image_model.rst b/docs/advanced_topics/images/custom_image_model.rst
index df733dd415..c6a22216be 100644
--- a/docs/advanced_topics/images/custom_image_model.rst
+++ b/docs/advanced_topics/images/custom_image_model.rst
@@ -1,5 +1,6 @@
 .. _custom_image_model:
 
+===================
 Custom image models
 ===================
 
@@ -23,7 +24,7 @@ Here's an example:
     from django.db import models
     from django.db.models.signals import post_delete
     from django.dispatch import receiver
-    
+
     from wagtail.wagtailimages.models import Image, AbstractImage, AbstractRendition
 
 
@@ -87,3 +88,12 @@ Then set the ``WAGTAILIMAGES_IMAGE_MODEL`` setting to point to it:
 
     Any templates that reference the builtin image model will still continue to
     work as before but would need to be updated in order to see any new images.
+
+Referring to the image model
+============================
+
+.. module:: wagtail.wagtailimages
+
+.. autofunction:: get_image_model
+
+.. autofunction:: get_image_model_string
diff --git a/wagtail/wagtailimages/__init__.py b/wagtail/wagtailimages/__init__.py
index 01092a0603..f9e64823a0 100644
--- a/wagtail/wagtailimages/__init__.py
+++ b/wagtail/wagtailimages/__init__.py
@@ -8,12 +8,21 @@ default_app_config = 'wagtail.wagtailimages.apps.WagtailImagesAppConfig'
 
 
 def get_image_model_string():
-    """Get the dotted app.Model name for the image model"""
+    """
+    Get the dotted ``app.Model`` name for the image model as a string.
+    Useful for developers making Wagtail plugins that need to refer to the
+    image model, such as in foreign keys, but the model itself is not required.
+    """
     return getattr(settings, 'WAGTAILIMAGES_IMAGE_MODEL', 'wagtailimages.Image')
 
 
 def get_image_model():
-    """Get the image model from WAGTAILIMAGES_IMAGE_MODEL."""
+    """
+    Get the image model from the ``WAGTAILIMAGES_IMAGE_MODEL`` setting.
+    Useful for developers making Wagtail plugins that need the image model.
+    Defaults to the standard :class:`~wagtail.wagtailimages.models.Image` model
+    if no custom model is defined.
+    """
     from django.apps import apps
     model_string = get_image_model_string()
     try: