Setting the package names correctly in the MIDI messages class files.

Adding some warnings on SystemExclusive needing to fit into the input buffer to parse.
Changing the reST docs for default class methods in MIDIMessage as those are inherited by documentation too and were not appropropriate for all.
Documenting the MIDI constructor. #3

Author: Kevin J Walters

adafruit_midi/__init__.py

@@ -51,15 +51,32 @@
 
 
 class MIDI:
-    """MIDI helper class."""
+    """MIDI helper class.
+
+    :param midi_in: an object which implements ``read(length)``,
+        defaults to ``usb_midi.ports[0]``.
+    :param midi_out: an object which implements ``write(buffer, length)``,
+        defaults to ``usb_midi.ports[1]``.
+    :param in_channel: The input channel(s).
+        This is used by ``receive`` to filter data.
+        This can either be an ``int`` for the wire protocol channel number (0-15)
+        a tuple of ``int`` to listen for multiple channels or ``"ALL"``.
+        Defaults to None.
+    :param int out_channel: The wire protocol output channel number (0-15)
+        used by ``send`` if no channel is specified,
+        defaults to 0 (MIDI Channel 1).
+    :param int in_buf_size: Size of input buffer in bytes, default 30.
+    :param bool debug: Debug mode, default False.
+
+    """
 
     NOTE_ON = 0x90
     NOTE_OFF = 0x80
     PITCH_BEND = 0xE0
     CONTROL_CHANGE = 0xB0
 
     def __init__(self, midi_in=usb_midi.ports[0], midi_out=usb_midi.ports[1], *,
-                 in_channel=None, out_channel=0, debug=False, in_buf_size=30):
+                 in_channel=None, out_channel=0, in_buf_size=30, debug=False):
         self._midi_in = midi_in
         self._midi_out = midi_out
         self.in_channel = in_channel
@@ -108,8 +125,10 @@ def out_channel(self, channel):
     def receive(self):
         """Read messages from MIDI port, store them in internal read buffer, then parse that data
         and return the first MIDI message (event).
+        This maintains the blocking characteristics of the midi_in port.
 
-        Returns (MIDIMessage object, channel) or (None, None) for nothing.
+        :returns (MIDIMessage object, int channel): Returns object and channel
+           or (None, None) for nothing.
         """
         ### could check _midi_in is an object OR correct object OR correct interface here?
         # If the buffer here is not full then read as much as we can fit from

adafruit_midi/channel_pressure.py

@@ -20,26 +20,17 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 """
-`adafruit_midi`
+`adafruit_midi.channel_pressure`
 ================================================================================
 
-A CircuitPython helper for encoding/decoding MIDI packets over a MIDI or UART connection.
+Channel Pressure MIDI message.
 
 
 * Author(s): Kevin J. Walters
 
 Implementation Notes
 --------------------
 
-**Hardware:**
-
-
-
-**Software and Dependencies:**
-
-* Adafruit CircuitPython firmware for the supported boards:
-  https://github.com/adafruit/circuitpython/releases
-
 """
 
 from .midi_message import MIDIMessage

adafruit_midi/control_change.py

@@ -20,26 +20,17 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 """
-`adafruit_midi`
+`adafruit_midi.control_change`
 ================================================================================
 
-A CircuitPython helper for encoding/decoding MIDI packets over a MIDI or UART connection.
+Control Change MIDI message.
 
 
 * Author(s): Kevin J. Walters
 
 Implementation Notes
 --------------------
 
-**Hardware:**
-
-
-
-**Software and Dependencies:**
-
-* Adafruit CircuitPython firmware for the supported boards:
-  https://github.com/adafruit/circuitpython/releases
-
 """
 
 from .midi_message import MIDIMessage

adafruit_midi/midi_message.py

@@ -20,26 +20,23 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 """
-`adafruit_midi`
+`adafruit_midi.midi_message.MIDIMessage`
 ================================================================================
 
-A CircuitPython helper for encoding/decoding MIDI packets over a MIDI or UART connection.
+An abstract class for objects which represent MIDI messages (events).
+When individual messages are imported they register themselves with
+:func:register_message_type which makes them recognised
+by the parser, :func:from_message_bytes.
+
+Large messages like :class:SystemExclusive can only be parsed if they fit
+within the input buffer in :class:MIDI.
 
 
 * Author(s): Kevin J. Walters
 
 Implementation Notes
 --------------------
 
-**Hardware:**
-
-
-
-**Software and Dependencies:**
-
-* Adafruit CircuitPython firmware for the supported boards:
-  https://github.com/adafruit/circuitpython/releases
-
 """
 
 __version__ = "0.0.0-auto.0"
@@ -97,16 +94,19 @@ def note_parser(note):
 
 class MIDIMessage:
     """
-    A MIDI message:
-      - _STATUS - extracted from Status byte with channel replaced by 0s
-                  (high bit always set).
-      - _STATUSMASK - mask used to compared a status byte with _STATUS value
-      - LENGTH - length for a fixed size message including status
-                  or -1 for variable length.
-      - CHANNELMASK - mask use to apply a (wire protocol) channel number.
-      - ENDSTATUS - the EOM status byte, only set for variable length.
-
-      This is an abstract class.
+    The parent class for MIDI messages.
+
+    Class variables:
+
+      * ``_STATUS`` - extracted from status byte with channel replaced by 0s
+        (high bit is always set by convention).
+      * ``_STATUSMASK`` - mask used to compared a status byte with ``_STATUS`` value.
+      * ``LENGTH`` - length for a fixed size message *including* status
+        or -1 for variable length.
+      * ``CHANNELMASK`` - mask used to apply a (wire protocol) channel number.
+      * ``ENDSTATUS`` - the end of message status byte, only set for variable length.
+
+    This is an *abstract* class.
     """
     _STATUS = None
     _STATUSMASK = None
@@ -277,18 +277,21 @@ def from_message_bytes(cls, midibytes, channel_in):
         return (msg, msgendidxplusone, skipped, channel)
 
     # channel value present to keep interface uniform but unused
+    # A default method for constructing wire messages with no data.
+    # Returns a (mutable) bytearray with just the status code in.
     # pylint: disable=unused-argument
     def as_bytes(self, channel=None):
-        """A default method for constructing wire messages with no data.
-        Returns a (mutable) bytearray with just status code in."""
+        """Return the ``bytearray`` wire protocol representation of the object."""
         return bytearray([self._STATUS])
 
     # databytes value present to keep interface uniform but unused
+    # A default method for constructing message objects with no data.
+    # Returns the new object.
     # pylint: disable=unused-argument
     @classmethod
     def from_bytes(cls, databytes):
-        """A default method for constructing message objects with no data.
-           Returns the new object."""
+        """Creates an object from the byte stream of the wire protocol
+        (not including the first status byte)."""
         return cls()
 
 

adafruit_midi/note_off.py

@@ -20,26 +20,17 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 """
-`adafruit_midi`
+`adafruit_midi.note_off`
 ================================================================================
 
-A CircuitPython helper for encoding/decoding MIDI packets over a MIDI or UART connection.
+Note Off Change MIDI message.
 
 
 * Author(s): Kevin J. Walters
 
 Implementation Notes
 --------------------
 
-**Hardware:**
-
-
-
-**Software and Dependencies:**
-
-* Adafruit CircuitPython firmware for the supported boards:
-  https://github.com/adafruit/circuitpython/releases
-
 """
 
 from .midi_message import MIDIMessage, note_parser

adafruit_midi/note_on.py

@@ -20,26 +20,17 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 """
-`adafruit_midi`
+`adafruit_midi.note_on`
 ================================================================================
 
-A CircuitPython helper for encoding/decoding MIDI packets over a MIDI or UART connection.
+Note On Change MIDI message.
 
 
 * Author(s): Kevin J. Walters
 
 Implementation Notes
 --------------------
 
-**Hardware:**
-
-
-
-**Software and Dependencies:**
-
-* Adafruit CircuitPython firmware for the supported boards:
-  https://github.com/adafruit/circuitpython/releases
-
 """
 
 from .midi_message import MIDIMessage, note_parser

adafruit_midi/pitch_bend_change.py

@@ -20,26 +20,17 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 """
-`adafruit_midi`
+`adafruit_midi.pitch_bend_change`
 ================================================================================
 
-A CircuitPython helper for encoding/decoding MIDI packets over a MIDI or UART connection.
+Pitch Bend Change MIDI message.
 
 
 * Author(s): Kevin J. Walters
 
 Implementation Notes
 --------------------
 
-**Hardware:**
-
-
-
-**Software and Dependencies:**
-
-* Adafruit CircuitPython firmware for the supported boards:
-  https://github.com/adafruit/circuitpython/releases
-
 """
 
 from .midi_message import MIDIMessage

adafruit_midi/polyphonic_key_pressure.py

@@ -20,26 +20,17 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 """
-`adafruit_midi`
+`adafruit_midi.polyphonic_key_pressure`
 ================================================================================
 
-A CircuitPython helper for encoding/decoding MIDI packets over a MIDI or UART connection.
+Polyphonic Key Pressure MIDI message.
 
 
 * Author(s): Kevin J. Walters
 
 Implementation Notes
 --------------------
 
-**Hardware:**
-
-
-
-**Software and Dependencies:**
-
-* Adafruit CircuitPython firmware for the supported boards:
-  https://github.com/adafruit/circuitpython/releases
-
 """
 
 from .midi_message import MIDIMessage, note_parser

adafruit_midi/program_change.py

@@ -20,26 +20,17 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 """
-`adafruit_midi`
+`adafruit_midi.program_change`
 ================================================================================
 
-A CircuitPython helper for encoding/decoding MIDI packets over a MIDI or UART connection.
+Program Change MIDI message.
 
 
 * Author(s): Kevin J. Walters
 
 Implementation Notes
 --------------------
 
-**Hardware:**
-
-
-
-**Software and Dependencies:**
-
-* Adafruit CircuitPython firmware for the supported boards:
-  https://github.com/adafruit/circuitpython/releases
-
 """
 
 from .midi_message import MIDIMessage

adafruit_midi/start.py

@@ -20,26 +20,17 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 """
-`adafruit_midi`
+`adafruit_midi.start`
 ================================================================================
 
-A CircuitPython helper for encoding/decoding MIDI packets over a MIDI or UART connection.
+Start MIDI message.
 
 
 * Author(s): Kevin J. Walters
 
 Implementation Notes
 --------------------
 
-**Hardware:**
-
-
-
-**Software and Dependencies:**
-
-* Adafruit CircuitPython firmware for the supported boards:
-  https://github.com/adafruit/circuitpython/releases
-
 """
 
 from .midi_message import MIDIMessage