docs: add missing attribute docs and version added/changed specifiers (…

…fixes #35)

src/graceful/fields.py

@@ -63,7 +63,11 @@ def to_representation(self, value):
 
     """
 
+    #: Two-tuple ``(label, url)`` pointing to represented type specification
+    #: (for documentation).
     spec = None
+
+    #: String label of represented type (for documentation).
     type = None
 
     def __init__(

src/graceful/parameters.py

@@ -42,8 +42,12 @@ class BaseParam:
             list-compatible data type by overriding the ``container`` class
             attribute. See: :ref:`guide-params-custom-containers`.
 
+            .. versionadded:: 0.1.0
+
         validators (list): list of validator callables.
 
+            .. versionadded:: 0.2.0
+
     .. note::
         If ``many=False`` and client inlcudes multiple values for this
         parameter in query string then only one of those values will be
@@ -68,9 +72,18 @@ def value(self, data):
 
     """
 
+    #: Two-tuple ``(label, url)`` pointing to represented type specification
+    #: (for documentation).
     spec = None
+
+    #: String label of represented type (for documentation).
     type = None
 
+    #: Allows to specify
+    #: :ref:`custom containers <guide-params-custom-containers>`
+    #: on ``many=True`` params in user-defined parameter classes.
+    #:
+    #: .. versionadded:: 0.2.0
     container = list
 
     def __init__(
@@ -268,6 +281,8 @@ def value(self, raw_value):
 class BoolParam(BaseParam):
     """Describes parameter with value expressed as bool.
 
+    .. versionadded:: 0.2.0
+
     Accepted string values for boolean parameters are as follows:
 
     * False: ``['True', 'true', 'TRUE', 'T', 't', '1'}``

src/graceful/resources/base.py

@@ -91,6 +91,8 @@ class BaseResource(metaclass=MetaResource):
         default='0'
     )
 
+    #: Instance of serializer class used to serialize/deserialize and
+    #: validate resource representations.
     serializer = None
 
     @property
@@ -170,6 +172,9 @@ def describe(req, resp, **kwargs):
         Returns:
             dict: dictionary with resource descritpion information
 
+        .. versionchanged:: 0.2.0
+           The `req` and `resp` parameters became optional to ease the
+           implementation of application-level documentation generators.
         """
         description = {
             'params': OrderedDict([
@@ -204,6 +209,10 @@ def on_options(self, req, resp, **kwargs):
         Returns:
             None
 
+
+        .. versionchanged:: 0.2.0
+           Default ``OPTIONS`` responses include ``Allow`` header with list of
+           allowed HTTP methods.
         """
         resp.set_header('Allow', ', '.join(self.allowed_methods()))
         resp.body = json.dumps(self.describe(req, resp))