Improve documentation of varBindTable returned by bulkCmd() (#91)

* Clarify varBindTable returned by bulkCmd() in docs
* Fix bulkCmd() examples
* Abbreviate endOfMibView
* Fix fixed-width markup of Get{BulkRequest,Response}-PDU

3 files changed, 74 insertions, 21 deletions

diff --git a/pysnmp/hlapi/asyncio/cmdgen.py b/pysnmp/hlapi/asyncio/cmdgen.py
index 9e732062..814a0559 100644
--- a/pysnmp/hlapi/asyncio/cmdgen.py
+++ b/pysnmp/hlapi/asyncio/cmdgen.py
@@ -427,13 +427,31 @@ def bulkCmd(snmpEngine, authData, transportTarget, contextData,
         True value indicates SNMP PDU error.
     errorIndex : int
         Non-zero value refers to `varBinds[errorIndex-1]`
-    varBinds : tuple
+    varBindTable : tuple
         A sequence of sequences (e.g. 2-D array) of
         :py:class:`~pysnmp.smi.rfc1902.ObjectType` class instances
-        representing a table of MIB variables returned in SNMP response.
-        Inner sequences represent table rows and ordered exactly the same
-        as `varBinds` in request. Response to GETNEXT always contain
-        a single row.
+        representing a table of MIB variables returned in SNMP response, with
+        up to ``maxRepetitions`` rows, i.e.
+        ``len(varBindTable) <= maxRepetitions``.
+
+        For ``0 <= i < len(varBindTable)`` and ``0 <= j < len(varBinds)``,
+        ``varBindTable[i][j]`` represents:
+
+        - For non-repeaters (``j < nonRepeaters``), the first lexicographic
+          successor of ``varBinds[j]``, regardless the value of ``i``, or an
+          :py:class:`~pysnmp.smi.rfc1902.ObjectType` instance with the
+          :py:obj:`~pysnmp.proto.rfc1905.endOfMibView` value if no such
+          successor exists;
+        - For repeaters (``j >= nonRepeaters``), the ``i``-th lexicographic
+          successor of ``varBinds[j]``, or an
+          :py:class:`~pysnmp.smi.rfc1902.ObjectType` instance with the
+          :py:obj:`~pysnmp.proto.rfc1905.endOfMibView` value if no such
+          successor exists.
+
+        See :rfc:`3416#section-4.2.3` for details on the underlying
+        ``GetBulkRequest-PDU`` and the associated ``GetResponse-PDU``, such as
+        specific conditions under which the server may truncate the response,
+        causing ``varBindTable`` to have less than ``maxRepetitions`` rows.
 
     Raises
     ------
@@ -459,7 +477,7 @@ def bulkCmd(snmpEngine, authData, transportTarget, contextData,
     ...     print(errorIndication, errorStatus, errorIndex, varBinds)
     >>>
     >>> asyncio.get_event_loop().run_until_complete(run())
-    (None, 0, 0, [[ObjectType(ObjectIdentity(ObjectName('1.3.6.1.2.1.1.1.0')), DisplayString('SunOS zeus.snmplabs.com 4.1.3_U1 1 sun4m')), ObjectType(ObjectIdentity(ObjectName('1.3.6.1.2.1.1.2.0')), ObjectIdentifier('1.3.6.1.4.1.424242.1.1')]])
+    (None, 0, 0, [[ObjectType(ObjectIdentity(ObjectName('1.3.6.1.2.1.1.1.0')), DisplayString('SunOS zeus.snmplabs.com 4.1.3_U1 1 sun4m'))], [ObjectType(ObjectIdentity(ObjectName('1.3.6.1.2.1.1.2.0')), ObjectIdentifier('1.3.6.1.4.1.424242.1.1'))]])
     >>>
 
     """
diff --git a/pysnmp/hlapi/asyncore/cmdgen.py b/pysnmp/hlapi/asyncore/cmdgen.py
index 369a8b2b..3a5dd9ec 100644
--- a/pysnmp/hlapi/asyncore/cmdgen.py
+++ b/pysnmp/hlapi/asyncore/cmdgen.py
@@ -416,12 +416,30 @@ def bulkCmd(snmpEngine, authData, transportTarget, contextData,
     * errorIndication (str): True value indicates SNMP engine error.
     * errorStatus (str): True value indicates SNMP PDU error.
     * errorIndex (int): Non-zero value refers to `varBinds[errorIndex-1]`
-    * varBinds (tuple): A sequence of sequences (e.g. 2-D array) of
-      :py:class:`~pysnmp.smi.rfc1902.ObjectType` class instances
-      representing a table of MIB variables returned in SNMP response.
-      Inner sequences represent table rows and ordered exactly the same
-      as `varBinds` in request. Number of rows might be less or equal
-      to `maxRepetitions` value in request.
+    * varBindTable (tuple):
+      A sequence of sequences (e.g. 2-D array) of
+      :py:class:`~pysnmp.smi.rfc1902.ObjectType` class instances representing a
+      table of MIB variables returned in SNMP response, with up to
+      ``maxRepetitions`` rows, i.e. ``len(varBindTable) <= maxRepetitions``.
+
+      For ``0 <= i < len(varBindTable)`` and ``0 <= j < len(varBinds)``,
+      ``varBindTable[i][j]`` represents:
+
+      - For non-repeaters (``j < nonRepeaters``), the first lexicographic
+        successor of ``varBinds[j]``, regardless the value of ``i``, or an
+        :py:class:`~pysnmp.smi.rfc1902.ObjectType` instance with the
+        :py:obj:`~pysnmp.proto.rfc1905.endOfMibView` value if no such successor
+        exists;
+      - For repeaters (``j >= nonRepeaters``), the ``i``-th lexicographic
+        successor of ``varBinds[j]``, or an
+        :py:class:`~pysnmp.smi.rfc1902.ObjectType` instance with the
+        :py:obj:`~pysnmp.proto.rfc1905.endOfMibView` value if no such successor
+        exists.
+
+      See :rfc:`3416#section-4.2.3` for details on the underlying
+      ``GetBulkRequest-PDU`` and the associated ``GetResponse-PDU``, such as
+      specific conditions under which the server may truncate the response,
+      causing ``varBindTable`` to have less than ``maxRepetitions`` rows.
     * `cbCtx` : Original user-supplied object.
 
     Returns
@@ -451,7 +469,7 @@ def bulkCmd(snmpEngine, authData, transportTarget, contextData,
     ...         ObjectType(ObjectIdentity('SNMPv2-MIB', 'system')),
     ...         cbFun=cbFun)
     >>> snmpEngine.transportDispatcher.runDispatcher()
-    (None, 0, 0, [ [ObjectType(ObjectIdentity(ObjectName('1.3.6.1.2.1.1.1.0')), DisplayString('SunOS zeus.snmplabs.com 4.1.3_U1 1 sun4m')), ObjectType(ObjectIdentity(ObjectName('1.3.6.1.2.1.1.2.0')), ObjectIdentifier('1.3.6.1.4.1.424242.1.1')] ])
+    (None, 0, 0, [[ObjectType(ObjectIdentity(ObjectName('1.3.6.1.2.1.1.1.0')), DisplayString('SunOS zeus.snmplabs.com 4.1.3_U1 1 sun4m'))], [ObjectType(ObjectIdentity(ObjectName('1.3.6.1.2.1.1.2.0')), ObjectIdentifier('1.3.6.1.4.1.424242.1.1'))]])
     >>>
 
     """
diff --git a/pysnmp/hlapi/twisted/cmdgen.py b/pysnmp/hlapi/twisted/cmdgen.py
index aa2ce106..ddddfe31 100644
--- a/pysnmp/hlapi/twisted/cmdgen.py
+++ b/pysnmp/hlapi/twisted/cmdgen.py
@@ -453,13 +453,30 @@ def bulkCmd(snmpEngine, authData, transportTarget, contextData,
 
     * errorStatus (str) : True value indicates SNMP PDU error.
     * errorIndex (int) : Non-zero value refers to `varBinds[errorIndex-1]`
-    * varBinds (tuple) :
-        A sequence of sequences (e.g. 2-D array) of
-        :py:class:`~pysnmp.smi.rfc1902.ObjectType` class instances
-        representing a table of MIB variables returned in SNMP response.
-        Inner sequences represent table rows and ordered exactly the same
-        as `varBinds` in request. Number of rows might be less or equal
-        to `maxRepetitions` value in request.
+    * varBindTable (tuple):
+      A sequence of sequences (e.g. 2-D array) of
+      :py:class:`~pysnmp.smi.rfc1902.ObjectType` class instances representing a
+      table of MIB variables returned in SNMP response, with up to
+      ``maxRepetitions`` rows, i.e. ``len(varBindTable) <= maxRepetitions``.
+
+      For ``0 <= i < len(varBindTable)`` and ``0 <= j < len(varBinds)``,
+      ``varBindTable[i][j]`` represents:
+
+      - For non-repeaters (``j < nonRepeaters``), the first lexicographic
+        successor of ``varBinds[j]``, regardless the value of ``i``, or an
+        :py:class:`~pysnmp.smi.rfc1902.ObjectType` instance with the
+        :py:obj:`~pysnmp.proto.rfc1905.endOfMibView` value if no such successor
+        exists;
+      - For repeaters (``j >= nonRepeaters``), the ``i``-th lexicographic
+        successor of ``varBinds[j]``, or an
+        :py:class:`~pysnmp.smi.rfc1902.ObjectType` instance with the
+        :py:obj:`~pysnmp.proto.rfc1905.endOfMibView` value if no such successor
+        exists.
+
+      See :rfc:`3416#section-4.2.3` for details on the underlying
+      ``GetBulkRequest-PDU`` and the associated ``GetResponse-PDU``, such as
+      specific conditions under which the server may truncate the response,
+      causing ``varBindTable`` to have less than ``maxRepetitions`` rows.
 
     User `error` callback is called with `errorIndication` object wrapped
     in :class:`~twisted.python.failure.Failure` object.
@@ -487,7 +504,7 @@ def bulkCmd(snmpEngine, authData, transportTarget, contextData,
     ...     return d
     ...
     >>> react(run)
-    (0, 0, [[ObjectType(ObjectIdentity(ObjectName('1.3.6.1.2.1.1.1.0')), DisplayString('SunOS zeus.snmplabs.com 4.1.3_U1 1 sun4m')), ObjectType(ObjectIdentity(ObjectName('1.3.6.1.2.1.1.2.0')), ObjectIdentifier('1.3.6.1.4.1.424242.1.1')]])
+    (0, 0, [[ObjectType(ObjectIdentity(ObjectName('1.3.6.1.2.1.1.1.0')), DisplayString('SunOS zeus.snmplabs.com 4.1.3_U1 1 sun4m'))], [ObjectType(ObjectIdentity(ObjectName('1.3.6.1.2.1.1.2.0')), ObjectIdentifier('1.3.6.1.4.1.424242.1.1'))]])
     >>>
 
     """