Write documentation for the Instance class.

docs/conf.py

@@ -113,7 +113,7 @@ todo_include_todos = False
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/index.rst

@@ -7,7 +7,7 @@ Contents:
    :maxdepth: 2
 
    instances
-
+   references
 
 Indices and tables
 ==================

docs/instances.rst

@@ -2,50 +2,96 @@
 Data Instances
 **************
 
-In-memory representation of instance data is implemented using the :class:`Instance` class:
+.. module:: yangson.instance
+   :synopsis: Classes and methods for working with YANG data
+	      instances.
+.. moduleauthor:: Ladislav Lhotka <lhotka@nic.cz>
 
-.. class:: Instance(value: Value, crumb: Crumb)
+The standard library function :func:`json.load` parses JSON text into
+convenient Python values – scalars, lists and dictionaries. For JSON-encoded
+YANG data instances, we need to add a bit of extra processing and more
+intelligent data structures. The reasons are as follows:
+
+* In order to be able to generate entity tags for HTTP ``ETag``
+  headers, we need a hash value for every scalar, array or
+  object. Unlike scalars, though, we can't use the built-in
+  :func:`hash` function to compute such a value for :class:`list` and
+  :class:`dict` instances, so we need to *subclass* those two built-in
+  classes and implement the :meth:`__hash__` method in the subclasses.
+
+* We also need each array and object to keep the time stamp of its
+  last modification (to be used in HTTP ``Last-Modified`` headers).
+
+* All 64-bit numbers (of YANG types ``int64``, ``uint64`` and
+  ``decimal64``) are encoded as JSON strings [Lho16]_, so we need to
+  convert them to :class:`int` and :class:`decimal.decimal` values.
 
-Each data instance has two slots:
+* From every value in the data tree, we need access to its parent
+  array or object.
 
-* *value* is a JSON-like value containing the instance data (configuration, state data etc.)
-* *crumb* makes each instance into a `persistent structure`__ that allows for editing the data while keeping the original version intact.
+* Last but not least, the data tree needs to be a `persistent
+  structure`__ so that we can edit it and, at the same time, keeping
+  the original version intact.
+
+The following classes and their method implement all this functionality.
 
 __ https://en.wikipedia.org/wiki/Persistent_data_structure
 
 Instance Values
 ===============
 
-.. class:: StructuredValue(ts:datetime.datetime=None) -> None:
+.. class:: StructuredValue(ts:datetime.datetime=None)
 
-   This class is an abstract superclass of both :class:ArrayValue and
-   :class:ObjectValue. It implements an equality test based on the
-   hash value.
+   This class is an abstract superclass of both :class:`ArrayValue` and
+   :class:`ObjectValue`.
 
-   .. attribute::last_modified
+   .. attribute:: last_modified
 
       This attribute contains a :class:`datetime.datetime` that
       records the date and time when the :class:StructuredValue
       instance was last modified.
 
-   .. method::time_stamp(ts:datetime.datetime=None)
+   .. method:: time_stamp(ts: datetime.datetime = None) -> None
 
       Update the receiver's *last_modified* time stamp with the value
       *ts*. If *ts* is ``None``, use the current date and time.
 
+   .. method:: __eq__(val: StructuredValue) -> bool
+
+      Return ``True`` if the receiver and *val* are equality. Equality
+      is based on their hash values (see below).
+
 .. class:: ArrayValue(ts:datetime.datetime=None)
 
-   This class is a subclass of both :class:StructuredValue and
-   :class:list, and corresponds to a JSON array.
+   This class is a subclass of both :class:`StructuredValue` and
+   :class:`list`, and corresponds to a JSON array.
+
+   .. method:: __hash__() -> int
+
+      Return integer hash value. It is computed by converting the
+      receiver to a :class:`tuple` and applying the :func:`hash`
+      function to it.
 
 .. class:: ObjectValue(ts:datetime.datetime=None)
 
-   This class is a subclass of both :class:StructuredValue and
-   :class:dict, and corresponds to a JSON object.
+   This class is a subclass of both :class:`StructuredValue` and
+   :class:`dict`, and corresponds to a JSON object.
+
+   All member names must be identifiers of YANG data nodes. Such a
+   name must be qualified with the YANG module module name in which
+   the node is defined if and only if either
+
+   * the data node is the root of a data tree, i.e. has no parent data
+     nodes, or
+   * the data node's parent is defined in the same module.
 
-Both :class:`ArrayValue` and :class:`ObjectValue` implement the
-:meth:`__hash__` method, so their instances can be used as arguments of
-the :func:hash function.
+   .. method:: __hash__() -> int
 
-Instance values are essentially the same as values returned by
-:func:`json.load` function, with the following exceptions.
+      Return integer hash value. It is computed by taking a sorted
+      list of the receiver's items, converting it to a :class:`tuple`
+      and applying the :func:`hash` function.
+
+Persistent Instances
+====================
+
+.. class:: Instance(value: Value, crumb: Crumb)

docs/references.rst

+**********
+References
+**********
+
+.. [Lho16] Lhotka, L. *JSON Encoding of Data Modeled with YANG.*
+	   `draft-ietf-netmod-yang-json`__, IETF, 2016.
+
+__ https://tools.ietf.org/html/draft-ietf-netmod-yang-json