WIP: better NoValue documentationnovalue-fixes-in-docs

6 files changed, 71 insertions, 25 deletions

diff --git a/CHANGES.rst b/CHANGES.rst
index 3c06812..7b13680 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -1,4 +1,9 @@
 
+Revision 0.4.3, released XX-11-2017
+-----------------------------------
+
+- Fixed to the docs here and there
+
 Revision 0.4.2, released 23-11-2017
 -----------------------------------
 
diff --git a/docs/source/pyasn1/contents.rst b/docs/source/pyasn1/contents.rst
index 102ea87..7d7dcb7 100644
--- a/docs/source/pyasn1/contents.rst
+++ b/docs/source/pyasn1/contents.rst
@@ -4,12 +4,11 @@
 Library documentation
 =====================
 
-As of this moment, pyasn1 library implements all ASN.1 data
-types as Python objects in accordance with X.208 standard. Later,
-post-1995, revision (X.680) introduced some changes to the schema
-language which may not be fully supported by pyasn1. Aside from data
-types a collection of data transformation codecs comes with the
-pyasn1 package.
+The pyasn1 library implements ASN.1 schema and data object as well as
+BER/DER/CER/Python serialisation codecs.
+
+The X.208 standard is mostly supported, its X.680 revision is supported
+only partially.
 
 As for ASN.1 schema language, pyasn1 package does
 not ship any compiler for it. However, there's a tool called
@@ -25,8 +24,8 @@ No external dependencies required.
 
 .. _pyasn1-types:
 
-ASN.1 types
------------
+Schema objects
+--------------
 
 The ASN.1 data description
 `language <https://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-X.208-198811-W!!PDF-E&type=items>`_
@@ -57,7 +56,8 @@ comprise a *schema* describing data structures of unbounded complexity.
            NamedType('publicExponent', Integer())
        )
 
-ASN.1 schema can be "instantiated" by essentially putting some concrete value
+ASN.1 schema can be "instantiated" by essentially replacing the default
+:ref:`noValue <univ.noValue>` sentinel object with some concrete value
 into the type container. Such instantiated schema object can still be
 used as a schema, but additionally it can play a role of a value in the
 context of any applicable operator (e.g. arithmetic etc.).
@@ -135,6 +135,11 @@ type's values.
    assert child_type_schema.isSubtypeOf(parent_type_schema) == True
    assert child_type_schema.isSameTypeWith(parent_type_schema) == False
 
+ASN.1 types
+-----------
+
+The ASN.1 standard introduces a collection of built-in data types
+categorized by their probable application.
 
 .. toctree::
    :maxdepth: 2
@@ -160,6 +165,9 @@ its :ref:`fields <type.namedtype>` specification.
    /pyasn1/type/opentype/contents
    /pyasn1/type/namedval/contents
 
+The :ref:`noValue <univ.NoValue>` sentinel object is the default for
+ASN.1 schema objects.
+
 .. _pyasn1-codecs:
 
 Serialisation codecs
diff --git a/docs/source/pyasn1/type/univ/contents.rst b/docs/source/pyasn1/type/univ/contents.rst
index 2a5ba25..d546e1c 100644
--- a/docs/source/pyasn1/type/univ/contents.rst
+++ b/docs/source/pyasn1/type/univ/contents.rst
@@ -32,7 +32,3 @@ and constructed.
    /pyasn1/type/univ/set
    /pyasn1/type/univ/sequence
    /pyasn1/type/univ/choice
-
-.. _univ.noValue:
-
-.. autoclass:: pyasn1.type.univ.NoValue()
diff --git a/docs/source/pyasn1/type/univ/novalue.rst b/docs/source/pyasn1/type/univ/novalue.rst
new file mode 100644
index 0000000..b7a448c
--- /dev/null
+++ b/docs/source/pyasn1/type/univ/novalue.rst
@@ -0,0 +1,12 @@
+
+.. _univ.NoValue:
+
+NoValue sentinel
+----------------
+
+.. autoclass:: pyasn1.type.univ.NoValue()
+   :members:
+
+.. note:
+
+    You can use the pre-instantiated `pyasn1.type.univ.noValue` object.
\ No newline at end of file
diff --git a/pyasn1/__init__.py b/pyasn1/__init__.py
index 1e99d6b..0f84991 100644
--- a/pyasn1/__init__.py
+++ b/pyasn1/__init__.py
@@ -1,7 +1,7 @@
 import sys
 
 # http://www.python.org/dev/peps/pep-0396/
-__version__ = '0.4.2'
+__version__ = '0.4.3'
 
 if sys.version_info[:2] < (2, 4):
     raise RuntimeError('PyASN1 requires Python 2.4 or later')
diff --git a/pyasn1/type/base.py b/pyasn1/type/base.py
index 9f52285..41e02fc 100644
--- a/pyasn1/type/base.py
+++ b/pyasn1/type/base.py
@@ -153,16 +153,29 @@ class Asn1ItemBase(Asn1Item):
 class NoValue(object):
     """Create a singleton instance of NoValue class.
 
-    The *NoValue* sentinel object represents an instance of ASN.1 schema
-    object as opposed to ASN.1 value object.
+    ASN.1 schema objects are always initialized with a *NoValue* instance.
 
-    Only ASN.1 schema-related operations can be performed on ASN.1
-    schema objects.
+    The instantiated ASN.1 schema objects (AKA *ASN.1 value objects*) are
+    always initialized with some data (e.g. :class:`int`, :class:`str` etc)
+    rather than with :class:`NoValue` object.
 
     Warning
     -------
-    Any operation attempted on the *noValue* object will raise the
-    *PyAsn1Error* exception.
+    Any operation attempted on the :class:`NoValue` object will raise the
+    *PyAsn1Error* exception to indicate an attempt of ASN.1 schema
+    use in the context where some usable data is expected.
+
+    Examples
+    --------
+    .. code-block:: python
+
+        schema_obj = Integer()  # e.g. just Integer(noValue)
+
+        schema_obj += 1  # throws exception
+
+        value_obj = Integer(123)
+        
+        value_obj += 1  # OK
     """
     skipMethods = set(
         ('__slots__',
@@ -236,8 +249,10 @@ class AbstractSimpleAsn1Item(Asn1ItemBase):
         Asn1ItemBase.__init__(self, **kwargs)
         if value is noValue:
             value = self.defaultValue
+
         else:
             value = self.prettyIn(value)
+
             try:
                 self.subtypeSpec(value)
 
@@ -302,6 +317,8 @@ class AbstractSimpleAsn1Item(Asn1ItemBase):
         this object can also be used like a Python built-in object (e.g. `int`,
         `str`, `dict` etc.).
 
+        The alternative term for value objects is *instantiated ASN.1 schema*.
+
         Returns
         -------
         : :class:`bool`
@@ -310,14 +327,22 @@ class AbstractSimpleAsn1Item(Asn1ItemBase):
 
         Note
         ----
-        There is an important distinction between PyASN1 schema and value objects.
-        The PyASN1 schema objects can only participate in ASN.1 schema-related
+        There is an important distinction between ASN1 schema and instantiated ASN.1
+        schema (AKA *value*) objects.
+        
+        The |ASN.1| schema object can only participate in ASN.1 schema-related
         operations (e.g. defining or testing the structure of the data). Most
         obvious uses of ASN.1 schema is to guide serialisation codecs whilst
         encoding/decoding serialised ASN.1 contents.
 
-        The PyASN1 value objects can **additionally** participate in many operations
-        involving regular Python objects (e.g. arithmetic, comprehension etc).
+        The instantiated |ASN.1| schema object can **additionally** participate in
+        many operations involving regular Python objects (e.g. arithmetic, 
+        comprehension etc).
+
+        Technically, |ASN.1| objects initialized with :py:class:`~pyasn1.type.univ.NoValue`
+        sentinel (which is the default) turn into ASN.1 schema. |ASN.1| objects
+        initialized with any  object other than *NoValue* turn into instantiated |ASN.1|
+        schema objects. 
         """
         return self._value is not noValue
 
@@ -355,7 +380,7 @@ class AbstractSimpleAsn1Item(Asn1ItemBase):
         subtype relationship between Python types. ASN.1 type is mainly identified
         by its tag(s) (:py:class:`~pyasn1.type.tag.TagSet`) and value range
         constraints (:py:class:`~pyasn1.type.constraint.ConstraintsIntersection`).
-        These ASN.1 type properties are implemented as |ASN.1| attributes.  
+        These ASN.1 type properties are implemented as |ASN.1| attributes.
 
         The `subtype()` method accepts the same set arguments as |ASN.1|
         class takes on instantiation except that all parameters