Added rustdoc comments to most public types

Cargo.toml

@@ -20,3 +20,6 @@ usb-device = "0.3.2"
 [dependencies.num_enum]
 version = "0.7.2"
 default-features = false
+
+[lints.rust]
+missing_docs = "warn"

src/data/byte/from_traits.rs

@@ -1,10 +1,14 @@
+//! Traits for type conversions.
+
 /// Like from, but will conceptually overflow if the value is too big
 /// this is useful from going from higher ranges to lower ranges
 pub trait FromOverFlow<T>: Sized {
+    /// Convert with overflowing.
     fn from_overflow(_: T) -> Self;
 }
 
 /// Like from, but will clamp the value to a maximum value
 pub trait FromClamped<T>: Sized {
+    /// Convert with clamping.
     fn from_clamped(_: T) -> Self;
 }

src/data/byte/mod.rs

@@ -1,3 +1,5 @@
+//! Primitive types with bit lengths used in USB MIDI data.
+
 pub mod from_traits;
 pub mod u4;
 pub mod u7;

src/data/byte/u4.rs

@@ -1,6 +1,8 @@
+//! A primitive value with 4-bit length.
+
 use core::convert::TryFrom;
 
-/// A primitive value that can be from 0-0x7F
+/// A primitive value that can be from 0-0x0F
 pub struct U4(u8);
 
 /// Error representing that this value is not a valid u4
@@ -25,7 +27,9 @@ impl From<U4> for u8 {
 }
 
 impl U4 {
+    /// Maximum value for the type.
     pub const MAX: U4 = U4(0x0F);
+    /// Minimum value for the type.
     pub const MIN: U4 = U4(0);
 
     /// Combines two nibbles (u4) eg half byte

src/data/byte/u7.rs

@@ -1,3 +1,5 @@
+//! A primitive value with 7-bit length.
+
 use crate::data::byte::from_traits::{FromClamped, FromOverFlow};
 use core::convert::TryFrom;
 
@@ -44,6 +46,8 @@ impl FromClamped<u8> for U7 {
 }
 
 impl U7 {
+    /// Maximum value for the type.
     pub const MAX: U7 = U7(0x7F);
+    /// Minimum value for the type.
     pub const MIN: U7 = U7(0);
 }

src/data/midi/channel.rs

@@ -1,29 +1,49 @@
+//! Enum representing the MIDI channel.
+
 use core::convert::TryFrom;
 
-/// The Channel is a value ranging from 0x0 to 0xF
-/// This is a standard midi concept
-/// Note Channel1 = 0 on the wire
+/// The Channel is a value ranging from 0x0 to 0xF.
+///
+/// This is a standard midi concept.
+/// Note Channel1 = 0 on the wire.
 #[derive(Debug, Copy, Clone, Eq, PartialEq)]
 #[repr(u8)]
 pub enum Channel {
+    /// MIDI channel 1.
     Channel1 = 0x0,
+    /// MIDI channel 2.
     Channel2 = 0x1,
+    /// MIDI channel 3.
     Channel3 = 0x2,
+    /// MIDI channel 4.
     Channel4 = 0x3,
+    /// MIDI channel 5.
     Channel5 = 0x4,
+    /// MIDI channel 6.
     Channel6 = 0x5,
+    /// MIDI channel 7.
     Channel7 = 0x6,
+    /// MIDI channel 8.
     Channel8 = 0x7,
+    /// MIDI channel 9.
     Channel9 = 0x8,
+    /// MIDI channel 10.
     Channel10 = 0x9,
+    /// MIDI channel 11.
     Channel11 = 0xA,
+    /// MIDI channel 12.
     Channel12 = 0xB,
+    /// MIDI channel 13.
     Channel13 = 0xC,
+    /// MIDI channel 14.
     Channel14 = 0xD,
+    /// MIDI channel 15.
     Channel15 = 0xE,
+    /// MIDI channel 16.
     Channel16 = 0xF,
 }
 
+/// Error indicating an invalid MIDI channel.
 pub struct InvalidChannel(u8);
 
 impl TryFrom<u8> for Channel {

src/data/midi/message/control_function.rs

@@ -1,10 +1,15 @@
+//! Control function definitions.
+
 use crate::data::byte::u7::U7;
 
+/// Custom type for a control function.
 #[derive(Debug, Eq, PartialEq)]
 pub struct ControlFunction(pub U7);
 
-/// Control Functions as defined in the MIDI 1.0 Specification
-/// Source: https://www.midi.org/specifications-old/item/table-3-control-change-messages-data-bytes-2
+/// Control Functions as defined in the MIDI 1.0 Specification.
+///
+/// Source: <https://www.midi.org/specifications-old/item/table-3-control-change-messages-data-bytes-2>
+#[allow(missing_docs)]
 impl ControlFunction {
     pub const BANK_SELECT_0: Self = ControlFunction(U7(0));
     pub const MOD_WHEEL_1: Self = ControlFunction(U7(1));

src/data/midi/message/mod.rs

@@ -1,3 +1,5 @@
+//! Enum representing the MIDI message.
+
 pub mod control_function;
 pub mod raw;
 
@@ -12,18 +14,26 @@ use core::convert::TryFrom;
 
 type Velocity = U7;
 
-/// Represents midi messages
+/// Represents midi messages.
+///
 /// Note: not current exhaustive and SysEx messages end up
 /// being a confusing case. So are currently note implemented
 /// they are sort-of unbounded
 #[derive(Debug, Eq, PartialEq)]
 pub enum Message {
+    /// Note On message.
     NoteOff(Channel, Note, Velocity),
+    /// Note Off message.
     NoteOn(Channel, Note, Velocity),
+    /// Polyphonic aftertouch (poly-pressure) message.
     PolyphonicAftertouch(Channel, Note, U7),
+    /// Program change message.
     ProgramChange(Channel, U7),
+    /// Channel aftertouch message.
     ChannelAftertouch(Channel, U7),
+    /// Pitchwheel message.
     PitchWheelChange(Channel, U7, U7),
+    /// Control Change (CC) message.
     ControlChange(Channel, ControlFunction, U7),
 }
 

src/data/midi/message/raw.rs

@@ -1,18 +1,24 @@
+//! Type for the raw MIDI message.
+
 use crate::data::byte::u7::U7;
 
-/// Represents the payloads that the midi message may contain
+/// Represents the payloads that the midi message may contain.
 pub enum Payload {
+    /// No payload.
     Empty,
+    /// One-byte payload.
     SingleByte(U7),
+    /// Two-byte payload.
     DoubleByte(U7, U7),
 }
 
-/// A struct that captures the valid states
-/// a midi message may be in, but without domain logic
-/// mainly useful for serializing.
-/// This represents the possible 'shapes', doesn't verify if
-/// the data makes sense though!
+/// A struct that captures the valid states.
+///
+/// A midi message may be in, but without domain logic mainly useful for serializing.
+/// This represents the possible 'shapes', doesn't verify if the data makes sense though!
 pub struct Raw {
+    /// Status byte.
     pub status: u8,
+    /// Payload of maximum 2 bytes.
     pub payload: Payload,
 }

src/data/midi/mod.rs

@@ -1,3 +1,5 @@
+//! MIDI message and related types.
+
 pub mod channel;
 pub mod message;
 pub mod notes;

src/data/midi/notes.rs

@@ -1,10 +1,15 @@
+//! Enum representing the MIDI notes.
+
 use crate::data::byte::from_traits::FromOverFlow;
 use crate::data::byte::u7::U7;
 use num_enum::TryFromPrimitive;
-/// A simple enum type that represents all the midi 'notes'
-/// note the flat versions are associated constants
+
+/// A simple enum type that represents all the midi 'notes'.
+///
+/// Note the flat versions are associated constants
 /// but can be referenced like Note::Bb3
 /// C1m is the C-1
+#[allow(missing_docs)]
 #[derive(Debug, Copy, Clone, TryFromPrimitive, Eq, PartialEq)]
 #[repr(u8)]
 pub enum Note {
@@ -152,6 +157,7 @@ impl From<Note> for U7 {
     }
 }
 
+#[allow(missing_docs)]
 impl Note {
     #[allow(non_upper_case_globals)]
     pub const Db1m: Note = Note::Cs1m;

src/data/mod.rs

@@ -1,3 +1,5 @@
+//! Primitives and structures used in USB MIDI data.
+
 pub mod byte;
 pub mod midi;
 pub mod usb;

src/data/usb/constants.rs

@@ -1,4 +1,8 @@
-//This should be better organized in future
+//! Constants for use in USB descriptors.
+
+#![allow(missing_docs)]
+
+// TODO: this should be better organized in future.
 
 pub const USB_CLASS_NONE: u8 = 0x00;
 pub const USB_AUDIO_CLASS: u8 = 0x01;

src/data/usb/mod.rs

@@ -1 +1,3 @@
+//! General items used for USB communication.
+
 pub mod constants;

src/data/usb_midi/cable_number.rs

@@ -1,9 +1,12 @@
+//! Enum representing the cable number of a packet.
+
 use crate::data::byte::u4::U4;
 use core::convert::TryFrom;
 
 /// The Cable Number (CN) is a value ranging from 0x0 to 0xF
 /// indicating the number assignment of the Embedded MIDI Jack associated
 /// with the endpoint that is transferring the data
+#[allow(missing_docs)]
 #[derive(Debug, Clone, Copy, Eq, PartialEq)]
 #[repr(u8)]
 pub enum CableNumber {
@@ -24,6 +27,8 @@ pub enum CableNumber {
     Cable14 = 0xE,
     Cable15 = 0xF,
 }
+
+/// Error indicating an invalid cable number.
 pub struct InvalidCableNumber(u8);
 
 impl TryFrom<u8> for CableNumber {

src/data/usb_midi/code_index_number.rs

@@ -1,10 +1,14 @@
+//! Enum representing the code index number of a packet.
+
 use crate::data::byte::u4::U4;
 use crate::data::midi::message::Message;
 use core::convert::TryFrom;
 
 /// The Code Index Number(CIN) indicates the classification
 /// of the bytes in the MIDI_x fields
 pub struct CodeIndexNumber(u8);
+
+/// Error indicating an invalid code index number.
 pub struct InvalidCodeIndexNumber(u8);
 
 impl TryFrom<u8> for CodeIndexNumber {
@@ -25,24 +29,25 @@ impl From<CodeIndexNumber> for U4 {
 }
 
 impl CodeIndexNumber {
-    /// Miscellaneous function codes. Reserved for future extensions
+    /// Miscellaneous function codes. Reserved for future extensions.
     pub const MISC_FUNCTION: CodeIndexNumber = CodeIndexNumber(0x00);
     /// Cable events. Reserved for future expansion.
     pub const CABLE_EVENTS: CodeIndexNumber = CodeIndexNumber(0x1);
     /// Two-byte System Common messages like MTC, SongSelect, etc.
     pub const SYSTEM_COMMON_LEN2: CodeIndexNumber = CodeIndexNumber(0x2);
     /// Three-byte System Common messages like SPP, etc.
     pub const SYSTEM_COMMON_LEN3: CodeIndexNumber = CodeIndexNumber(0x3);
-    /// SysEx starts or continues
+    /// SysEx starts.
     pub const SYSEX_STARTS: CodeIndexNumber = CodeIndexNumber(0x4);
+    /// SysEx continues.
     pub const SYSEX_CONTINUES: CodeIndexNumber = CodeIndexNumber::SYSEX_STARTS;
     /// Single-byte System Common Message or SysEx ends with following single byte.
     pub const SYSTEM_COMMON_LEN1: CodeIndexNumber = CodeIndexNumber(0x5);
-    /// SysEx ends with the following byte
+    /// SysEx ends with the following byte.
     pub const SYSEX_ENDS_NEXT1: CodeIndexNumber = CodeIndexNumber::SYSTEM_COMMON_LEN1;
-    /// SysEx ends with following two bytes
+    /// SysEx ends with following two bytes.
     pub const SYSEX_ENDS_NEXT2: CodeIndexNumber = CodeIndexNumber(0x6);
-    /// SysEx ends with following three bytes
+    /// SysEx ends with following three bytes.
     pub const SYSEX_ENDS_NEXT3: CodeIndexNumber = CodeIndexNumber(0x7);
     /// Note - Off
     pub const NOTE_OFF: CodeIndexNumber = CodeIndexNumber(0x8);
@@ -61,6 +66,7 @@ impl CodeIndexNumber {
     /// Single Byte
     pub const SINGLE_BYTE: CodeIndexNumber = CodeIndexNumber(0xF);
 
+    /// Determines the code index number of a message and returns it.
     pub fn find_from_message(value: &Message) -> CodeIndexNumber {
         match value {
             Message::NoteOn(_, _, _) => CodeIndexNumber::NOTE_ON,

src/data/usb_midi/midi_packet_reader.rs

@@ -1,14 +1,18 @@
+//! Reader for received packets.
+
 use crate::data::usb_midi::usb_midi_event_packet::{MidiPacketParsingError, UsbMidiEventPacket};
 use crate::midi_device::{MAX_PACKET_SIZE, MIDI_PACKET_SIZE};
 use core::convert::TryFrom;
 
+/// Packet reader with internal buffer for received message.
 pub struct MidiPacketBufferReader<'a> {
     buffer: &'a [u8; MAX_PACKET_SIZE],
     position: usize,
     raw_bytes_received: usize,
 }
 
 impl<'a> MidiPacketBufferReader<'a> {
+    /// Creates a new reader.
     pub fn new(buffer: &'a [u8; MAX_PACKET_SIZE], raw_bytes_received: usize) -> Self {
         MidiPacketBufferReader {
             buffer,

src/data/usb_midi/mod.rs

@@ -1,3 +1,5 @@
+//! USB MIDI event packet parser and related types.
+
 pub mod cable_number;
 pub mod code_index_number;
 pub mod midi_packet_reader;

src/data/usb_midi/usb_midi_event_packet.rs

@@ -1,16 +1,21 @@
+//! Representation of a USB MIDI event packet.
+
 use crate::data::byte::u4::U4;
 use crate::data::midi::message::raw::{Payload, Raw};
 use crate::data::midi::message::Message;
 use crate::data::usb_midi::cable_number::CableNumber;
 use crate::data::usb_midi::code_index_number::CodeIndexNumber;
 use core::convert::TryFrom;
 
-/// A packet that communicates with the host
+/// A packet that communicates with the host.
+///
 /// Currently supported is sending the specified normal midi
 /// message over the supplied cable number
 #[derive(Debug, Eq, PartialEq)]
 pub struct UsbMidiEventPacket {
+    /// Cable number of the packet.
     pub cable_number: CableNumber,
+    /// Message payload.
     pub message: Message,
 }
 
@@ -35,11 +40,16 @@ impl From<UsbMidiEventPacket> for [u8; 4] {
     }
 }
 
+/// Error variants for parsing the packet.
 #[derive(Debug)]
 pub enum MidiPacketParsingError {
+    /// Invalid note.
     InvalidNote(u8),
+    /// Invalid cable number.
     InvalidCableNumber(u8),
+    /// Invalid event type.
     InvalidEventType(u8),
+    /// Missing data packet.
     MissingDataPacket,
 }
 
@@ -72,6 +82,7 @@ impl TryFrom<&[u8]> for UsbMidiEventPacket {
 }
 
 impl UsbMidiEventPacket {
+    /// Creates a packet from a MIDI message and returns it.
     pub fn from_midi(cable: CableNumber, midi: Message) -> UsbMidiEventPacket {
         UsbMidiEventPacket {
             cable_number: cable,