Introduce description; make title the same as name.

colander/__init__.py

@@ -573,7 +573,8 @@ class SchemaNode(object):
         self.validator = kw.get('validator', None)
         self.default = kw.get('default', _missing)
         self.name = kw.get('name', '')
-        self.title = kw.get('title', self.name.capitalize())
+        self.title = kw.get('title', self.name)
+        self.description = kw.get('description', '')
         self.nodes = list(nodes)
 
     def __repr__(self):
@@ -610,6 +611,8 @@ class _SchemaMeta(type):
         for name, value in clsattrs.items():
             if isinstance(value, SchemaNode):
                 value.name = name
+                if not value.title:
+                    value.title = name
                 nodes.append((value._order, value))
         cls.__schema_nodes__ = nodes
         # Combine all attrs from this class and its subclasses.

colander/tests.py

@@ -810,7 +810,7 @@ class TestSchemaNode(unittest.TestCase):
         self.assertEqual(node.validator, 1)
         self.assertEqual(node.default, 2)
         self.assertEqual(node.name, 'name')
-        self.assertEqual(node.title, 'Name')
+        self.assertEqual(node.title, 'name')
 
     def test_ctor_with_title(self):
         node = self._makeOne(None, 0, validator=1, default=2, name='name',
@@ -822,6 +822,11 @@ class TestSchemaNode(unittest.TestCase):
         self.assertEqual(node.name, 'name')
         self.assertEqual(node.title, 'title')
 
+    def test_ctor_with_description(self):
+        node = self._makeOne(None, 0, validator=1, default=2, name='name',
+                             title='title', description='desc')
+        self.assertEqual(node.description, 'desc')
+
     def test_required_true(self):
         node = self._makeOne(None)
         self.assertEqual(node.required, True)
@@ -870,12 +875,15 @@ class TestSchema(unittest.TestCase):
         import colander
         class MySchema(colander.Schema):
             thing = colander.SchemaNode(colander.String())
+            thing2 = colander.SchemaNode(colander.String(), title='bar')
         node = MySchema(unknown_keys='raise')
         self.failUnless(hasattr(node, '_order'))
         self.assertEqual(node.__class__, colander.SchemaNode)
         self.assertEqual(node.typ.__class__, colander.Mapping)
         self.assertEqual(node.typ.unknown_keys, 'raise')
-        self.assertEqual(node.nodes[0].typ.__class__, colander.String)
+        self.assertEqual(node.nodes[0].typ.__class__, colander.String) 
+        self.assertEqual(node.nodes[0].title, 'thing')
+        self.assertEqual(node.nodes[1].title, 'bar')
         
 class TestSequenceSchema(unittest.TestCase):
     def test_it(self):

docs/index.rst

@@ -121,7 +121,8 @@ A schema is composed of one or more *schema node* objects, each
 typically of the class :class:`colander.SchemaNode`, usually in a
 nested arrangement.  Each schema node object has a required *type*, an
 optional deserialization *validator*, an optional *default*, an
-optional *title*, and a slightly less optional *name*.
+optional *title*, an optional *description*, and a slightly less
+optional *name*.
 
 The *type* of a schema node indicates its data type (such as
 :class:`colander.Int` or :class:`colander.String`).
@@ -141,8 +142,11 @@ considered required.
 The *name* of a schema node appears in error reports.
 
 The *title* of a schema node is metadata about a schema node that can
-be used by higher-level systems.  By default, it is a capitalizaton of
-the *name*.
+be used by higher-level systems.  By default, it is the same as the
+*name*.
+
+The *description* of a schema node is metadata about a schema node
+that can be used by higher-level systems.  By default, it is empty.
 
 The name of a schema node that is introduced as a class-level
 attribute of a :class:`colander.MappingSchema`,
@@ -161,7 +165,7 @@ its class attribute name.  For example:
 
 The name of the schema node defined via ``location =
 colander.SchemaNode(..)`` within the schema above is ``location``.
-The title of the same schema node is ``Location``.
+The title of the same schema node is ``location``.
 
 Schema Objects
 ~~~~~~~~~~~~~~