More napoleonizing.

3 files changed, 146 insertions, 87 deletions

diff --git a/docs/creating.rst b/docs/creating.rst
index f9cef2a..aed7b28 100644
--- a/docs/creating.rst
+++ b/docs/creating.rst
@@ -10,35 +10,49 @@ Creating or Extending Validator Classes
 
     Create a new validator class.
 
-    :argument dict meta_schema: the meta schema for the new validator class
+    Arguments:
 
-    :argument dict validators: a mapping from names to callables, where
-        each callable will validate the schema property with the given
-        name.
+        meta_schema (collections.Mapping):
 
-        Each callable should take 4 arguments:
+            the meta schema for the new validator class
 
-            1. a validator instance,
-            2. the value of the property being validated within the instance
-            3. the instance
-            4. the schema
+        validators (collections.Mapping):
 
-    :argument str version: an identifier for the version that this
-        validator class will validate. If provided, the returned validator
-        class will have its ``__name__`` set to include the version, and
-        also will have `jsonschema.validators.validates` automatically
-        called for the given version.
+            a mapping from names to callables, where each callable will
+            validate the schema property with the given name.
 
-    :argument dict default_types:
-        .. deprecated:: 2.7.0 Please use the type_checker argument instead.
+            Each callable should take 4 arguments:
 
-        If set, it provides mappings of JSON types to Python types that will
-        be converted to functions and redefined in this object's
-        `jsonschema.TypeChecker`.
+                1. a validator instance,
+                2. the value of the property being validated within the
+                   instance
+                3. the instance
+                4. the schema
 
-    :argument jsonschema.TypeChecker type_checker: a type checker. If
-        unprovided, a `jsonschema.TypeChecker` will created with no
-        supported types.
+        version (str):
+
+            an identifier for the version that this validator class will
+            validate. If provided, the returned validator class will have its
+            ``__name__`` set to include the version, and also will have
+            `jsonschema.validators.validates` automatically called for the
+            given version.
+
+        type_checker (jsonschema.TypeChecker):
+
+            a type checker, used when applying the :validator:`type` validator.
+
+            If unprovided, an empty `jsonschema.TypeChecker` will created with
+            no known default types.
+
+        default_types (collections.Mapping):
+
+            .. deprecated:: 2.7.0
+
+                Please use the type_checker argument instead.
+
+            If set, it provides mappings of JSON types to Python types that
+            will be converted to functions and redefined in this object's
+            `jsonschema.TypeChecker`.
 
     Returns:
 
@@ -49,26 +63,39 @@ Creating or Extending Validator Classes
 
     Create a new validator class by extending an existing one.
 
-    :argument jsonschema.IValidator validator: an existing validator class
+    Arguments:
+
+        validator (jsonschema.IValidator):
+
+            an existing validator class
 
-    :argument dict validators: a mapping of new validator callables to extend
-        with, whose structure is as in `create`\ .
+        validators (collections.Mapping):
 
-        .. note::
+            a mapping of new validator callables to extend with, whose
+            structure is as in `create`.
 
-            Any validator callables with the same name as an existing one will
-            (silently) replace the old validator callable entirely, effectively
-            overriding any validation done in the "parent" validator class.
+            .. note::
 
-            If you wish to instead extend the behavior of a parent's
-            validator callable, delegate and call it directly in
-            the new validator function by retrieving it using
-            ``OldValidator.VALIDATORS["validator_name"]``.
+                Any validator callables with the same name as an existing one
+                will (silently) replace the old validator callable entirely,
+                effectively overriding any validation done in the "parent"
+                validator class.
 
-    :argument str version: a version for the new validator class
+                If you wish to instead extend the behavior of a parent's
+                validator callable, delegate and call it directly in the new
+                validator function by retrieving it using
+                ``OldValidator.VALIDATORS["validator_name"]``.
 
-    :argument jsonschema.TypeChecker type_checker: a type checker. If
-        unprovided, the existing `jsonschema.TypeChecker` will be used.
+        version (str):
+
+            a version for the new validator class
+
+        type_checker (jsonschema.TypeChecker):
+
+            a type checker, used when applying the :validator:`type` validator.
+
+            If unprovided, the type checker of the extended
+            `jsonschema.IValidator` will be carried along.`
 
     Returns:
 
@@ -92,10 +119,19 @@ Creating or Extending Validator Classes
     Uses the :validator:`$schema` property that should be present in the given
     schema to look up the appropriate validator class.
 
-    :argument schema: the schema to look at
-    :argument default: the default to return if the appropriate validator class
-        cannot be determined. If unprovided, the default is to return
-        `jsonschema.Draft4Validator`
+    Arguments:
+
+        schema (dict):
+
+            the schema to look at
+
+        default:
+
+            the default to return if the appropriate validator class cannot be
+            determined.
+
+            If unprovided, the default is to return
+            `jsonschema.Draft4Validator`.
 
 
 .. autofunction:: validates
diff --git a/docs/errors.rst b/docs/errors.rst
index 324884f..9a950b0 100644
--- a/docs/errors.rst
+++ b/docs/errors.rst
@@ -371,16 +371,23 @@ to guess the most relevant error in a given bunch.
     since these validators only need to match once, and any other errors may
     not be relevant.
 
-    :argument collections.Iterable errors: the errors to select from. Do not
-        provide a mixture of errors from different validation attempts
-        (i.e. from different instances or schemas), since it won't
-        produce sensical output.
-    :argument callable key: the key to use when sorting errors. See
-        `relevance` and transitively `by_relevance` for more
-        details (the default is to sort with the defaults of that function).
-        Changing the default is only useful if you want to change the function
-        that rates errors but still want the error context descent done by
-        this function.
+    Arguments:
+
+        errors (collections.Iterable):
+
+            the errors to select from. Do not provide a mixture of errors from
+            different validation attempts (i.e. from different instances or
+            schemas), since it won't produce sensical output.
+
+        key (callable):
+
+            the key to use when sorting errors.
+
+            See `relevance` and transitively `by_relevance` for more details
+            (the default is to sort with the defaults of that function).
+            Changing the default is only useful if you want to change the
+            function that rates errors but still want the error context descent
+            done by this function.
 
     Returns:
 
@@ -435,11 +442,17 @@ to guess the most relevant error in a given bunch.
 
     Create a key function that can be used to sort errors by relevance.
 
-    :argument set weak: a collection of validator names to consider to
-        be "weak". If there are two errors at the same level of the
-        instance and one is in the set of weak validator names, the
-        other error will take priority. By default, :validator:`anyOf`
-        and :validator:`oneOf` are considered weak validators and will
-        be superseded by other same-level validation errors.
-    :argument set strong: a collection of validator names to consider to
-        be "strong"
+    Arguments:
+
+        weak (collections.Set):
+
+            a collection of validator names to consider to be "weak". If there
+            are two errors at the same level of the instance and one is in the
+            set of weak validator names, the other error will take priority. By
+            default, :validator:`anyOf` and :validator:`oneOf` are considered
+            weak validators and will be superseded by other same-level
+            validation errors.
+
+        strong (collections.Set):
+
+            a collection of validator names to consider to be "strong"
diff --git a/docs/validate.rst b/docs/validate.rst
index 5de06b3..1489eb3 100644
--- a/docs/validate.rst
+++ b/docs/validate.rst
@@ -28,40 +28,40 @@ classes should adhere to.
 
 .. class:: IValidator(schema, types=(), resolver=None, format_checker=None)
 
-    :argument dict schema: the schema that the validator object
-        will validate with. It is assumed to be valid, and providing
-        an invalid schema can lead to undefined behavior. See
-        `IValidator.check_schema` to validate a schema first.
-    :argument types:
+    Arguments:
 
-        .. deprecated:: 2.7.0
+        schema (dict):
 
-            Instead, create a custom type checker and extend the validator.
-           
-            See `validating-types` for details.
-
-        If used, this overrides or extends the list of known type when
-        validating the :validator:`type` property. Should map strings (type
-        names) to class objects that will be checked via `isinstance`.
-    :type types: dict or ~collections.Iterable of 2-`tuple`\s
-    :argument resolver: an instance of `RefResolver` that will be
-        used to resolve :validator:`$ref` properties (JSON references). If
-        unprovided, one will be created.
-    :argument format_checker: an instance of `FormatChecker`
-        whose `FormatChecker.conforms` method will be called to
-        check and see if instances conform to each :validator:`format`
-        property present in the schema. If unprovided, no validation
-        will be done for :validator:`format`.
+            the schema that the validator object will validate with. It is
+            assumed to be valid, and providing an invalid schema can lead to
+            undefined behavior. See `IValidator.check_schema` to validate a
+            schema first.
 
-    .. attribute:: DEFAULT_TYPES
+        resolver (RefResolver):
 
-        .. deprecated:: 2.7.0
-           Use of this attribute is deprecated in favour of the the new type
-           checkers.
+            an instance of `RefResolver` that will be used to resolve
+            :validator:`$ref` properties (JSON references). If unprovided, one
+            will be created.
 
-        It provides mappings of JSON types to Python types that will
-        be converted to functions and redefined in this object's type checker
-        if one is not provided.
+        format_checker (FormatChecker):
+
+            a format checker whose `FormatChecker.conforms` method will be
+            called to check and see if instances conform to each
+            :validator:`format` property present in the schema.
+
+            If unprovided, no validation will be done for :validator:`format`.
+
+        types (dict or collections.Iterable of 2-tuples):
+
+            .. deprecated:: 2.7.0
+
+                Instead, create a custom type checker and extend the validator.
+
+                See `validating-types` for details.
+
+            If used, this overrides or extends the list of known type when
+            validating the :validator:`type` property. Should map strings (type
+            names) to class objects that will be checked via `isinstance`.
 
     .. attribute:: META_SCHEMA
 
@@ -82,6 +82,16 @@ classes should adhere to.
 
         The schema that was passed in when initializing the object.
 
+    .. attribute:: DEFAULT_TYPES
+
+        .. deprecated:: 2.7.0
+           Use of this attribute is deprecated in favour of the the new type
+           checkers.
+
+        It provides mappings of JSON types to Python types that will
+        be converted to functions and redefined in this object's type checker
+        if one is not provided.
+
 
     .. classmethod:: check_schema(schema)