Merge pull request #248 from lmctv/document_drop_behavior

First attempt at documenting colander.drop

colander/__init__.py

@@ -48,8 +48,9 @@ null = _null()
 
 class _drop(object):
     """ Represents a value that will be dropped from the schema if it
-    is missing during *deserialization*.  Passed as a value to the
-    `missing` keyword argument of :class:`SchemaNode`.
+    is missing during *serialization* or *deserialization*.  Passed as
+    a value to the `missing` or `default` keyword argument
+    of :class:`SchemaNode`.
     """
     def __repr__(self):
         return '<colander.drop>'
@@ -1851,8 +1852,10 @@ class _SchemaNode(object):
     - ``typ``: The 'type' for this node can optionally be passed in as a
       keyword argument. See the documentation for the positional arg above.
 
-    - ``default``: The default serialization value for this node.
-      Default: :attr:`colander.null`.
+    - ``default``: The default serialization value for this node when
+      not set.  If ``default`` is :attr:`colander.drop`, the node
+      will be dropped from schema serialization.  If not provided,
+      the node will be serialized to :attr:`colander.null`.
 
     - ``missing``: The default deserialization value for this node.  If it is
       not provided, the missing value of this node will be the special marker
@@ -1860,7 +1863,7 @@ class _SchemaNode(object):
       'required'.  When ``missing`` is :attr:`colander.required`, the
       ``required`` computed attribute will be ``True``.  When ``missing`` is
       :attr:`colander.drop`, the node is dropped from the schema if it isn't
-      set during serialization/deserialization.
+      set during deserialization.
 
     - ``missing_msg``: Optional error message to be used if the value is
       required and missing.

docs/index.rst

@@ -58,7 +58,7 @@ internationalizable.
    :maxdepth: 2
 
    basics.rst
-   null.rst
+   null_and_drop.rst
    extending.rst
    binding.rst
    manipulation.rst

docs/null_and_drop.rst

@@ -1,21 +1,26 @@
-.. _null:
+.. _null_and_drop:
 
-The Null Value
-==============
+The Null and Drop Values
+========================
 
 :attr:`colander.null` is a sentinel value which may be passed to
 :meth:`colander.SchemaNode.serialize` during serialization or to
 :meth:`colander.SchemaNode.deserialize` during deserialization.
 
+:attr:`colander.drop` is a sentinel value which controls the
+behavior of collection-like :class:`colander.SchemaNode` subclasses.
+
 During serialization, the use of :attr:`colander.null` indicates that
 the :term:`appstruct` value corresponding to the node it's passed to
 is missing and the value of the ``default`` attribute of the
-corresponding node should be used instead.
+corresponding node should be used instead.  If the node's ``default``
+attribute is :attr:`colander.drop`, the serializer will skip the node.
 
 During deserialization, the use of :attr:`colander.null` indicates
 that the :term:`cstruct` value corresponding to the node it's passed
 to is missing, and if possible, the value of the ``missing`` attribute
-of the corresponding node should be used instead.
+of the corresponding node should be used instead. If the node's ``missing``
+attribute is :attr:`colander.drop`, the deserializer will skip the node.
 
 Note that :attr:`colander.null` has no relationship to the built-in Python
 ``None`` value.  ``colander.null`` is used instead of ``None`` because