Add exception classes documentation

Also fix references to exception objects in other docstrings.

14 files changed, 122 insertions, 33 deletions

diff --git a/docs/source/pyasn1/contents.rst b/docs/source/pyasn1/contents.rst
index 474bbff..554ebe9 100644
--- a/docs/source/pyasn1/contents.rst
+++ b/docs/source/pyasn1/contents.rst
@@ -212,3 +212,16 @@ implemented in pyasn1.
    /pyasn1/codec/cer/contents
    /pyasn1/codec/der/contents
    /pyasn1/codec/native/contents
+
+Exceptions
+----------
+
+Operations on PyASN1 schema and value objects might cause errors. These
+errors are manifested to the caller in form of Python exceptions.
+
+The exception hierarchy is as follows (ordered from least specific).
+
+.. toctree::
+   :maxdepth: 2
+
+   /pyasn1/error/contents
diff --git a/docs/source/pyasn1/error/contents.rst b/docs/source/pyasn1/error/contents.rst
new file mode 100644
index 0000000..be8a04c
--- /dev/null
+++ b/docs/source/pyasn1/error/contents.rst
@@ -0,0 +1,60 @@
+
+.. _error.PyAsn1Error:
+
+.. |PyAsn1Error| replace:: PyAsn1Error
+
+|PyAsn1Error|
+-------------
+
+.. autoclass:: pyasn1.error.PyAsn1Error
+   :members:
+
+.. _error.ValueConstraintError:
+
+.. |ValueConstraintError| replace:: ValueConstraintError
+
+|ValueConstraintError|
+----------------------
+
+.. autoclass:: pyasn1.error.ValueConstraintError
+   :members:
+
+.. _error.SubstrateUnderrunError:
+
+.. |SubstrateUnderrunError| replace:: SubstrateUnderrunError
+
+|SubstrateUnderrunError|
+------------------------
+
+.. autoclass:: pyasn1.error.SubstrateUnderrunError
+   :members:
+
+.. _error.PyAsn1UnicodeError:
+
+.. |PyAsn1UnicodeError| replace:: PyAsn1UnicodeError
+
+|PyAsn1UnicodeError|
+--------------------
+
+.. autoclass:: pyasn1.error.PyAsn1UnicodeError
+   :members:
+
+.. _error.PyAsn1UnicodeDecodeError:
+
+.. |PyAsn1UnicodeDecodeError| replace:: PyAsn1UnicodeDecodeError
+
+|PyAsn1UnicodeDecodeError|
+--------------------------
+
+.. autoclass:: pyasn1.error.PyAsn1UnicodeDecodeError
+   :members:
+
+.. _error.PyAsn1UnicodeEncodeError:
+
+.. |PyAsn1UnicodeEncodeError| replace:: PyAsn1UnicodeEncodeError
+
+|PyAsn1UnicodeEncodeError|
+--------------------------
+
+.. autoclass:: pyasn1.error.PyAsn1UnicodeEncodeError
+   :members:
diff --git a/pyasn1/codec/ber/decoder.py b/pyasn1/codec/ber/decoder.py
index ddd8f83..3f2d180 100644
--- a/pyasn1/codec/ber/decoder.py
+++ b/pyasn1/codec/ber/decoder.py
@@ -1620,7 +1620,7 @@ class Decoder(object):
 #:
 #: Raises
 #: ------
-#: :py:class:`~pyasn1.error.PyAsn1Error`
+#: ~pyasn1.error.PyAsn1Error, ~pyasn1.error.SubstrateUnderrunError
 #:     On decoding errors
 #:
 #: Examples
diff --git a/pyasn1/codec/ber/encoder.py b/pyasn1/codec/ber/encoder.py
index fbad7e7..58e71e7 100644
--- a/pyasn1/codec/ber/encoder.py
+++ b/pyasn1/codec/ber/encoder.py
@@ -861,7 +861,7 @@ class Encoder(object):
 #:
 #: Raises
 #: ------
-#: :py:class:`~pyasn1.error.PyAsn1Error`
+#: ~pyasn1.error.PyAsn1Error
 #:     On encoding errors
 #:
 #: Examples
diff --git a/pyasn1/codec/cer/decoder.py b/pyasn1/codec/cer/decoder.py
index 5099e3c..3e86fd0 100644
--- a/pyasn1/codec/cer/decoder.py
+++ b/pyasn1/codec/cer/decoder.py
@@ -87,7 +87,7 @@ class Decoder(decoder.Decoder):
 #:
 #: Raises
 #: ------
-#: :py:class:`~pyasn1.error.PyAsn1Error`
+#: ~pyasn1.error.PyAsn1Error, ~pyasn1.error.SubstrateUnderrunError
 #:     On decoding errors
 #:
 #: Examples
diff --git a/pyasn1/codec/cer/encoder.py b/pyasn1/codec/cer/encoder.py
index d7a1dfe..6a9db97 100644
--- a/pyasn1/codec/cer/encoder.py
+++ b/pyasn1/codec/cer/encoder.py
@@ -284,7 +284,7 @@ class Encoder(encoder.Encoder):
 #:
 #: Raises
 #: ------
-#: :py:class:`~pyasn1.error.PyAsn1Error`
+#: ~pyasn1.error.PyAsn1Error
 #:     On encoding errors
 #:
 #: Examples
diff --git a/pyasn1/codec/der/decoder.py b/pyasn1/codec/der/decoder.py
index 261bab8..1a13fdb 100644
--- a/pyasn1/codec/der/decoder.py
+++ b/pyasn1/codec/der/decoder.py
@@ -67,7 +67,7 @@ class Decoder(decoder.Decoder):
 #:
 #: Raises
 #: ------
-#: :py:class:`~pyasn1.error.PyAsn1Error`
+#: ~pyasn1.error.PyAsn1Error, ~pyasn1.error.SubstrateUnderrunError
 #:     On decoding errors
 #:
 #: Examples
diff --git a/pyasn1/codec/der/encoder.py b/pyasn1/codec/der/encoder.py
index 5e3c571..90e982d 100644
--- a/pyasn1/codec/der/encoder.py
+++ b/pyasn1/codec/der/encoder.py
@@ -82,7 +82,7 @@ class Encoder(encoder.Encoder):
 #:
 #: Raises
 #: ------
-#: :py:class:`~pyasn1.error.PyAsn1Error`
+#: ~pyasn1.error.PyAsn1Error
 #:     On encoding errors
 #:
 #: Examples
diff --git a/pyasn1/codec/native/decoder.py b/pyasn1/codec/native/decoder.py
index 10e2015..104b92e 100644
--- a/pyasn1/codec/native/decoder.py
+++ b/pyasn1/codec/native/decoder.py
@@ -195,7 +195,7 @@ class Decoder(object):
 #:
 #: Raises
 #: ------
-#: :py:class:`~pyasn1.error.PyAsn1Error`
+#: ~pyasn1.error.PyAsn1Error
 #:     On decoding errors
 #:
 #: Examples
diff --git a/pyasn1/codec/native/encoder.py b/pyasn1/codec/native/encoder.py
index 50caa53..4c5908d 100644
--- a/pyasn1/codec/native/encoder.py
+++ b/pyasn1/codec/native/encoder.py
@@ -235,7 +235,7 @@ class Encoder(object):
 #:
 #: Raises
 #: ------
-#: :py:class:`~pyasn1.error.PyAsn1Error`
+#: ~pyasn1.error.PyAsn1Error
 #:     On encoding errors
 #:
 #: Examples
diff --git a/pyasn1/error.py b/pyasn1/error.py
index cb30033..4f48db2 100644
--- a/pyasn1/error.py
+++ b/pyasn1/error.py
@@ -7,33 +7,41 @@
 
 
 class PyAsn1Error(Exception):
-    """Create pyasn1 exception object
+    """Base pyasn1 exception
 
-    The `PyAsn1Error` exception represents generic, usually fatal, error.
+    `PyAsn1Error` is the base exception class (based on
+    :class:`Exception`) that represents all possible ASN.1 related
+    errors.
     """
 
 
 class ValueConstraintError(PyAsn1Error):
-    """Create pyasn1 exception object
+    """ASN.1 type constraints violation exception
 
     The `ValueConstraintError` exception indicates an ASN.1 value
     constraint violation.
+
+    It might happen on value object instantiation (for scalar types) or on
+    serialization (for constructed types).
     """
 
 
 class SubstrateUnderrunError(PyAsn1Error):
-    """Create pyasn1 exception object
+    """ASN.1 data structure deserialization error
 
     The `SubstrateUnderrunError` exception indicates insufficient serialised
-    data on input of a de-serialization routine.
+    data on input of a de-serialization codec.
     """
 
 
 class PyAsn1UnicodeError(PyAsn1Error, UnicodeError):
-    """Create pyasn1 exception object
+    """Unicode text processing error
 
     The `PyAsn1UnicodeError` exception is a base class for errors relating to
     unicode text de/serialization.
+
+    Apart from inheriting from :class:`PyAsn1Error`, it also inherits from
+    :class:`UnicodeError` to help the caller catching unicode-related errors.
     """
     def __init__(self, message, unicode_error=None):
         if isinstance(unicode_error, UnicodeError):
@@ -42,18 +50,26 @@ class PyAsn1UnicodeError(PyAsn1Error, UnicodeError):
 
 
 class PyAsn1UnicodeDecodeError(PyAsn1UnicodeError, UnicodeDecodeError):
-    """Create pyasn1 exception object
+    """Unicode text decoding error
 
     The `PyAsn1UnicodeDecodeError` exception represents a failure to
     deserialize unicode text.
+
+    Apart from inheriting from :class:`PyAsn1UnicodeError`, it also inherits
+    from :class:`UnicodeDecodeError` to help the caller catching unicode-related
+    errors.
     """
 
 
 class PyAsn1UnicodeEncodeError(PyAsn1UnicodeError, UnicodeEncodeError):
-    """Create pyasn1 exception object
+    """Unicode text encoding error
 
     The `PyAsn1UnicodeEncodeError` exception represents a failure to
     serialize unicode text.
+
+    Apart from inheriting from :class:`PyAsn1UnicodeError`, it also inherits
+    from :class:`UnicodeEncodeError` to help the caller catching
+    unicode-related errors.
     """
 
 
diff --git a/pyasn1/type/char.py b/pyasn1/type/char.py
index 1b5daed..ce10599 100644
--- a/pyasn1/type/char.py
+++ b/pyasn1/type/char.py
@@ -44,7 +44,7 @@ class AbstractCharacterString(univ.OctetString):
 
     Raises
     ------
-    :py:class:`~pyasn1.error.PyAsn1Error`
+    ~pyasn1.error.PyAsn1Error
         On constraint violation or bad initializer.
     """
 
diff --git a/pyasn1/type/namedtype.py b/pyasn1/type/namedtype.py
index 71f5f11..936c96c 100644
--- a/pyasn1/type/namedtype.py
+++ b/pyasn1/type/namedtype.py
@@ -293,7 +293,7 @@ class NamedTypes(object):
 
         Raises
         ------
-        : :class:`~pyasn1.error.PyAsn1Error`
+        ~pyasn1.error.PyAsn1Error
             If given position is out of fields range
         """
         try:
@@ -317,7 +317,7 @@ class NamedTypes(object):
 
         Raises
         ------
-        : :class:`~pyasn1.error.PyAsn1Error`
+        ~pyasn1.error.PyAsn1Error
             If *tagSet* is not present or ASN.1 types are not unique within callee *NamedTypes*
         """
         try:
@@ -341,7 +341,7 @@ class NamedTypes(object):
 
         Raises
         ------
-        : :class:`~pyasn1.error.PyAsn1Error`
+        ~pyasn1.error.PyAsn1Error
             If given field name is not present in callee *NamedTypes*
         """
         try:
@@ -365,7 +365,7 @@ class NamedTypes(object):
 
         Raises
         ------
-        : :class:`~pyasn1.error.PyAsn1Error`
+        ~pyasn1.error.PyAsn1Error
             If *name* is not present or not unique within callee *NamedTypes*
         """
         try:
@@ -394,7 +394,7 @@ class NamedTypes(object):
 
         Raises
         ------
-        : :class:`~pyasn1.error.PyAsn1Error`
+        ~pyasn1.error.PyAsn1Error
             If given position is out of fields range
         """
         try:
@@ -426,7 +426,7 @@ class NamedTypes(object):
 
         Raises
         ------
-        : :class:`~pyasn1.error.PyAsn1Error`
+        ~pyasn1.error.PyAsn1Error
             If *tagSet* is not present or not unique within callee *NamedTypes*
             or *idx* is out of fields range
         """
diff --git a/pyasn1/type/univ.py b/pyasn1/type/univ.py
index 93114d6..2a42fc7 100644
--- a/pyasn1/type/univ.py
+++ b/pyasn1/type/univ.py
@@ -52,7 +52,7 @@ class Integer(base.AbstractSimpleAsn1Item):
 
     Raises
     ------
-    :py:class:`~pyasn1.error.PyAsn1Error`
+    ~pyasn1.error.PyAsn1Error
         On constraint violation or bad initializer.
 
     Examples
@@ -296,7 +296,7 @@ class Boolean(Integer):
 
     Raises
     ------
-    :py:class:`~pyasn1.error.PyAsn1Error`
+    ~pyasn1.error.PyAsn1Error
         On constraint violation or bad initializer.
 
     Examples
@@ -386,7 +386,7 @@ class BitString(base.AbstractSimpleAsn1Item):
 
     Raises
     ------
-    :py:class:`~pyasn1.error.PyAsn1Error`
+    ~pyasn1.error.PyAsn1Error
         On constraint violation or bad initializer.
 
     Examples
@@ -754,7 +754,7 @@ class OctetString(base.AbstractSimpleAsn1Item):
 
     Raises
     ------
-    :py:class:`~pyasn1.error.PyAsn1Error`
+    ~pyasn1.error.PyAsn1Error
         On constraint violation or bad initializer.
 
     Examples
@@ -1047,7 +1047,7 @@ class Null(OctetString):
 
     Raises
     ------
-    :py:class:`~pyasn1.error.PyAsn1Error`
+    ~pyasn1.error.PyAsn1Error
         On constraint violation or bad initializer.
 
     Examples
@@ -1106,7 +1106,7 @@ class ObjectIdentifier(base.AbstractSimpleAsn1Item):
 
     Raises
     ------
-    :py:class:`~pyasn1.error.PyAsn1Error`
+    ~pyasn1.error.PyAsn1Error
         On constraint violation or bad initializer.
 
     Examples
@@ -1242,7 +1242,7 @@ class Real(base.AbstractSimpleAsn1Item):
 
     Raises
     ------
-    :py:class:`~pyasn1.error.PyAsn1Error`
+    ~pyasn1.error.PyAsn1Error
         On constraint violation or bad initializer.
 
     Examples
@@ -1527,7 +1527,7 @@ class Enumerated(Integer):
 
     Raises
     ------
-    :py:class:`~pyasn1.error.PyAsn1Error`
+    ~pyasn1.error.PyAsn1Error
         On constraint violation or bad initializer.
 
     Examples
@@ -1827,7 +1827,7 @@ class SequenceOfAndSetOfBase(base.AbstractConstructedAsn1Item):
 
         Raises
         ------
-        IndexError:
+        IndexError
             When idx > len(self)
         """
         if isinstance(idx, slice):
@@ -3160,7 +3160,7 @@ class Any(OctetString):
 
     Raises
     ------
-    :py:class:`~pyasn1.error.PyAsn1Error`
+    ~pyasn1.error.PyAsn1Error
         On constraint violation or bad initializer.
 
     Examples