Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

[1.1.X] Apply doc addition that somehow was left out of r11834. Refs …

…#7977.

r11841 from trunk.


git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.1.X@11842 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit b5ffd10547e941a8514eae23bc1dc1ee908d2ff2 1 parent 08b5d95
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 b5ffd10

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