update docs about custom type methods for readability and accuracy

fixes issue 151: Pylons#151

docs/extending.rst

@@ -33,10 +33,9 @@ serializes a boolean to the string ``true`` or ``false`` or the special
 .. code-block::  python
    :linenos:
 
-   from colander import Invalid
-   from colander import null
+   from colander import SchemaType, Invalid, null
 
-   class Boolean(object):
+   class Boolean(SchemaType):
        def serialize(self, node, appstruct):
            if appstruct is null:
                return null
@@ -54,9 +53,6 @@ serializes a boolean to the string ``true`` or ``false`` or the special
                return True
            return False
 
-       def cstruct_children(self, node, cstruct):
-           return []
-
 Here's how you would use the resulting class as part of a schema:
 
 .. code-block:: python
@@ -78,40 +74,52 @@ The constraints of a type class implementation are:
 
 - It must have both a ``serialize`` and ``deserialize`` method.
 
-- it must deal specially with the value :attr:`colander.null` within both
+- It must deal specially with the value :attr:`colander.null` within both
   ``serialize`` and ``deserialize``.
 
-- its ``serialize`` method must be able to make sense of a value generated by
+- Its ``serialize`` method must be able to make sense of a value generated by
   its ``deserialize`` method and vice versa.
 
-- its ``cstruct_children`` method must return an empty list if the node it's
-  passed has no children, or a value for each child node in the node it's
-  passed based on the ``cstruct``.
-
-The ``serialize`` method of a type accepts two values: ``node``, and
-``appstruct``.  ``node`` will be the schema node associated with this type.
-The node is used when the type must raise a :exc:`colander.Invalid` error,
-which expects a schema node as its first constructor argument.  ``appstruct``
-will be the :term:`appstruct` value that needs to be serialized.
-
-The deserialize and method of a type accept two values: ``node``, and
-``cstruct``.  ``node`` will be the schema node associated with this type.
-The node is used when the type must raise a :exc:`colander.Invalid` error,
-which expects a schema node as its first constructor argument.  ``cstruct``
-will be the :term:`cstruct` value that needs to be deserialized.
-
-The ``cstruct_children`` method accepts two values: ``node`` and ``cstruct``.
-``node`` will be the schema node associated with this type.  ``cstruct`` will
-be the :term:`cstruct` that the caller wants to obtain child values for.  The
-``cstruct_children`` method should *never* raise an exception, even if it
-passed a nonsensical value.  If it is passed a nonsensical value, it should
-return a sequence of ``colander.null`` values; the sequence should contain as
-many nulls as there are node children.  If the ``cstruct`` passed does not
-contain a value for a particular child, that child should be replaced with
-the ``colander.null`` value in the returned list.  Generally, if the type
-you're defining is not expected to have children, it's fine to return an
-empty list from ``cstruct_children``.  It's only useful for complex types
-such as mappings and sequences, usually.
+- If it contains child nodes, it must also implement ``cstruct_children``,
+  ``flatten``, ``unflatten``, ``set_value`` and ``get_value`` methods. It
+  may inherit from ``Mapping``, ``Tuple``, ``Set``, ``List`` or ``Sequence``
+  to obtain these methods, but only if the expected behavior is the same.
+
+
+**The ``serialize`` method accepts two arguments:**
+
+- ``node``: the ``SchemaNode`` associated with this type
+- ``appstruct``: the :term:`appstruct` value that needs to be serialized
+
+If ``appstruct`` is invalid, raise a :exc:`colander.Invalid` error, passing
+``node`` as its first constructor argument.
+
+
+**The ``deserialize`` and method accepts two arguments:**
+
+- ``node``: the ``SchemaNode`` associated with this type
+- ``cstruct``: the :term:`cstruct` value that needs to be deserialized
+
+If ``appstruct`` is invalid, raise a :exc:`colander.Invalid` error, passing
+``node`` as its first constructor argument.
+
+
+**The ``cstruct_children`` method accepts two arguments:**
+
+- ``node``: the ``SchemaNode`` associated with this type
+- ``cstruct``: the :term:`cstruct` that the caller wants to obtain child values
+  for
+
+``cstruct_children`` should return a value based on ``cstruct`` for
+each child node in ``node`` (or an empty list if ``node`` has no children). If
+``cstruct`` does not contain a value for a particular child, that child should
+be replaced with the ``colander.null`` value in the returned list.
+``cstruct_children`` should *never* raise an exception, even if it passed a
+nonsensical ``cstruct`` argument. In that case, it should return a sequence of
+as many ``colander.null`` values as there are child nodes. You only need to
+define this method for complex types that have child nodes, such as mappings
+and sequences.
+
 
 Null Values
 ~~~~~~~~~~~