added example code snippets to the docstrings (#101)

6 files changed, 394 insertions, 29 deletions

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.