Add docstring for `.reset()` and `.clear()` methods

5 files changed, 31 insertions, 4 deletions

diff --git a/docs/source/pyasn1/type/univ/sequence.rst b/docs/source/pyasn1/type/univ/sequence.rst
index f48f497..0988004 100644
--- a/docs/source/pyasn1/type/univ/sequence.rst
+++ b/docs/source/pyasn1/type/univ/sequence.rst
@@ -8,7 +8,8 @@
 
 .. autoclass:: pyasn1.type.univ.Sequence(componentType=NamedTypes(), tagSet=tagSet(), subtypeSpec=ConstraintsIntersection(), sizeSpec=ConstraintsIntersection())
    :members: isValue, isSameTypeWith, isSuperTypeOf, tagSet, effectiveTagSet, tagMap, componentType, subtypeSpec, sizeSpec, getComponentByPosition,
-             setComponentByPosition, getComponentByName, setComponentByName, setDefaultComponents
+             setComponentByPosition, getComponentByName, setComponentByName, setDefaultComponents,
+             clear, reset
 
    .. note::
 
diff --git a/docs/source/pyasn1/type/univ/sequenceof.rst b/docs/source/pyasn1/type/univ/sequenceof.rst
index ed6a781..6a09b92 100644
--- a/docs/source/pyasn1/type/univ/sequenceof.rst
+++ b/docs/source/pyasn1/type/univ/sequenceof.rst
@@ -8,7 +8,7 @@
 
 .. autoclass:: pyasn1.type.univ.SequenceOf(componentType=NoValue(), tagSet=TagSet(), subtypeSpec=ConstraintsIntersection(), sizeSpec=ConstraintsIntersection())
    :members: isValue, isSameTypeWith, isSuperTypeOf, tagSet, effectiveTagSet, tagMap, componentType, subtypeSpec, sizeSpec,
-             getComponentByPosition, setComponentByPosition
+             getComponentByPosition, setComponentByPosition, clear, reset
 
    .. note::
 
diff --git a/docs/source/pyasn1/type/univ/set.rst b/docs/source/pyasn1/type/univ/set.rst
index 229525a..792d2e9 100644
--- a/docs/source/pyasn1/type/univ/set.rst
+++ b/docs/source/pyasn1/type/univ/set.rst
@@ -9,7 +9,7 @@
 .. autoclass:: pyasn1.type.univ.Set(componentType=NamedTypes(), tagSet=TagSet(), subtypeSpec=ConstraintsIntersection(), sizeSpec=ConstraintsIntersection())
    :members: isValue, isSameTypeWith, isSuperTypeOf, tagSet, effectiveTagSet, tagMap, componentType, subtypeSpec, sizeSpec,
              getComponentByPosition, setComponentByPosition, getComponentByName, setComponentByName, setDefaultComponents,
-             getComponentByType, setComponentByType
+             getComponentByType, setComponentByType, clear, reset
 
    .. note::
 
diff --git a/docs/source/pyasn1/type/univ/setof.rst b/docs/source/pyasn1/type/univ/setof.rst
index 2745677..67ef92f 100644
--- a/docs/source/pyasn1/type/univ/setof.rst
+++ b/docs/source/pyasn1/type/univ/setof.rst
@@ -8,7 +8,7 @@
 
 .. autoclass:: pyasn1.type.univ.SetOf(componentType=NoValue(), tagSet=TagSet(), subtypeSpec=ConstraintsIntersection(), sizeSpec=ConstraintsIntersection())
    :members: isValue, isSameTypeWith, isSuperTypeOf, tagSet, effectiveTagSet, tagMap, componentType, subtypeSpec, sizeSpec,
-             getComponentByPosition, setComponentByPosition
+             getComponentByPosition, setComponentByPosition, clear, reset
 
    .. note::
 
diff --git a/pyasn1/type/univ.py b/pyasn1/type/univ.py
index 0ba59a7..93114d6 100644
--- a/pyasn1/type/univ.py
+++ b/pyasn1/type/univ.py
@@ -1922,10 +1922,20 @@ class SequenceOfAndSetOfBase(base.AbstractConstructedAsn1Item):
                 for idx in sorted(self._componentValues)]
 
     def clear(self):
+        """Remove all components and become an empty |ASN.1| value object.
+
+        Has the same effect on |ASN.1| object as it does on :class:`list`
+        built-in.
+        """
         self._componentValues = {}
         return self
 
     def reset(self):
+        """Remove all components and become a |ASN.1| schema object.
+
+        See :meth:`isValue` property for more information on the
+        distinction between value and schema objects.
+        """
         self._componentValues = noValue
         return self
 
@@ -2217,11 +2227,21 @@ class SequenceAndSetBase(base.AbstractConstructedAsn1Item):
             self[k] = mappingValue[k]
 
     def clear(self):
+        """Remove all components and become an empty |ASN.1| value object.
+
+        Has the same effect on |ASN.1| object as it does on :class:`dict`
+        built-in.
+        """
         self._componentValues = []
         self._dynamicNames = self.DynamicNames()
         return self
 
     def reset(self):
+        """Remove all components and become a |ASN.1| schema object.
+
+        See :meth:`isValue` property for more information on the
+        distinction between value and schema objects.
+        """
         self._componentValues = noValue
         self._dynamicNames = self.DynamicNames()
         return self
@@ -2556,6 +2576,12 @@ class SequenceAndSetBase(base.AbstractConstructedAsn1Item):
 
         The PyASN1 value objects can **additionally** participate in many operations
         involving regular Python objects (e.g. arithmetic, comprehension etc).
+
+        It is sufficient for |ASN.1| objects to have all non-optional and non-defaulted
+        components being value objects to be considered as a value objects as a whole.
+        In other words, even having one or more optional components not turned into
+        value objects, |ASN.1| object is still considered as a value object. Defaulted
+        components are normally value objects by default.
         """
         if self._componentValues is noValue:
             return False