From cf9b3f5f67501b85296c05456bbd324352177718 Mon Sep 17 00:00:00 2001
From: Ilya Etingof <etingof@gmail.com>
Date: Tue, 9 Jul 2019 00:18:00 +0200
Subject: Add more docs on `OpenType` (#166)

This change adds more explanations and examples on ASN.1 ANY
DEFINED BY syntax (OpenType).
---
 pyasn1/type/base.py     | 11 +++++------
 pyasn1/type/opentype.py | 45 +++++++++++++++++++++++++++++++++++++--------
 2 files changed, 42 insertions(+), 14 deletions(-)

(limited to 'pyasn1')

diff --git a/pyasn1/type/base.py b/pyasn1/type/base.py
index b231482..61ec35e 100644
--- a/pyasn1/type/base.py
+++ b/pyasn1/type/base.py
@@ -12,7 +12,8 @@ from pyasn1.type import constraint
 from pyasn1.type import tag
 from pyasn1.type import tagmap
 
-__all__ = ['Asn1Item', 'Asn1ItemBase', 'AbstractSimpleAsn1Item', 'AbstractConstructedAsn1Item']
+__all__ = ['Asn1Item', 'Asn1ItemBase', 'AbstractSimpleAsn1Item',
+           'AbstractConstructedAsn1Item']
 
 
 class Asn1Item(object):
@@ -535,8 +536,7 @@ class AbstractConstructedAsn1Item(Asn1ItemBase):
         Note
         ----
         Due to the mutable nature of the |ASN.1| object, even if no arguments
-        are supplied, new |ASN.1| object will always be created as a shallow
-        copy of `self`.
+        are supplied, a new |ASN.1| object will be created and returned.
         """
         cloneValueFlag = kwargs.pop('cloneValueFlag', False)
 
@@ -588,9 +588,8 @@ class AbstractConstructedAsn1Item(Asn1ItemBase):
 
         Note
         ----
-        Due to the immutable nature of the |ASN.1| object, if no arguments
-        are supplied, no new |ASN.1| object will be created and `self` will
-        be returned instead.
+        Due to the mutable nature of the |ASN.1| object, even if no arguments
+        are supplied, a new |ASN.1| object will be created and returned.
         """
 
         initializers = self.readOnly.copy()
diff --git a/pyasn1/type/opentype.py b/pyasn1/type/opentype.py
index d37a533..29645f0 100644
--- a/pyasn1/type/opentype.py
+++ b/pyasn1/type/opentype.py
@@ -11,11 +11,22 @@ __all__ = ['OpenType']
 class OpenType(object):
     """Create ASN.1 type map indexed by a value
 
-    The *DefinedBy* object models the ASN.1 *DEFINED BY* clause which maps
-    values to ASN.1 types in the context of the ASN.1 SEQUENCE/SET type.
-
-    OpenType objects are duck-type a read-only Python :class:`dict` objects,
-    however the passed `typeMap` is stored by reference.
+    The *OpenType* object models an untyped field of a constructed ASN.1
+    type. In ASN.1 syntax it is usually represented by the
+    `ANY DEFINED BY` for scalars or `SET OF ANY DEFINED BY`,
+    `SEQUENCE OF ANY DEFINED BY` for container types clauses. Typically
+    used together with :class:`~pyasn1.type.univ.Any` object.
+
+    OpenType objects duck-type a read-only Python :class:`dict` objects,
+    however the passed `typeMap` is not copied, but stored by reference.
+    That means the user can manipulate `typeMap` at run time having this
+    reflected on *OpenType* object behavior.
+
+    The |OpenType| class models an untyped field of a constructed ASN.1
+    type. In ASN.1 syntax it is usually represented by the
+    `ANY DEFINED BY` for scalars or `SET OF ANY DEFINED BY`,
+    `SEQUENCE OF ANY DEFINED BY` for container types clauses. Typically
+    used with :class:`~pyasn1.type.univ.Any` type.
 
     Parameters
     ----------
@@ -28,12 +39,14 @@ class OpenType(object):
 
     Examples
     --------
+
+    For untyped scalars:
+
     .. code-block:: python
 
         openType = OpenType(
-            'id',
-            {1: Integer(),
-             2: OctetString()}
+            'id', {1: Integer(),
+                   2: OctetString()}
         )
         Sequence(
             componentType=NamedTypes(
@@ -41,6 +54,22 @@ class OpenType(object):
                 NamedType('blob', Any(), openType=openType)
             )
         )
+
+    For untyped `SET OF` or `SEQUENCE OF` vectors:
+
+    .. code-block:: python
+
+        openType = OpenType(
+            'id', {1: Integer(),
+                   2: OctetString()}
+        )
+        Sequence(
+            componentType=NamedTypes(
+                NamedType('id', Integer()),
+                NamedType('blob', SetOf(componentType=Any()),
+                          openType=openType)
+            )
+        )
     """
 
     def __init__(self, name, typeMap=None):
-- 
cgit v1.2.3