docs on channel aliases. docs need pinouts

adafruit_mcp3xxx/analog_in.py

@@ -26,6 +26,24 @@
 differential ADC readings.
 
 * Author(s): Brent Rubell
+
+.. note:: The ADC chips' input pins (AKA "channels") are aliased in this library as integer
+    variables whose names start with "P". Each module that contains a driver class for a
+    particular ADC chip (in this library) has these aliases predefined accordingly. This is done
+    for code readability and prevention of erroneous SPI commands. The following example code
+    explains this best:
+
+    .. code-block:: python
+
+        >>> import adafruit_mcp3xxx.mcp3008 as MCP
+        >>> print('channel', MCP.P0)
+        channel 0
+        >>> print('channel', MCP.P7)
+        channel 7
+        >>> print('channel', MCP.P8)
+        Traceback (most recent call last):
+          File "<stdin>", line 1, in <module>
+        AttributeError: 'module' object has no attribute 'P8'
 """
 
 from .mcp3xxx import MCP3xxx
@@ -36,6 +54,19 @@ class AnalogIn():
     :param ~mcp3002.MCP3002,~mcp3004.MCP3004,~mcp3008.MCP3008 mcp: The mcp object.
     :param int positive_pin: Required pin for single-ended.
     :param int negative_pin: Optional pin for differential reads.
+
+    .. important::
+        The ADC chips supported by this library do not handle negative numbers when returning the
+        differential read of 2 channels. If the resulting differential read is less than 0, the
+        returned integer is ``0``. If for some reason the voltage on a channel is greater than the
+        reference voltage (Vin) or less than 0, then the returned integer is ``65472‬`` or ``0``
+        (applies to single ended and differential reads).
+
+        It is also worth noting that the differential reads (comparisons done by the ADC chip) are
+        limited to certain pairs of channels. Please refer to the driver class of your ADC chip for
+        a list of available differential mappings (comparisons). Otherwise, it is recommended to
+        compute the differences between single-ended reads of separate channels for more flexible
+        results.
     """
     def __init__(self, mcp, positive_pin, negative_pin=None):
         if not isinstance(mcp, MCP3xxx):

adafruit_mcp3xxx/mcp3002.py

@@ -30,15 +30,19 @@
 """
 from .mcp3xxx import MCP3xxx
 
-# MCP3002 Pin Mapping
+# # MCP3002 Pin Mapping
 P0 = 0
 P1 = 1
 
 class MCP3002(MCP3xxx):
     """
-    MCP3002 Differential channel mapping.
-        - 0: CH0 = IN+, CH1 = IN-
-        - 1: CH1 = IN+, CH0 = IN-
+    MCP3002 Differential channel mapping. The following list of available differential readings
+    takes the form ``(positive_pin, negative_pin) = channel A - channel B``.
+
+    - (P0, P1) = CH0 - CH1
+    - (P1, P0) = CH1 - CH0
+
+    See also the notes in the `AnalogIn <api.html#id3>`_ class.
     """
     DIFF_PINS = {
         (0, 1) : P0,

adafruit_mcp3xxx/mcp3004.py

@@ -30,19 +30,23 @@
 
 from .mcp3xxx import MCP3xxx
 
-# MCP3004 Pin Mapping
+# # MCP3004 Pin Mapping
 P0 = 0
 P1 = 1
 P2 = 2
 P3 = 3
 
 class MCP3004(MCP3xxx):
     """
-    MCP3004 Differential channel mapping.
-        - 0: CH0 = IN+, CH1 = IN-
-        - 1: CH1 = IN+, CH0 = IN-
-        - 2: CH2 = IN+, CH3 = IN-
-        - 3: CH3 = IN+, CH2 = IN-
+    MCP3004 Differential channel mapping. The following list of available differential readings
+    takes the form ``(positive_pin, negative_pin) = channel A - channel B``.
+
+    - (P0, P1) = CH0 - CH1
+    - (P1, P0) = CH1 - CH0
+    - (P2, P3) = CH2 - CH3
+    - (P3, P2) = CH3 - CH2
+
+    See also the notes in the `AnalogIn <api.html#id3>`_ class.
     """
     DIFF_PINS = {
         (0, 1) : P0,

adafruit_mcp3xxx/mcp3008.py

@@ -30,7 +30,7 @@
 
 from .mcp3xxx import MCP3xxx
 
-# MCP3008 Pin Mapping
+# # MCP3008 Pin Mapping
 P0 = 0
 P1 = 1
 P2 = 2
@@ -42,15 +42,19 @@
 
 class MCP3008(MCP3xxx):
     """
-    MCP3008 Differential channel mapping.
-        - 0: CH0 = IN+, CH1 = IN-
-        - 1: CH1 = IN+, CH0 = IN-
-        - 2: CH2 = IN+, CH3 = IN-
-        - 3: CH3 = IN+, CH2 = IN-
-        - 4: CH4 = IN+, CH5 = IN-
-        - 5: CH5 = IN+, CH4 = IN-
-        - 6: CH6 = IN+, CH7 = IN-
-        - 7: CH7 = IN+, CH6 = IN-
+    MCP3008 Differential channel mapping. The following list of available differential readings
+    takes the form ``(positive_pin, negative_pin) = channel A - channel B``.
+
+    - (P0, P1) = CH0 - CH1
+    - (P1, P0) = CH1 - CH0
+    - (P2, P3) = CH2 - CH3
+    - (P3, P2) = CH3 - CH2
+    - (P4, P5) = CH4 - CH5
+    - (P5, P4) = CH5 - CH4
+    - (P6, P7) = CH6 - CH7
+    - (P7, P6) = CH7 - CH6
+
+    See also the notes in the `AnalogIn <api.html#id3>`_ class.
     """
     DIFF_PINS = {
         (0, 1) : P0,