Fixed #67 -- Human-readable name is now optional in model fields. If a second positional argument isn't given, Django will use the first argument, converting underscores to spaces. This change is fully backwards-compatible.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@212 bcc190cf-cafb-0310-a4f2-bffc1f526a37

4 files changed, 41 insertions, 32 deletions

diff --git a/docs/db-api.txt b/docs/db-api.txt
index b01c85b5dd..f6ca07dd83 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -12,18 +12,18 @@ Throughout this reference, we'll refer to the following Poll application::
 
     class Poll(meta.Model):
         fields = (
-            meta.SlugField('slug', 'slug', unique_for_month='pub_date'),
-            meta.CharField('question', 'question', maxlength=255),
-            meta.DateTimeField('pub_date', 'date published'),
-            meta.DateTimeField('expire_date', 'expiration date'),
+            meta.SlugField('slug', unique_for_month='pub_date'),
+            meta.CharField('question', maxlength=255),
+            meta.DateTimeField('pub_date'),
+            meta.DateTimeField('expire_date'),
         )
 
     class Choice(meta.Model):
         fields = (
             meta.ForeignKey(Poll, edit_inline=True, edit_inline_type=meta.TABULAR,
                 num_in_admin=10, min_num_in_admin=5),
-            meta.CharField('choice', 'choice', maxlength=255, core=True),
-            meta.IntegerField('votes', 'votes', editable=False, default=0),
+            meta.CharField('choice', maxlength=255, core=True),
+            meta.IntegerField('votes', editable=False, default=0),
         )
 
 Basic lookup functions
@@ -351,6 +351,4 @@ the relation (``poll_id`` in this case).
 Deleting objects
 ================
 
-Just cause we're crazy like that, the delete method is named ``delete()``.
-Yeah, you never know what we're going to do next.
-
+The delete method, conveniently, is named ``delete()``.
diff --git a/docs/model-api.txt b/docs/model-api.txt
index 28a57edaf9..56c1a8cd14 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -34,9 +34,9 @@ wide array of options, only ``fields`` is required.
     A list of field objects. See `Field objects`_. For example::
 
         fields = (
-            meta.CharField('customer_name', 'customer name', maxlength=15),
-            meta.BooleanField('use_extra_cheese', 'use extra cheese'),
-            meta.IntegerField('customer_type', 'customer type', choices=CUSTOMER_TYPE_CHOICES),
+            meta.CharField('customer_name', maxlength=15),
+            meta.BooleanField('use_extra_cheese'),
+            meta.IntegerField('customer_type', choices=CUSTOMER_TYPE_CHOICES),
             ...
         )
 
@@ -123,10 +123,13 @@ the ``fields`` list is an instance of a ``meta.Field`` subclass and maps to
 a database field.
 
 All field objects -- except for ``ForeignKey`` and ``ManyToManyField`` (see
-below) -- take two positional arguments and a number of keyword arguments.
-The positional arguments are the field name and the human-readable name.  The
-field name must be a valid Python identifier, but the human-readable name can
-contain spaces, punctuation, etc.
+below) -- require the field's machine-readable name as the first positional
+argument. This must be a valid Python identifier -- no spaces, punctuation,
+etc., are allowed.
+
+The second positional argument, a human-readable name, is optional. If the
+human-readable name isn't given, Django will use the machine-readable name,
+coverting underscores to spaces.
 
 General field options
 ---------------------
@@ -226,7 +229,7 @@ Field Types
     use this directly; a primary key field will automatically be added to your
     model if you don't specify otherwise. That automatically-added field is::
 
-        meta.AutoField('id', 'ID', primary_key=True)
+        meta.AutoField('id', primary_key=True)
 
 ``BooleanField``
     A true/false field.
diff --git a/docs/overview.txt b/docs/overview.txt
index a7e0f1c14c..1453b70964 100644
--- a/docs/overview.txt
+++ b/docs/overview.txt
@@ -22,7 +22,7 @@ solving two years' worth of database-schema problems. Here's a quick example::
 
     class Reporter(meta.Model):
         fields = (
-            meta.CharField('full_name', "reporter's full name", maxlength=70),
+            meta.CharField('full_name', maxlength=70),
         )
 
         def __repr__(self):
@@ -30,9 +30,9 @@ solving two years' worth of database-schema problems. Here's a quick example::
 
     class Article(meta.Model):
         fields = (
-            meta.DateTimeField('pub_date', 'publication date'),
-            meta.CharField('headline', 'headline', maxlength=200),
-            meta.TextField('article', 'article'),
+            meta.DateTimeField('pub_date'),
+            meta.CharField('headline', maxlength=200),
+            meta.TextField('article'),
             meta.ForeignKey(Reporter),
         )
 
@@ -133,9 +133,9 @@ classes::
 
     class Article(meta.Model):
         fields = (
-            meta.DateTimeField('pub_date', 'publication date'),
-            meta.CharField('headline', 'headline', maxlength=200),
-            meta.TextField('article', 'article'),
+            meta.DateTimeField('pub_date'),
+            meta.CharField('headline', maxlength=200),
+            meta.TextField('article'),
             meta.ForeignKey(Reporter),
         )
         admin = meta.Admin(
@@ -302,7 +302,11 @@ features:
     * An RSS framework that makes creating RSS feeds as easy as writing a
       small Python class.
     * More sexy automatically-generated admin features -- this overview barely
-      scratched the surface
+      scratched the surface.
 
-The next obvious steps are for you to download Django, read the documentation
-and join the community. Thanks for your interest!
\ No newline at end of file
+The next obvious steps are for you to `download Django`_, read `the tutorial`_
+and join `the community`_. Thanks for your interest!
+
+.. _download Django: http://www.djangoproject.com/documentation/
+.. _the tutorial: http://www.djangoproject.com/documentation/tutorial1/
+.. _the community: http://www.djangoproject.com/community/
diff --git a/docs/tutorial01.txt b/docs/tutorial01.txt
index d2ad8e36e7..39d77fafd2 100644
--- a/docs/tutorial01.txt
+++ b/docs/tutorial01.txt
@@ -137,15 +137,15 @@ Edit the ``polls/models/polls.py`` file so that it looks like this::
 
     class Poll(meta.Model):
         fields = (
-            meta.CharField('question', 'question', maxlength=200),
+            meta.CharField('question', maxlength=200),
             meta.DateTimeField('pub_date', 'date published'),
         )
 
     class Choice(meta.Model):
         fields = (
             meta.ForeignKey(Poll),
-            meta.CharField('choice', 'choice', maxlength=200),
-            meta.IntegerField('votes', 'votes'),
+            meta.CharField('choice', maxlength=200),
+            meta.IntegerField('votes'),
         )
 
 The code is straightforward. Each model is represented by a class that
@@ -160,8 +160,12 @@ The first argument to each ``Field`` call is the field's name, in
 machine-friendly format. You'll use this value in your Python code, and your
 database will use it as the column name.
 
-The second argument is the field's human-readable name. That's used in a couple
-of introspective parts of Django, and it doubles as documentation.
+The second, optional, argument is the field's human-readable name. That's used
+in a couple of introspective parts of Django, and it doubles as documentation.
+If this field isn't provided, Django will use the machine-readable name. In
+this example, we've only defined a human-readable name for ``Poll.pub_date``.
+For all other fields in this model, the field's machine-readable name will
+suffice as its human-readable name.
 
 Some ``meta.*Field`` classes have additional required elements.
 ``meta.CharField``, for example, requires that you give it a ``maxlength``.