Add more content to docs (#96)

* minor fixes to RsT docstrings
* more explanations in the docs, better linkage
* cosmetic fixes to NamedValues() docstring

11 files changed, 87 insertions, 47 deletions

diff --git a/pyasn1/codec/ber/decoder.py b/pyasn1/codec/ber/decoder.py
index 8bdffcf..725eaa3 100644
--- a/pyasn1/codec/ber/decoder.py
+++ b/pyasn1/codec/ber/decoder.py
@@ -1329,15 +1329,17 @@ class Decoder(object):
 
 #: Turns BER octet stream into an ASN.1 object.
 #:
-#: Takes BER octetstream and decode it into an ASN.1 object
+#: Takes BER octet-stream and decode it into an ASN.1 object
 #: (e.g. :py:class:`~pyasn1.type.base.PyAsn1Item` derivative) which
 #: may be a scalar or an arbitrary nested structure.
 #:
 #: Parameters
 #: ----------
 #: substrate: :py:class:`bytes` (Python 3) or :py:class:`str` (Python 2)
-#:     BER octetstream
+#:     BER octet-stream
 #:
+#: Keyword Args
+#: ------------
 #: asn1Spec: any pyasn1 type object e.g. :py:class:`~pyasn1.type.base.PyAsn1Item` derivative
 #:     A pyasn1 type object to act as a template guiding the decoder. Depending on the ASN.1 structure
 #:     being decoded, *asn1Spec* may or may not be required. Most common reason for
diff --git a/pyasn1/codec/ber/encoder.py b/pyasn1/codec/ber/encoder.py
index 3f19c8a..c8eac34 100644
--- a/pyasn1/codec/ber/encoder.py
+++ b/pyasn1/codec/ber/encoder.py
@@ -646,6 +646,8 @@ class Encoder(object):
 #:     A Python or pyasn1 object to encode. If Python object is given, `asnSpec`
 #:     parameter is required to guide the encoding process.
 #:
+#: Keyword Args
+#: ------------
 #: asn1Spec:
 #:     Optional ASN.1 schema or value object e.g. :py:class:`~pyasn1.type.base.PyAsn1Item` derivative
 #:
diff --git a/pyasn1/codec/cer/decoder.py b/pyasn1/codec/cer/decoder.py
index a93b9a6..3cc29c7 100644
--- a/pyasn1/codec/cer/decoder.py
+++ b/pyasn1/codec/cer/decoder.py
@@ -63,15 +63,17 @@ class Decoder(decoder.Decoder):
 
 #: Turns CER octet stream into an ASN.1 object.
 #:
-#: Takes CER octetstream and decode it into an ASN.1 object
+#: Takes CER octet-stream and decode it into an ASN.1 object
 #: (e.g. :py:class:`~pyasn1.type.base.PyAsn1Item` derivative) which
 #: may be a scalar or an arbitrary nested structure.
 #:
 #: Parameters
 #: ----------
 #: substrate: :py:class:`bytes` (Python 3) or :py:class:`str` (Python 2)
-#:     CER octetstream
+#:     CER octet-stream
 #:
+#: Keyword Args
+#: ------------
 #: asn1Spec: any pyasn1 type object e.g. :py:class:`~pyasn1.type.base.PyAsn1Item` derivative
 #:     A pyasn1 type object to act as a template guiding the decoder. Depending on the ASN.1 structure
 #:     being decoded, *asn1Spec* may or may not be required. Most common reason for
diff --git a/pyasn1/codec/cer/encoder.py b/pyasn1/codec/cer/encoder.py
index 8acd580..b4c68ec 100644
--- a/pyasn1/codec/cer/encoder.py
+++ b/pyasn1/codec/cer/encoder.py
@@ -257,13 +257,15 @@ class Encoder(encoder.Encoder):
 #:     A Python or pyasn1 object to encode. If Python object is given, `asnSpec`
 #:     parameter is required to guide the encoding process.
 #:
+#: Keyword Args
+#: ------------
 #: asn1Spec:
 #:     Optional ASN.1 schema or value object e.g. :py:class:`~pyasn1.type.base.PyAsn1Item` derivative
 #:
 #: Returns
 #: -------
 #: : :py:class:`bytes` (Python 3) or :py:class:`str` (Python 2)
-#:     Given ASN.1 object encoded into BER octetstream
+#:     Given ASN.1 object encoded into BER octet-stream
 #:
 #: Raises
 #: ------
diff --git a/pyasn1/codec/der/decoder.py b/pyasn1/codec/der/decoder.py
index 4977a05..1da37a0 100644
--- a/pyasn1/codec/der/decoder.py
+++ b/pyasn1/codec/der/decoder.py
@@ -43,15 +43,17 @@ class Decoder(decoder.Decoder):
 
 #: Turns DER octet stream into an ASN.1 object.
 #:
-#: Takes DER octetstream and decode it into an ASN.1 object
+#: Takes DER octet-stream and decode it into an ASN.1 object
 #: (e.g. :py:class:`~pyasn1.type.base.PyAsn1Item` derivative) which
 #: may be a scalar or an arbitrary nested structure.
 #:
 #: Parameters
 #: ----------
 #: substrate: :py:class:`bytes` (Python 3) or :py:class:`str` (Python 2)
-#:     DER octetstream
+#:     DER octet-stream
 #:
+#: Keyword Args
+#: ------------
 #: asn1Spec: any pyasn1 type object e.g. :py:class:`~pyasn1.type.base.PyAsn1Item` derivative
 #:     A pyasn1 type object to act as a template guiding the decoder. Depending on the ASN.1 structure
 #:     being decoded, *asn1Spec* may or may not be required. Most common reason for
diff --git a/pyasn1/codec/der/encoder.py b/pyasn1/codec/der/encoder.py
index 0a39e71..8496252 100644
--- a/pyasn1/codec/der/encoder.py
+++ b/pyasn1/codec/der/encoder.py
@@ -70,13 +70,15 @@ class Encoder(encoder.Encoder):
 #:     A Python or pyasn1 object to encode. If Python object is given, `asnSpec`
 #:     parameter is required to guide the encoding process.
 #:
+#: Keyword Args
+#: ------------
 #: asn1Spec:
 #:     Optional ASN.1 schema or value object e.g. :py:class:`~pyasn1.type.base.PyAsn1Item` derivative
 #:
 #: Returns
 #: -------
 #: : :py:class:`bytes` (Python 3) or :py:class:`str` (Python 2)
-#:     Given ASN.1 object encoded into BER octetstream
+#:     Given ASN.1 object encoded into BER octet-stream
 #:
 #: Raises
 #: ------
diff --git a/pyasn1/codec/native/decoder.py b/pyasn1/codec/native/decoder.py
index e5d0a53..cd60649 100644
--- a/pyasn1/codec/native/decoder.py
+++ b/pyasn1/codec/native/decoder.py
@@ -177,6 +177,8 @@ class Decoder(object):
 #: pyObject: :py:class:`object`
 #:     A scalar or nested Python objects
 #:
+#: Keyword Args
+#: ------------
 #: asn1Spec: any pyasn1 type object e.g. :py:class:`~pyasn1.type.base.PyAsn1Item` derivative
 #:     A pyasn1 type object to act as a template guiding the decoder. It is required
 #:     for successful interpretation of Python objects mapping into their ASN.1
diff --git a/pyasn1/type/char.py b/pyasn1/type/char.py
index 2a04bd1..29fe7dc 100644
--- a/pyasn1/type/char.py
+++ b/pyasn1/type/char.py
@@ -23,8 +23,8 @@ class AbstractCharacterString(univ.OctetString):
     |ASN.1| objects are immutable and duck-type Python 2 :class:`unicode` or Python 3 :class:`str`.
     When used in octet-stream context, |ASN.1| type assumes "|encoding|" encoding.
 
-    Parameters
-    ----------
+    Keyword Args
+    ------------
     value: :class:`unicode`, :class:`str`, :class:`bytes` or |ASN.1| object
         unicode object (Python 2) or string (Python 3), alternatively string
         (Python 2) or bytes (Python 3) representing octet-stream of serialized
diff --git a/pyasn1/type/namedval.py b/pyasn1/type/namedval.py
index 008ddc0..d2d0f25 100644
--- a/pyasn1/type/namedval.py
+++ b/pyasn1/type/namedval.py
@@ -23,26 +23,34 @@ class NamedValues(object):
 
     Parameters
     ----------
-
     \*args: variable number of two-element :py:class:`tuple` 
-    \*\*kwargs: keyword parameters of:
-        
+
         name: :py:class:`str`
-            Value name
-    
+            Value label
+
         value: :py:class:`int`
-                A numerical value
+            Numeric value
+
+    Keyword Args
+    ------------
+    name: :py:class:`str`
+        Value label
+
+    value: :py:class:`int`
+        Numeric value
 
     Examples
     --------
 
-    >>> nv = namedval.NamedValues('a', 'b', ('c', 0), d=1)
-    >>> nv
-    >>> {'c': 0, 'd': 1, 'a': 2, 'b': 3}
-    >>> nv[0]
-    'c'
-    >>> nv['a']
-    2
+    .. code-block:: pycon
+
+        >>> nv = NamedValues('a', 'b', ('c', 0), d=1)
+        >>> nv
+        >>> {'c': 0, 'd': 1, 'a': 2, 'b': 3}
+        >>> nv[0]
+        'c'
+        >>> nv['a']
+        2
     """
     def __init__(self, *args, **kwargs):
         self.__names = {}
diff --git a/pyasn1/type/univ.py b/pyasn1/type/univ.py
index 724fa55..43c0d2c 100644
--- a/pyasn1/type/univ.py
+++ b/pyasn1/type/univ.py
@@ -27,9 +27,9 @@ class Integer(base.AbstractSimpleAsn1Item):
 
     |ASN.1| objects are immutable and duck-type Python :class:`int` objects.
 
-    Parameters
-    ----------
-    value : :class:`int`, :class:`str` or |ASN.1| object
+    Keyword Args
+    ------------
+    value: :class:`int`, :class:`str` or |ASN.1| object
         Python integer or string literal or |ASN.1| class instance.
 
     tagSet: :py:class:`~pyasn1.type.tag.TagSet`
@@ -279,9 +279,9 @@ class BitString(base.AbstractSimpleAsn1Item):
     |ASN.1| objects are immutable and duck-type both Python :class:`tuple` (as a tuple
     of bits) and :class:`int` objects.
 
-    Parameters
-    ----------
-    value : :class:`int`, :class:`str` or |ASN.1| object
+    Keyword Args
+    ------------
+    value: :class:`int`, :class:`str` or |ASN.1| object
         Python integer or string literal representing binary or hexadecimal
         number or sequence of integer bits or |ASN.1| object.
 
@@ -640,9 +640,9 @@ class OctetString(base.AbstractSimpleAsn1Item):
     |ASN.1| objects are immutable and duck-type Python 2 :class:`str` or Python 3 :class:`bytes`.
     When used in Unicode context, |ASN.1| type assumes "|encoding|" serialization.
 
-    Parameters
-    ----------
-    value : :class:`str`, :class:`bytes` or |ASN.1| object
+    Keyword Args
+    ------------
+    value: :class:`str`, :class:`bytes` or |ASN.1| object
         string (Python 2) or bytes (Python 3), alternatively unicode object
         (Python 2) or string (Python 3) representing character string to be
         serialized into octets (note `encoding` parameter) or |ASN.1| object.
@@ -927,9 +927,9 @@ class Null(OctetString):
 
     |ASN.1| objects are immutable and duck-type Python :class:`str` objects (always empty).
 
-    Parameters
-    ----------
-    value : :class:`str` or :py:class:`~pyasn1.type.univ.Null` object
+    Keyword Args
+    ------------
+    value: :class:`str` or :py:class:`~pyasn1.type.univ.Null` object
         Python empty string literal or any object that evaluates to `False`
 
     tagSet: :py:class:`~pyasn1.type.tag.TagSet`
@@ -971,8 +971,8 @@ class ObjectIdentifier(base.AbstractSimpleAsn1Item):
 
     |ASN.1| objects are immutable and duck-type Python :class:`tuple` objects (tuple of non-negative integers).
 
-    Parameters
-    ----------
+    Keyword Args
+    ------------
     value: :class:`tuple`, :class:`str` or |ASN.1| object
         Python sequence of :class:`int` or string literal or |ASN.1| object.
 
@@ -1096,8 +1096,8 @@ class Real(base.AbstractSimpleAsn1Item):
     Additionally, |ASN.1| objects behave like a :class:`tuple` in which case its
     elements are mantissa, base and exponent.
 
-    Parameters
-    ----------
+    Keyword Args
+    ------------
     value: :class:`tuple`, :class:`float` or |ASN.1| object
         Python sequence of :class:`int` (representing mantissa, base and
         exponent) or float instance or *Real* class instance.
@@ -1401,8 +1401,8 @@ class SequenceOfAndSetOfBase(base.AbstractConstructedAsn1Item):
 
     |ASN.1| objects are mutable and duck-type Python :class:`list` objects.
 
-    Parameters
-    ----------
+    Keyword Args
+    ------------
     componentType : :py:class:`~pyasn1.type.base.PyAsn1Item` derivative
         A pyasn1 object representing ASN.1 type allowed within |ASN.1| type
 
@@ -1497,6 +1497,8 @@ class SequenceOfAndSetOfBase(base.AbstractConstructedAsn1Item):
             case a new component type gets instantiated and appended to the |ASN.1|
             sequence.
 
+        Keyword Args
+        ------------
         instantiate: :class:`bool`
             If `True` (default), inner component will be automatically instantiated.
             If 'False' either existing component or the `noValue` object will be
@@ -1564,6 +1566,8 @@ class SequenceOfAndSetOfBase(base.AbstractConstructedAsn1Item):
             type gets instantiated (if *componentType* is set, or given ASN.1
             object is taken otherwise) and appended to the |ASN.1| sequence.
 
+        Keyword Args
+        ------------
         value: :class:`object` or :py:class:`~pyasn1.type.base.PyAsn1Item` derivative
             A Python value to initialize |ASN.1| component with (if *componentType* is set)
             or ASN.1 value object to assign to |ASN.1| component.
@@ -1750,8 +1754,8 @@ class SequenceAndSetBase(base.AbstractConstructedAsn1Item):
 
     |ASN.1| objects are mutable and duck-type Python :class:`dict` objects.
 
-    Parameters
-    ----------
+    Keyword Args
+    ------------
     componentType: :py:class:`~pyasn1.type.namedtype.NamedType`
         Object holding named ASN.1 types allowed within this collection
 
@@ -1904,6 +1908,8 @@ class SequenceAndSetBase(base.AbstractConstructedAsn1Item):
         name: :class:`str`
             |ASN.1| type component name
 
+        Keyword Args
+        ------------
         instantiate: :class:`bool`
             If `True` (default), inner component will be automatically instantiated.
             If 'False' either existing component or the `noValue` object will be
@@ -1938,7 +1944,9 @@ class SequenceAndSetBase(base.AbstractConstructedAsn1Item):
         name: :class:`str`
             |ASN.1| type component name
 
-        value : :class:`object` or :py:class:`~pyasn1.type.base.PyAsn1Item` derivative
+        Keyword Args
+        ------------
+        value: :class:`object` or :py:class:`~pyasn1.type.base.PyAsn1Item` derivative
             A Python value to initialize |ASN.1| component with (if *componentType* is set)
             or ASN.1 value object to assign to |ASN.1| component.
 
@@ -1980,6 +1988,8 @@ class SequenceAndSetBase(base.AbstractConstructedAsn1Item):
             component or (if *componentType* is set) new ASN.1 schema object gets
             instantiated.
 
+        Keyword Args
+        ------------
         instantiate: :class:`bool`
             If `True` (default), inner component will be automatically instantiated.
             If 'False' either existing component or the `noValue` object will be
@@ -2050,7 +2060,9 @@ class SequenceAndSetBase(base.AbstractConstructedAsn1Item):
             otherwise. In the latter case a new component of given ASN.1
             type gets instantiated and appended to |ASN.1| sequence.
 
-        value : :class:`object` or :py:class:`~pyasn1.type.base.PyAsn1Item` derivative
+        Keyword Args
+        ------------
+        value: :class:`object` or :py:class:`~pyasn1.type.base.PyAsn1Item` derivative
             A Python value to initialize |ASN.1| component with (if *componentType* is set)
             or ASN.1 value object to assign to |ASN.1| component.
 
@@ -2294,6 +2306,8 @@ class Set(SequenceAndSetBase):
             Object representing ASN.1 tags to identify one of
             |ASN.1| object component
 
+        Keyword Args
+        ------------
         instantiate: :class:`bool`
             If `True` (default), inner component will be automatically instantiated.
             If 'False' either existing component or the `noValue` object will be
@@ -2327,7 +2341,9 @@ class Set(SequenceAndSetBase):
             Object representing ASN.1 tags to identify one of
             |ASN.1| object component
 
-        value : :class:`object` or :py:class:`~pyasn1.type.base.PyAsn1Item` derivative
+        Keyword Args
+        ------------
+        value: :class:`object` or :py:class:`~pyasn1.type.base.PyAsn1Item` derivative
             A Python value to initialize |ASN.1| component with (if *componentType* is set)
             or ASN.1 value object to assign to |ASN.1| component.
 
@@ -2509,6 +2525,8 @@ class Choice(Set):
             type gets instantiated (if *componentType* is set, or given ASN.1
             object is taken otherwise) and appended to the |ASN.1| sequence.
 
+        Keyword Args
+        ------------
         value: :class:`object` or :py:class:`~pyasn1.type.base.PyAsn1Item` derivative
             A Python value to initialize |ASN.1| component with (if *componentType* is set)
             or ASN.1 value object to assign to |ASN.1| component. Once a new value is
diff --git a/pyasn1/type/useful.py b/pyasn1/type/useful.py
index a05a9a6..7f7cd1e 100644
--- a/pyasn1/type/useful.py
+++ b/pyasn1/type/useful.py
@@ -127,7 +127,7 @@ class TimeMixIn(object):
 
         Parameters
         ----------
-        dt : :py:class:`datetime.datetime` object
+        dt: :py:class:`datetime.datetime` object
             The `datetime.datetime` object to initialize the |ASN.1| object from