Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Apply doc addition that somehow was left out of r11833. Refs #7977.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@11841 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit d10dd3eceb45b72746c974adaf7d9040aa48dd0a 1 parent 20938b6
Karen Tracey authored December 13, 2009

Showing 1 changed file with 21 additions and 0 deletions. Show diff stats Hide diff stats

  1. 21  docs/howto/custom-model-fields.txt
21  docs/howto/custom-model-fields.txt
@@ -39,6 +39,8 @@ are traditionally called *north*, *east*, *south* and *west*.  Our class looks
39 39
 something like this::
40 40
 
41 41
     class Hand(object):
  42
+        """A hand of cards (bridge style)"""
  43
+
42 44
         def __init__(self, north, east, south, west):
43 45
             # Input parameters are lists of cards ('Ah', '9s', etc)
44 46
             self.north = north
@@ -163,6 +165,8 @@ behave like any existing field, so we'll subclass directly from
163 165
     from django.db import models
164 166
 
165 167
     class HandField(models.Field):
  168
+        """A hand of cards (bridge style)"""
  169
+
166 170
         def __init__(self, *args, **kwargs):
167 171
             kwargs['max_length'] = 104
168 172
             super(HandField, self).__init__(*args, **kwargs)
@@ -244,6 +248,8 @@ simple: make sure your field subclass uses a special metaclass:
244 248
 For example::
245 249
 
246 250
     class HandField(models.Field):
  251
+        """A hand of cards (bridge style)"""
  252
+
247 253
         __metaclass__ = models.SubfieldBase
248 254
 
249 255
         def __init__(self, *args, **kwargs):
@@ -252,6 +258,21 @@ For example::
252 258
 This ensures that the :meth:`to_python` method, documented below, will always be
253 259
 called when the attribute is initialized.
254 260
 
  261
+
  262
+Documenting your Custom Field
  263
+-----------------------------
  264
+
  265
+As always, you should document your field type, so users will know what it is.
  266
+The best way to do this is to simply provide a docstring for it.  This will 
  267
+automatically be picked up by ``django.contrib.admindocs``, if you have it
  268
+installed, and the first line of it will show up as the field type in the 
  269
+documentation for any model that uses your field.  In the above examples, it 
  270
+will show up as 'A hand of cards (bridge style)'.  Note that if you provide a 
  271
+more verbose docstring, only the first line will show up in 
  272
+``django.contrib.admindocs``.  The full docstring will, of course, still be
  273
+available through ``pydoc`` or the interactive interpreter's ``help()`` 
  274
+function.
  275
+
255 276
 Useful methods
256 277
 --------------
257 278
 

0 notes on commit d10dd3e

Please sign in to comment.
Something went wrong with that request. Please try again.