From 85871fb33d86595c1b0a6c0c1f4191d8635f8d2a Mon Sep 17 00:00:00 2001
From: Thomas Adamcik <thomas@adamcik.no>
Date: Tue, 5 May 2015 00:00:22 +0200
Subject: [PATCH] docs: Improve fields documentation

---
 docs/api/models.rst     | 25 +++++++++++++++++++++++--
 mopidy/models/fields.py | 24 ++++++++++++++++++++++--
 2 files changed, 45 insertions(+), 4 deletions(-)

diff --git a/docs/api/models.rst b/docs/api/models.rst
index d2d8ec0a..d25e7f34 100644
--- a/docs/api/models.rst
+++ b/docs/api/models.rst
@@ -77,8 +77,29 @@ Data model helpers
 .. autoclass:: mopidy.models.ImmutableObject
     :members:
 
-.. autoclass:: mopidy.models.Field
+.. autoclass:: mopidy.models.ValidatedImmutableObject
+    :members: replace
+
+Data model (de)serialization
+----------------------------
+
+.. autofunction:: mopidy.models.model_json_decoder
 
 .. autoclass:: mopidy.models.ModelJSONEncoder
 
-.. autofunction:: mopidy.models.model_json_decoder
+Data model field types
+----------------------
+
+.. autoclass:: mopidy.models.fields.Field
+
+.. autoclass:: mopidy.models.fields.String
+
+.. autoclass:: mopidy.models.fields.Identifier
+
+.. autoclass:: mopidy.models.fields.URI
+
+.. autoclass:: mopidy.models.fields.Date
+
+.. autoclass:: mopidy.models.fields.Integer
+
+.. autoclass:: mopidy.models.fields.Collection
diff --git a/mopidy/models/fields.py b/mopidy/models/fields.py
index bd0ba9f9..01a03a75 100644
--- a/mopidy/models/fields.py
+++ b/mopidy/models/fields.py
@@ -73,20 +73,41 @@ class String(Field):
 
 
 class Date(String):
+    """
+    :class:`Field` for storing ISO 8601 dates as a string.
+
+    Supported formats are ``YYYY-MM-DD``, ``YYYY-MM`` and ``YYYY``, currently
+    not validated.
+
+    :param default: default value for field
+    """
     pass  # TODO: make this check for YYYY-MM-DD, YYYY-MM, YYYY using strptime.
 
 
 class Identifier(String):
+    """
+    :class:`Field` for storing ASCII values such as GUIDs or other identifiers.
+
+    Values will be interned.
+
+    :param default: default value for field
+    """
     def validate(self, value):
         return intern(str(super(Identifier, self).validate(value)))
 
 
 class URI(Identifier):
+    """
+    :class`Field` for storing URIs
+
+    Values will be interned, currently not validated.
+
+    :param default: default value for field
+    """
     pass  # TODO: validate URIs?
 
 
 class Integer(Field):
-
     """
     :class:`Field` for storing integer numbers.
 
@@ -112,7 +133,6 @@ class Integer(Field):
 
 
 class Collection(Field):
-
     """
     :class:`Field` for storing collections of a given type.