added example code snippets to the docstrings (#101)

21 files changed, 599 insertions, 38 deletions

diff --git a/docs/source/pyasn1/type/namedtype/defaultednamedtype.rst b/docs/source/pyasn1/type/namedtype/defaultednamedtype.rst
index e617288..f203d08 100644
--- a/docs/source/pyasn1/type/namedtype/defaultednamedtype.rst
+++ b/docs/source/pyasn1/type/namedtype/defaultednamedtype.rst
@@ -3,7 +3,7 @@
 
 .. |NamedType| replace:: DefaultedNamedType
 
-|NamedType|
+DefaultedNamedType
 ------------------
 
 .. autoclass:: pyasn1.type.namedtype.DefaultedNamedType
@@ -11,4 +11,10 @@
 
    .. note::
 
-        The |NamedType| class models named field of a constructed ASN.1 type which has a default value.
+        The *DefaultedNamedType* class models named field of a constructed
+        ASN.1 type which has a default value.
+
+        The *DefaultedNamedType* objects are normally utilized
+        by the :ref:`NamedTypes <namedtype.NamedTypes>` objects
+        to model individual fields of the constructed ASN.1
+        types.
diff --git a/docs/source/pyasn1/type/namedtype/namedtype.rst b/docs/source/pyasn1/type/namedtype/namedtype.rst
index 2e6c270..7429ffa 100644
--- a/docs/source/pyasn1/type/namedtype/namedtype.rst
+++ b/docs/source/pyasn1/type/namedtype/namedtype.rst
@@ -3,12 +3,18 @@
 
 .. |NamedType| replace:: NamedType
 
-|NamedType|
------------
+NamedType
+---------
 
 .. autoclass:: pyasn1.type.namedtype.NamedType
    :members:
 
    .. note::
 
-        The |NamedType| class models a mandatory field of a constructed ASN.1 type.
+        The *NamedType* class models a mandatory field of a constructed
+        ASN.1 type.
+
+        The *NamedType* objects are normally utilized by the
+        the :ref:`NamedTypes <namedtype.NamedTypes>` objects
+        to model individual fields of the constructed ASN.1
+        types.
diff --git a/docs/source/pyasn1/type/namedtype/namedtypes.rst b/docs/source/pyasn1/type/namedtype/namedtypes.rst
index d6ca43a..2e2bb9d 100644
--- a/docs/source/pyasn1/type/namedtype/namedtypes.rst
+++ b/docs/source/pyasn1/type/namedtype/namedtypes.rst
@@ -6,3 +6,10 @@ NamedTypes
 
 .. autoclass:: pyasn1.type.namedtype.NamedTypes
    :members:
+
+   .. note::
+
+        The *NamedTypes* objects are normally utilized by the
+        constructed ASN.1 types (e.g. :ref:`Sequence <univ.Sequence>`,
+        :ref:`Set <univ.Set>` and :ref:`Choice <univ.Choice>`) to model
+        the set of fields of those types.
diff --git a/docs/source/pyasn1/type/namedtype/optionalnamedtype.rst b/docs/source/pyasn1/type/namedtype/optionalnamedtype.rst
index f78bec5..2095b05 100644
--- a/docs/source/pyasn1/type/namedtype/optionalnamedtype.rst
+++ b/docs/source/pyasn1/type/namedtype/optionalnamedtype.rst
@@ -3,12 +3,18 @@
 
 .. |NamedType| replace:: OptionalNamedType
 
-|NamedType|
-------------------
+OptionalNamedType
+-----------------
 
 .. autoclass:: pyasn1.type.namedtype.OptionalNamedType
    :members:
 
    .. note::
 
-        The |NamedType| class models an optional field of a constructed ASN.1 type.
+        The *OptionalNamedType* class models an optional field of
+        a constructed ASN.1 type.
+
+        The *OptionalNamedType* objects are normally utilized by
+        the :ref:`NamedTypes <namedtype.NamedTypes>` objects
+        to model individual fields of the constructed ASN.1
+        types.
diff --git a/docs/source/pyasn1/type/tag/tag.rst b/docs/source/pyasn1/type/tag/tag.rst
index 0536b61..3aeb670 100644
--- a/docs/source/pyasn1/type/tag/tag.rst
+++ b/docs/source/pyasn1/type/tag/tag.rst
@@ -5,6 +5,14 @@ Solitary tag
 ------------
 
 .. automodule:: pyasn1.type.tag
-   :members: Tag, tagClassUniversal, tagClassApplication, tagClassContext,
+   :members: tagClassUniversal, tagClassApplication, tagClassContext,
              tagClassPrivate, tagFormatSimple, tagFormatConstructed
 
+.. autoclass:: pyasn1.type.tag.Tag
+   :members:
+
+   .. note::
+
+       The *Tag* objects are normally used by the
+       :ref:`TagSet <tag.TagSet>`, objects to model a collection
+       of ASN.1 tags.
diff --git a/docs/source/pyasn1/type/tag/tagmap.rst b/docs/source/pyasn1/type/tag/tagmap.rst
index a3222e3..05b8404 100644
--- a/docs/source/pyasn1/type/tag/tagmap.rst
+++ b/docs/source/pyasn1/type/tag/tagmap.rst
@@ -6,3 +6,9 @@ Tag->type map
 
 .. autoclass:: pyasn1.type.tagmap.TagMap
    :members:
+
+   .. note::
+
+       The *TagMap* objects are used by the
+       :ref:`TagSet <tag.TagSet>`, objects for looking up components
+       of constructed ASN.1 types by :ref:`Tag <tag.Tag>`.
diff --git a/docs/source/pyasn1/type/tag/tagset.rst b/docs/source/pyasn1/type/tag/tagset.rst
index 566238a..c4dce2e 100644
--- a/docs/source/pyasn1/type/tag/tagset.rst
+++ b/docs/source/pyasn1/type/tag/tagset.rst
@@ -6,3 +6,9 @@ Tag set
 
 .. autoclass:: pyasn1.type.tag.TagSet
    :members:
+
+   .. note::
+
+       The *TagSet* objects are normally used by all ASN.1 type
+       objects both simple (like :ref:`Integer <univ.Integer>`)
+       and constructed (e.g. :ref:`Sequence <univ.Sequence>`).
diff --git a/pyasn1/codec/ber/decoder.py b/pyasn1/codec/ber/decoder.py
index 725eaa3..3737742 100644
--- a/pyasn1/codec/ber/decoder.py
+++ b/pyasn1/codec/ber/decoder.py
@@ -1355,6 +1355,28 @@ class Decoder(object):
 #: ------
 #: :py:class:`~pyasn1.error.PyAsn1Error`
 #:     On decoding errors
+#:
+#: Examples
+#: --------
+#: Decode BER serialisation without ASN.1 schema
+#:
+#: .. code-block:: pycon
+#:
+#:    >>> s, _ = decode(b'0\t\x02\x01\x01\x02\x01\x02\x02\x01\x03')
+#:    >>> print(s.prettyPrint())
+#:    SequenceOf:
+#:     1 2 3
+#:
+#: Decode BER serialisation with ASN.1 schema
+#:
+#: .. code-block:: pycon
+#:
+#:    >>> seq = SequenceOf(componentType=Integer())
+#:    >>> s, _ = decode(b'0\t\x02\x01\x01\x02\x01\x02\x02\x01\x03', asn1Spec=seq)
+#:    >>> print(s.prettyPrint())
+#:    SequenceOf:
+#:     1 2 3
+#:
 decode = Decoder(tagMap, typeMap)
 
 # XXX
diff --git a/pyasn1/codec/ber/encoder.py b/pyasn1/codec/ber/encoder.py
index c8eac34..a915f52 100644
--- a/pyasn1/codec/ber/encoder.py
+++ b/pyasn1/codec/ber/encoder.py
@@ -666,4 +666,24 @@ class Encoder(object):
 #: ------
 #: :py:class:`~pyasn1.error.PyAsn1Error`
 #:     On encoding errors
+#:
+#: Examples
+#: --------
+#: Encode Python value into BER with ASN.1 schema
+#:
+#: .. code-block:: pycon
+#:
+#:    >>> seq = SequenceOf(componentType=Integer())
+#:    >>> encode([1, 2, 3], asn1Spec=seq)
+#:    b'0\t\x02\x01\x01\x02\x01\x02\x02\x01\x03'
+#:
+#: Encode ASN.1 value object into BER
+#:
+#: .. code-block:: pycon
+#:
+#:    >>> seq = SequenceOf(componentType=Integer())
+#:    >>> seq.extend([1, 2, 3])
+#:    >>> encode(seq)
+#:    b'0\t\x02\x01\x01\x02\x01\x02\x02\x01\x03'
+#:
 encode = Encoder(tagMap, typeMap)
diff --git a/pyasn1/codec/cer/decoder.py b/pyasn1/codec/cer/decoder.py
index 3cc29c7..2a9d94f 100644
--- a/pyasn1/codec/cer/decoder.py
+++ b/pyasn1/codec/cer/decoder.py
@@ -89,4 +89,26 @@ class Decoder(decoder.Decoder):
 #: ------
 #: :py:class:`~pyasn1.error.PyAsn1Error`
 #:     On decoding errors
+#:
+#: Examples
+#: --------
+#: Decode CER serialisation without ASN.1 schema
+#:
+#: .. code-block:: pycon
+#:
+#:    >>> s, _ = decode(b'0\x80\x02\x01\x01\x02\x01\x02\x02\x01\x03\x00\x00')
+#:    >>> print(s.prettyPrint())
+#:    SequenceOf:
+#:     1 2 3
+#:
+#: Decode CER serialisation with ASN.1 schema
+#:
+#: .. code-block:: pycon
+#:
+#:    >>> seq = SequenceOf(componentType=Integer())
+#:    >>> s, _ = decode(b'0\x80\x02\x01\x01\x02\x01\x02\x02\x01\x03\x00\x00', asn1Spec=seq)
+#:    >>> print(s.prettyPrint())
+#:    SequenceOf:
+#:     1 2 3
+#:
 decode = Decoder(tagMap, decoder.typeMap)
diff --git a/pyasn1/codec/cer/encoder.py b/pyasn1/codec/cer/encoder.py
index b4c68ec..80cdc35 100644
--- a/pyasn1/codec/cer/encoder.py
+++ b/pyasn1/codec/cer/encoder.py
@@ -271,6 +271,26 @@ class Encoder(encoder.Encoder):
 #: ------
 #: :py:class:`~pyasn1.error.PyAsn1Error`
 #:     On encoding errors
+#:
+#: Examples
+#: --------
+#: Encode Python value into CER with ASN.1 schema
+#:
+#: .. code-block:: pycon
+#:
+#:    >>> seq = SequenceOf(componentType=Integer())
+#:    >>> encode([1, 2, 3], asn1Spec=seq)
+#:    b'0\x80\x02\x01\x01\x02\x01\x02\x02\x01\x03\x00\x00'
+#:
+#: Encode ASN.1 value object into CER
+#:
+#: .. code-block:: pycon
+#:
+#:    >>> seq = SequenceOf(componentType=Integer())
+#:    >>> seq.extend([1, 2, 3])
+#:    >>> encode(seq)
+#:    b'0\x80\x02\x01\x01\x02\x01\x02\x02\x01\x03\x00\x00'
+#:
 encode = Encoder(tagMap, typeMap)
 
 # EncoderFactory queries class instance and builds a map of tags -> encoders
diff --git a/pyasn1/codec/der/decoder.py b/pyasn1/codec/der/decoder.py
index 1da37a0..e7956a4 100644
--- a/pyasn1/codec/der/decoder.py
+++ b/pyasn1/codec/der/decoder.py
@@ -69,4 +69,26 @@ class Decoder(decoder.Decoder):
 #: ------
 #: :py:class:`~pyasn1.error.PyAsn1Error`
 #:     On decoding errors
+#:
+#: Examples
+#: --------
+#: Decode DER serialisation without ASN.1 schema
+#:
+#: .. code-block:: pycon
+#:
+#:    >>> s, _ = decode(b'0\t\x02\x01\x01\x02\x01\x02\x02\x01\x03')
+#:    >>> print(s.prettyPrint())
+#:    SequenceOf:
+#:     1 2 3
+#:
+#: Decode DER serialisation with ASN.1 schema
+#:
+#: .. code-block:: pycon
+#:
+#:    >>> seq = SequenceOf(componentType=Integer())
+#:    >>> s, _ = decode(b'0\t\x02\x01\x01\x02\x01\x02\x02\x01\x03', asn1Spec=seq)
+#:    >>> print(s.prettyPrint())
+#:    SequenceOf:
+#:     1 2 3
+#:
 decode = Decoder(tagMap, typeMap)
diff --git a/pyasn1/codec/der/encoder.py b/pyasn1/codec/der/encoder.py
index 8496252..5d6c6c0 100644
--- a/pyasn1/codec/der/encoder.py
+++ b/pyasn1/codec/der/encoder.py
@@ -84,4 +84,24 @@ class Encoder(encoder.Encoder):
 #: ------
 #: :py:class:`~pyasn1.error.PyAsn1Error`
 #:     On encoding errors
+#:
+#: Examples
+#: --------
+#: Encode Python value into DER with ASN.1 schema
+#:
+#: .. code-block:: pycon
+#:
+#:    >>> seq = SequenceOf(componentType=Integer())
+#:    >>> encode([1, 2, 3], asn1Spec=seq)
+#:    b'0\t\x02\x01\x01\x02\x01\x02\x02\x01\x03'
+#:
+#: Encode ASN.1 value object into DER
+#:
+#: .. code-block:: pycon
+#:
+#:    >>> seq = SequenceOf(componentType=Integer())
+#:    >>> seq.extend([1, 2, 3])
+#:    >>> encode(seq)
+#:    b'0\t\x02\x01\x01\x02\x01\x02\x02\x01\x03'
+#:
 encode = Encoder(tagMap, typeMap)
diff --git a/pyasn1/codec/native/decoder.py b/pyasn1/codec/native/decoder.py
index cd60649..55ccc3c 100644
--- a/pyasn1/codec/native/decoder.py
+++ b/pyasn1/codec/native/decoder.py
@@ -193,4 +193,17 @@ class Decoder(object):
 #: ------
 #: :py:class:`~pyasn1.error.PyAsn1Error`
 #:     On decoding errors
+#:
+#: Examples
+#: --------
+#: Decode native Python object into ASN.1 objects with ASN.1 schema
+#:
+#: .. code-block:: pycon
+#:
+#:    >>> seq = SequenceOf(componentType=Integer())
+#:    >>> s, _ = decode([1, 2, 3], asn1Spec=seq)
+#:    >>> print(s.prettyPrint())
+#:    SequenceOf:
+#:     1 2 3
+#:
 decode = Decoder(tagMap, typeMap)
diff --git a/pyasn1/codec/native/encoder.py b/pyasn1/codec/native/encoder.py
index 53d16fc..e99e1df 100644
--- a/pyasn1/codec/native/encoder.py
+++ b/pyasn1/codec/native/encoder.py
@@ -209,4 +209,16 @@ class Encoder(object):
 #: ------
 #: :py:class:`~pyasn1.error.PyAsn1Error`
 #:     On encoding errors
+#:
+#: Examples
+#: --------
+#: Encode ASN.1 value object into native Python types
+#:
+#: .. code-block:: pycon
+#:
+#:    >>> seq = SequenceOf(componentType=Integer())
+#:    >>> seq.extend([1, 2, 3])
+#:    >>> encode(seq)
+#:    [1, 2, 3]
+#:
 encode = Encoder(tagMap, typeMap)
diff --git a/pyasn1/type/base.py b/pyasn1/type/base.py
index a20eff4..45b27e3 100644
--- a/pyasn1/type/base.py
+++ b/pyasn1/type/base.py
@@ -354,8 +354,8 @@ class AbstractSimpleAsn1Item(Asn1ItemBase):
         The following arguments to `subtype()` create a ASN.1 subtype out of
         |ASN.1| type:
 
-        Parameters
-        ----------
+        Other Parameters
+        ----------------
         implicitTag: :py:class:`~pyasn1.type.tag.Tag`
             Implicitly apply given ASN.1 tag object to `self`'s
             :py:class:`~pyasn1.type.tag.TagSet`, then use the result as
@@ -559,8 +559,8 @@ class AbstractConstructedAsn1Item(Asn1ItemBase):
         The following arguments to `subtype()` create a ASN.1 subtype out of
         |ASN.1| type.
 
-        Parameters
-        ----------
+        Other Parameters
+        ----------------
         implicitTag: :py:class:`~pyasn1.type.tag.Tag`
             Implicitly apply given ASN.1 tag object to `self`'s
             :py:class:`~pyasn1.type.tag.TagSet`, then use the result as
diff --git a/pyasn1/type/constraint.py b/pyasn1/type/constraint.py
index c4f4238..7299ccd 100644
--- a/pyasn1/type/constraint.py
+++ b/pyasn1/type/constraint.py
@@ -105,8 +105,8 @@ class SingleValueConstraint(AbstractConstraint):
     \*values: :class:`int`
         Full set of values permitted by this constraint object.
 
-    Example
-    -------
+    Examples
+    --------
     .. code-block:: python
 
         class DivisorOfSix(Integer):
@@ -148,8 +148,8 @@ class ContainedSubtypeConstraint(AbstractConstraint):
         Full set of values and constraint objects permitted
         by this constraint object.
 
-    Example
-    -------
+    Examples
+    --------
     .. code-block:: python
 
         class DivisorOfEighteen(Integer):
@@ -194,8 +194,8 @@ class ValueRangeConstraint(AbstractConstraint):
     end: :class:`int`
         Maximum permitted value in the range (inclusive)
 
-    Example
-    -------
+    Examples
+    --------
     .. code-block:: python
 
         class TeenAgeYears(Integer):
@@ -254,8 +254,8 @@ class ValueSizeConstraint(ValueRangeConstraint):
     maximum: :class:`int`
         Maximum permitted size of the value (inclusive)
 
-    Example
-    -------
+    Examples
+    --------
     .. code-block:: python
 
         class BaseballTeamRoster(SetOf):
@@ -308,8 +308,8 @@ class PermittedAlphabetConstraint(SingleValueConstraint):
     \*alphabet: :class:`str`
         Full set of characters permitted by this constraint object.
 
-    Example
-    -------
+    Examples
+    --------
     .. code-block:: python
 
         class BooleanValue(IA5String):
@@ -378,8 +378,8 @@ class ConstraintsExclusion(AbstractConstraint):
     constraint:
         Constraint or logic operator object.
 
-    Example
-    -------
+    Examples
+    --------
     .. code-block:: python
 
         class Lipogramme(IA5STRING):
@@ -465,8 +465,8 @@ class ConstraintsIntersection(AbstractConstraintSet):
     \*constraints:
         Constraint or logic operator objects.
 
-    Example
-    -------
+    Examples
+    --------
     .. code-block:: python
 
         class CapitalAndSmall(IA5String):
@@ -509,8 +509,8 @@ class ConstraintsUnion(AbstractConstraintSet):
     \*constraints:
         Constraint or logic operator objects.
 
-    Example
-    -------
+    Examples
+    --------
     .. code-block:: python
 
         class CapitalOrSmall(IA5String):
diff --git a/pyasn1/type/namedtype.py b/pyasn1/type/namedtype.py
index 256ba56..bf650c8 100644
--- a/pyasn1/type/namedtype.py
+++ b/pyasn1/type/namedtype.py
@@ -116,6 +116,31 @@ class NamedTypes(object):
     Parameters
     ----------
     *namedTypes: :class:`~pyasn1.type.namedtype.NamedType`
+
+    Examples
+    --------
+
+    .. code-block:: python
+
+        class Description(Sequence):
+            '''
+            ASN.1 specification:
+
+            Description ::= SEQUENCE {
+                surname    IA5String,
+                first-name IA5String OPTIONAL,
+                age        INTEGER DEFAULT 40
+            }
+            '''
+            componentType = NamedTypes(
+                NamedType('surname', IA5String()),
+                OptionalNamedType('first-name', IA5String()),
+                DefaultedNamedType('age', Integer(40))
+            )
+
+        descr = Description()
+        descr['surname'] = 'Smith'
+        descr['first-name'] = 'John'
     """
     def __init__(self, *namedTypes, **kwargs):
         self.__namedTypes = namedTypes
@@ -466,7 +491,6 @@ class NamedTypes(object):
 
         Example
         -------
-
         .. code-block:: python
 
            OuterType ::= CHOICE {
@@ -491,7 +515,6 @@ class NamedTypes(object):
 
         Example
         -------
-
         .. code-block:: python
 
            OuterType ::= CHOICE {
diff --git a/pyasn1/type/opentype.py b/pyasn1/type/opentype.py
index 2f692d5..ae27ffe 100644
--- a/pyasn1/type/opentype.py
+++ b/pyasn1/type/opentype.py
@@ -22,13 +22,12 @@ class OpenType(object):
     name: :py:class:`str`
         Field name
 
-    typeMap: :py:class:`dict`:
+    typeMap: :py:class:`dict`
         A map of value->ASN.1 type. It's stored by reference and can be
         mutated later to register new mappings.
 
     Examples
     --------
-
     .. code-block:: python
 
         openType = OpenType(
diff --git a/pyasn1/type/tag.py b/pyasn1/type/tag.py
index 6c0e2c1..44d6c4e 100644
--- a/pyasn1/type/tag.py
+++ b/pyasn1/type/tag.py
@@ -168,6 +168,23 @@ class TagSet(object):
 
     *superTags: :class:`~pyasn1.type.tag.Tag`
         Additional *Tag* objects taking part in subtyping.
+
+    Examples
+    --------
+    .. code-block:: python
+
+        class OrderNumber(NumericString):
+            '''
+            ASN.1 specification
+
+            Order-number ::=
+                [APPLICATION 5] IMPLICIT NumericString
+            '''
+            tagSet = NumericString.tagSet.tagImplicitly(
+                Tag(tagClassApplication, tagFormatSimple, 5)
+            )
+
+        orderNumber = OrderNumber('1234')
     """
     def __init__(self, baseTag=(), *superTags):
         self.__baseTag = baseTag
diff --git a/pyasn1/type/univ.py b/pyasn1/type/univ.py
index 9d16b05..1ff079b 100644
--- a/pyasn1/type/univ.py
+++ b/pyasn1/type/univ.py
@@ -45,6 +45,28 @@ class Integer(base.AbstractSimpleAsn1Item):
     ------
     :py:class:`~pyasn1.error.PyAsn1Error`
         On constraint violation or bad initializer.
+
+    Examples
+    --------
+
+    .. code-block:: python
+
+        class ErrorCode(Integer):
+            '''
+            ASN.1 specification:
+
+            ErrorCode ::=
+                INTEGER { disk-full(1), no-disk(-1),
+                          disk-not-formatted(2) }
+
+            error ErrorCode ::= disk-full
+            '''
+            namedValues = NamedValues(
+                ('disk-full', 1), ('no-disk', -1),
+                ('disk-not-formatted', 2)
+            )
+
+        error = ErrorCode('disk-full')
     """
     #: Set (on class, not on instance) or return a
     #: :py:class:`~pyasn1.type.tag.TagSet` object representing ASN.1 tag(s)
@@ -251,8 +273,45 @@ class Integer(base.AbstractSimpleAsn1Item):
 
 
 class Boolean(Integer):
-    __doc__ = Integer.__doc__
+    """Create |ASN.1| type or object.
+
+    |ASN.1| objects are immutable and duck-type Python :class:`int` objects.
+
+    Keyword Args
+    ------------
+    value: :class:`int`, :class:`str` or |ASN.1| object
+        Python integer or boolean or string literal or |ASN.1| class instance.
+
+    tagSet: :py:class:`~pyasn1.type.tag.TagSet`
+        Object representing non-default ASN.1 tag(s)
+
+    subtypeSpec: :py:class:`~pyasn1.type.constraint.ConstraintsIntersection`
+        Object representing non-default ASN.1 subtype constraint(s)
+
+    namedValues: :py:class:`~pyasn1.type.namedval.NamedValues`
+        Object representing non-default symbolic aliases for numbers
+
+    Raises
+    ------
+    :py:class:`~pyasn1.error.PyAsn1Error`
+        On constraint violation or bad initializer.
+
+    Examples
+    --------
+    .. code-block:: python
+
+        class RoundResult(Boolean):
+            '''
+            ASN.1 specification:
 
+            RoundResult ::= BOOLEAN
+
+            ok RoundResult ::= TRUE
+            ko RoundResult ::= FALSE
+            '''
+        ok = RoundResult(True)
+        ko = RoundResult(False)
+    """
     #: Set (on class, not on instance) or return a
     #: :py:class:`~pyasn1.type.tag.TagSet` object representing ASN.1 tag(s)
     #: associated with |ASN.1| type.
@@ -326,6 +385,32 @@ class BitString(base.AbstractSimpleAsn1Item):
     ------
     :py:class:`~pyasn1.error.PyAsn1Error`
         On constraint violation or bad initializer.
+
+    Examples
+    --------
+    .. code-block:: python
+
+        class Rights(BitString):
+            '''
+            ASN.1 specification:
+
+            Rights ::= BIT STRING { user-read(0), user-write(1),
+                                    group-read(2), group-write(3),
+                                    other-read(4), other-write(5) }
+
+            group1 Rights ::= { group-read, group-write }
+            group2 Rights ::= '0011'B
+            group3 Rights ::= '3'H
+            '''
+            namedValues = NamedValues(
+                ('user-read', 0), ('user-write', 1),
+                ('group-read', 2), ('group-write', 3),
+                ('other-read', 4), ('other-write', 5)
+            )
+
+        group1 = Rights(('group-read', 'group-write'))
+        group2 = Rights('0011')
+        group3 = Rights(0x3)
     """
     #: Set (on class, not on instance) or return a
     #: :py:class:`~pyasn1.type.tag.TagSet` object representing ASN.1 tag(s)
@@ -671,6 +756,22 @@ class OctetString(base.AbstractSimpleAsn1Item):
     ------
     :py:class:`~pyasn1.error.PyAsn1Error`
         On constraint violation or bad initializer.
+
+    Examples
+    --------
+    .. code-block:: python
+
+        class Icon(OctetString):
+            '''
+            ASN.1 specification:
+
+            Icon ::= OCTET STRING
+
+            icon1 Icon ::= '001100010011001000110011'B
+            icon2 Icon ::= '313233'H
+            '''
+        icon1 = Icon.fromBinaryString('001100010011001000110011')
+        icon2 = Icon.fromHexString('313233')
     """
     #: Set (on class, not on instance) or return a
     #: :py:class:`~pyasn1.type.tag.TagSet` object representing ASN.1 tag(s)
@@ -940,6 +1041,18 @@ class Null(OctetString):
     ------
     :py:class:`~pyasn1.error.PyAsn1Error`
         On constraint violation or bad initializer.
+
+    Examples
+    --------
+    .. code-block:: python
+
+        class Ack(Null):
+            '''
+            ASN.1 specification:
+
+            Ack ::= NULL
+            '''
+        ack = Ack('')
     """
 
     #: Set (on class, not on instance) or return a
@@ -987,6 +1100,22 @@ class ObjectIdentifier(base.AbstractSimpleAsn1Item):
     ------
     :py:class:`~pyasn1.error.PyAsn1Error`
         On constraint violation or bad initializer.
+
+    Examples
+    --------
+    .. code-block:: python
+
+        class ID(ObjectIdentifier):
+            '''
+            ASN.1 specification:
+
+            ID ::= OBJECT IDENTIFIER
+
+            id-edims ID ::= { joint-iso-itu-t mhs-motif(6) edims(7) }
+            id-bp ID ::= { id-edims 11 }
+            '''
+        id_edims = ID('2.6.7')
+        id_bp = id_edims + (11,)
     """
     #: Set (on class, not on instance) or return a
     #: :py:class:`~pyasn1.type.tag.TagSet` object representing ASN.1 tag(s)
@@ -1114,6 +1243,20 @@ class Real(base.AbstractSimpleAsn1Item):
     :py:class:`~pyasn1.error.PyAsn1Error`
         On constraint violation or bad initializer.
 
+    Examples
+    --------
+    .. code-block:: python
+
+        class Pi(Real):
+            '''
+            ASN.1 specification:
+
+            Pi ::= REAL
+
+            pi Pi ::= { mantissa 314159, base 10, exponent -5 }
+
+            '''
+        pi = Pi((314159, 10, -5))
     """
     binEncBase = None  # binEncBase = 16 is recommended for large numbers
 
@@ -1373,8 +1516,50 @@ class Real(base.AbstractSimpleAsn1Item):
 
 
 class Enumerated(Integer):
-    __doc__ = Integer.__doc__
+    """Create |ASN.1| type or object.
+
+    |ASN.1| objects are immutable and duck-type Python :class:`int` objects.
+
+    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`
+        Object representing non-default ASN.1 tag(s)
+
+    subtypeSpec: :py:class:`~pyasn1.type.constraint.ConstraintsIntersection`
+        Object representing non-default ASN.1 subtype constraint(s)
+
+    namedValues: :py:class:`~pyasn1.type.namedval.NamedValues`
+        Object representing non-default symbolic aliases for numbers
+
+    Raises
+    ------
+    :py:class:`~pyasn1.error.PyAsn1Error`
+        On constraint violation or bad initializer.
 
+    Examples
+    --------
+
+    .. code-block:: python
+
+        class RadioButton(Enumerated):
+            '''
+            ASN.1 specification:
+
+            RadioButton ::= ENUMERATED { button1(0), button2(1),
+                                         button3(2) }
+
+            selected-by-default RadioButton ::= button1
+            '''
+            namedValues = NamedValues(
+                ('button1', 0), ('button2', 1),
+                ('button3', 2)
+            )
+
+        selected_by_default = RadioButton('button1')
+    """
     #: Set (on class, not on instance) or return a
     #: :py:class:`~pyasn1.type.tag.TagSet` object representing ASN.1 tag(s)
     #: associated with |ASN.1| type.
@@ -1415,8 +1600,23 @@ class SequenceOfAndSetOfBase(base.AbstractConstructedAsn1Item):
 
     sizeSpec: :py:class:`~pyasn1.type.constraint.ConstraintsIntersection`
         Object representing collection size constraint
-     """
 
+    Examples
+    --------
+
+    .. code-block:: python
+
+        class LotteryDraw(SequenceOf):  #  SetOf is similar
+            '''
+            ASN.1 specification:
+
+            LotteryDraw ::= SEQUENCE OF INTEGER
+            '''
+            componentType = Integer()
+
+        lotteryDraw = LotteryDraw()
+        lotteryDraw.extend([123, 456, 789])
+    """
     def __init__(self, *args, **kwargs):
         # support positional params for backward compatibility
         if args:
@@ -1768,6 +1968,31 @@ class SequenceAndSetBase(base.AbstractConstructedAsn1Item):
 
     sizeSpec: :py:class:`~pyasn1.type.constraint.ConstraintsIntersection`
         Object representing collection size constraint
+
+    Examples
+    --------
+
+    .. code-block:: python
+
+        class Description(Sequence):  #  Set is similar
+            '''
+            ASN.1 specification:
+
+            Description ::= SEQUENCE {
+                surname    IA5String,
+                first-name IA5String OPTIONAL,
+                age        INTEGER DEFAULT 40
+            }
+            '''
+            componentType = NamedTypes(
+                NamedType('surname', IA5String()),
+                OptionalNamedType('first-name', IA5String()),
+                DefaultedNamedType('age', Integer(40))
+            )
+
+        descr = Description()
+        descr['surname'] = 'Smith'
+        descr['first-name'] = 'John'
     """
     #: Default :py:class:`~pyasn1.type.namedtype.NamedTypes`
     #: object representing named ASN.1 types allowed within |ASN.1| type
@@ -2390,8 +2615,50 @@ class Set(SequenceAndSetBase):
 
 
 class Choice(Set):
-    __doc__ = Set.__doc__
+    """Create |ASN.1| type.
+
+    |ASN.1| objects are mutable and duck-type Python :class:`dict` objects.
 
+    Keyword Args
+    ------------
+    componentType: :py:class:`~pyasn1.type.namedtype.NamedType`
+        Object holding named ASN.1 types allowed within this collection
+
+    tagSet: :py:class:`~pyasn1.type.tag.TagSet`
+        Object representing non-default ASN.1 tag(s)
+
+    subtypeSpec: :py:class:`~pyasn1.type.constraint.ConstraintsIntersection`
+        Object representing non-default ASN.1 subtype constraint(s)
+
+    sizeSpec: :py:class:`~pyasn1.type.constraint.ConstraintsIntersection`
+        Object representing collection size constraint
+
+    Examples
+    --------
+
+    .. code-block:: python
+
+        class Afters(Choice):
+            '''
+            ASN.1 specification:
+
+            Afters ::= CHOICE {
+                cheese  [0] IA5String,
+                dessert [1] IA5String
+            }
+            '''
+            componentType = NamedTypes(
+                NamedType('cheese', IA5String().subtype(
+                    implicitTag=Tag(tagClassContext, tagFormatSimple, 0)
+                ),
+                NamedType('dessert', IA5String().subtype(
+                    implicitTag=Tag(tagClassContext, tagFormatSimple, 1)
+                )
+            )
+
+        afters = Afters()
+        afters['cheese'] = 'Mascarpone'
+    """
     #: Set (on class, not on instance) or return a
     #: :py:class:`~pyasn1.type.tag.TagSet` object representing ASN.1 tag(s)
     #: associated with |ASN.1| type.
@@ -2649,8 +2916,67 @@ class Choice(Set):
 
 
 class Any(OctetString):
-    __doc__ = OctetString.__doc__
+    """Create |ASN.1| schema or value object.
+
+    |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.
+
+    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.
+
+    tagSet: :py:class:`~pyasn1.type.tag.TagSet`
+        Object representing non-default ASN.1 tag(s)
+
+    subtypeSpec: :py:class:`~pyasn1.type.constraint.ConstraintsIntersection`
+        Object representing non-default ASN.1 subtype constraint(s)
+
+    encoding: :py:class:`str`
+        Unicode codec ID to encode/decode :class:`unicode` (Python 2) or
+        :class:`str` (Python 3) the payload when |ASN.1| object is used
+        in text string context.
+
+    binValue: :py:class:`str`
+        Binary string initializer to use instead of the *value*.
+        Example: '10110011'.
+
+    hexValue: :py:class:`str`
+        Hexadecimal string initializer to use instead of the *value*.
+        Example: 'DEADBEEF'.
 
+    Raises
+    ------
+    :py:class:`~pyasn1.error.PyAsn1Error`
+        On constraint violation or bad initializer.
+
+    Examples
+    --------
+    .. code-block:: python
+
+        class Error(Sequence):
+            '''
+            ASN.1 specification:
+
+            Error ::= SEQUENCE {
+                code      INTEGER,
+                parameter ANY DEFINED BY code  -- Either INTEGER or REAL
+            }
+            '''
+            componentType=NamedTypes(
+                NamedType('code', Integer()),
+                NamedType('parameter', Any(),
+                          openType=OpenType('code', {1: Integer(),
+                                                     2: Real()}))
+            )
+
+        error = Error()
+        error['code'] = 1
+        error['parameter'] = Integer(1234)
+    """
     #: Set (on class, not on instance) or return a
     #: :py:class:`~pyasn1.type.tag.TagSet` object representing ASN.1 tag(s)
     #: associated with |ASN.1| type.