Ticket #4737: 4737.patch

docs/model-api.txt

@@ -471 +471 @@
 Field options
 -------------
 
-The following arguments are available to all field types. All are optional.
+All field types can take a number of options. These are split into two main
+categories; `field database options`_ which affect how the field is represented
+in the database, and `field meta options`_ which affect the field's display and
+validation. These meta options are only used by components which recognise 
+them, i.e. the admin interface and the form component.
 
+Field database options
+----------------------
+
 ``null``
 ~~~~~~~~
 
@@ -497 +504 @@
     be coerced for string-based fields that can blank, and the value
     ``NULL`` will be stored to denote the empty string.
 
+``db_column``
+~~~~~~~~~~~~~
+
+The name of the database column to use for this field. If this isn't given,
+Django will use the field's name.
+
+If your database column name is an SQL reserved word, or contains
+characters that aren't allowed in Python variable names -- notably, the
+hyphen -- that's OK. Django quotes column and table names behind the
+scenes.
+
+``db_index``
+~~~~~~~~~~~~
+
+If ``True``, ``django-admin.py sqlindexes`` will output a ``CREATE INDEX``
+statement for this field.
+
+``primary_key``
+~~~~~~~~~~~~~~~
+
+If ``True``, this field is the primary key for the model.
+
+If you don't specify ``primary_key=True`` for any fields in your model,
+Django will automatically add this field::
+
+    id = models.AutoField('ID', primary_key=True)
+
+Thus, you don't need to set ``primary_key=True`` on any of your fields
+unless you want to override the default primary-key behavior.
+
+``primary_key=True`` implies ``blank=False``, ``null=False`` and
+``unique=True``. Only one primary key is allowed on an object.
+
+``unique``
+~~~~~~~~~~
+
+If ``True``, this field must be unique throughout the table.
+
+This is enforced at the database level and at the Django admin-form level.
+
+Field meta options
+------------------
+
 ``blank``
 ~~~~~~~~~
 
@@ -574 +624 @@
 Django admin site. Essentially, this means you should put ``core=True`` on all
 required fields in your related object that is being edited inline.
 
-``db_column``
-~~~~~~~~~~~~~
-
-The name of the database column to use for this field. If this isn't given,
-Django will use the field's name.
-
-If your database column name is an SQL reserved word, or contains
-characters that aren't allowed in Python variable names -- notably, the
-hyphen -- that's OK. Django quotes column and table names behind the
-scenes.
-
-``db_index``
-~~~~~~~~~~~~
-
-If ``True``, ``django-admin.py sqlindexes`` will output a ``CREATE INDEX``
-statement for this field.
-
 ``db_tablespace``
 ~~~~~~~~~~~~~~~~~
 
@@ -620 +653 @@
 form. It's useful for documentation even if your object doesn't have an
 admin form.
 
-``primary_key``
-~~~~~~~~~~~~~~~
-
-If ``True``, this field is the primary key for the model.
-
-If you don't specify ``primary_key=True`` for any fields in your model,
-Django will automatically add this field::
-
-    id = models.AutoField('ID', primary_key=True)
-
-Thus, you don't need to set ``primary_key=True`` on any of your fields
-unless you want to override the default primary-key behavior.
-
-``primary_key=True`` implies ``blank=False``, ``null=False`` and
-``unique=True``. Only one primary key is allowed on an object.
-
 ``radio_admin``
 ~~~~~~~~~~~~~~~
 
@@ -646 +663 @@
 Don't use this for a field unless it's a ``ForeignKey`` or has ``choices``
 set.
 
-``unique``
-~~~~~~~~~~
-
-If ``True``, this field must be unique throughout the table.
-
-This is enforced at the database level and at the Django admin-form level.
-
 ``unique_for_date``
 ~~~~~~~~~~~~~~~~~~~