From ac1628691fa68bcc61a0374b219ead802b94e17b Mon Sep 17 00:00:00 2001
From: Sergey Matveev <stargrave@stargrave.org>
Date: Thu, 6 Feb 2020 14:37:44 +0300
Subject: [PATCH] More decod() usage examples

---
 doc/examples.rst   |  2 +-
 pyderasn.py        | 25 ++++++++++++++-----------
 tests/test_crts.py |  6 ++----
 3 files changed, 17 insertions(+), 16 deletions(-)

diff --git a/doc/examples.rst b/doc/examples.rst
index 7e4c473..5dace60 100644
--- a/doc/examples.rst
+++ b/doc/examples.rst
@@ -177,7 +177,7 @@ We are ready to decode PayPal's certificate from Go `encoding/asn1
 <https://golang.org/pkg/encoding/asn1/>`__ test suite (assuming that
 it's DER encoded representation is already in ``raw`` variable)::
 
-    >>> crt, tail = Certificate().decode(raw)
+    >>> crt = Certificate().decod(raw)
     >>> crt
     Certificate SEQUENCE[tbsCertificate: TBSCertificate SEQUENCE[
         version: [0] EXPLICIT Version INTEGER v3 OPTIONAL;
diff --git a/pyderasn.py b/pyderasn.py
index 92c1824..00defa5 100755
--- a/pyderasn.py
+++ b/pyderasn.py
@@ -21,7 +21,7 @@ format, unmarshal them in BER/CER/DER ones.
 
     >>> i = Integer(123)
     >>> raw = i.encode()
-    >>> Integer().decode(raw) == i
+    >>> Integer().decod(raw) == i
     True
 
 There are primitive types, holding single values
@@ -170,13 +170,16 @@ safely mutated.
 Decoding
 --------
 
-Decoding is performed using ``decode()`` method. ``offset`` optional
-argument could be used to set initial object's offset in the binary
-data, for convenience. It returns decoded object and remaining
-unmarshalled data (tail). Internally all work is done on
+Decoding is performed using :py:meth:`pyderasn.Obj.decode` method.
+``offset`` optional argument could be used to set initial object's
+offset in the binary data, for convenience. It returns decoded object
+and remaining unmarshalled data (tail). Internally all work is done on
 ``memoryview(data)``, and you can leave returning tail as a memoryview,
 by specifying ``leavemm=True`` argument.
 
+Also note convenient :py:meth:`pyderasn.Obj.decod` method, that
+immediately checks and raises if there is non-empty tail.
+
 When object is decoded, ``decoded`` property is true and you can safely
 use following properties:
 
@@ -206,9 +209,9 @@ When error occurs, :py:exc:`pyderasn.DecodeError` is raised.
 Context
 _______
 
-You can specify so called context keyword argument during ``decode()``
-invocation. It is dictionary containing various options governing
-decoding process.
+You can specify so called context keyword argument during
+:py:meth:`pyderasn.Obj.decode` invocation. It is dictionary containing
+various options governing decoding process.
 
 Currently available context options:
 
@@ -430,7 +433,7 @@ For example, again for CMS, you want to automatically decode
 structures it may hold. Also, automatically decode ``controlSequence``
 of ``PKIResponse``::
 
-    content_info, tail = ContentInfo().decode(data, ctx={"defines_by_path": (
+    content_info = ContentInfo().decod(data, ctx={"defines_by_path": (
         (
             ("contentType",),
             ((("content",), {id_signedData: SignedData()}),),
@@ -4415,9 +4418,9 @@ class PrimitiveTypes(Choice):
 
     It could be useful for general decoding of some unspecified values:
 
-    >>> PrimitiveTypes().decode(hexdec("0403666f6f"))[0].value
+    >>> PrimitiveTypes().decod(hexdec("0403666f6f")).value
     OCTET STRING 3 bytes 666f6f
-    >>> PrimitiveTypes().decode(hexdec("0203123456"))[0].value
+    >>> PrimitiveTypes().decod(hexdec("0203123456")).value
     INTEGER 1193046
     """
     __slots__ = ()
diff --git a/tests/test_crts.py b/tests/test_crts.py
index e3f84c6..4b58fac 100644
--- a/tests/test_crts.py
+++ b/tests/test_crts.py
@@ -205,8 +205,7 @@ class TestGoSelfSignedVector(TestCase):
             "ba3ca12568fdc6c7b4511cd40a7f659980402df2b998bb9a4a8cbeb34c0f0a78c",
             "f8d91ede14a5ed76bf116fe360aafa8821490435",
         )))
-        crt, tail = Certificate().decode(raw)
-        self.assertSequenceEqual(tail, b"")
+        crt = Certificate().decod(raw)
         tbs = crt["tbsCertificate"]
         self.assertEqual(tbs["version"], 0)
         self.assertFalse(tbs["version"].decoded)
@@ -397,8 +396,7 @@ class TestGoPayPalVector(TestCase):
             "07ba44cce54a2d723f9847f626dc054605076321ab469b9c78d5545b3d0c1ec86",
             "48cb55023826fdbb8221c439607a8bb",
         )))
-        crt, tail = Certificate().decode(raw)
-        self.assertSequenceEqual(tail, b"")
+        crt = Certificate().decod(raw)
         self.assertSequenceEqual(crt.encode(), raw)
         pprint(crt)
         repr(crt)
-- 
2.44.0