add documentation

Add doc strings to public symbols.

src/core/message.rs

@@ -149,6 +149,16 @@ pub enum OnOff {
     Off = 0,
 }
 
+/// A parameter found on most MIDI keyboards that have built-in sounds. Local Control can be set on
+/// or off, and is normally found in the global parameters for a particular instrument. When enabled
+/// the keyboard is electronically connected to the internal sounds of the instrument. This is the
+/// “normal” or default mode for most instruments. When turned off the keyboard only transmits MIDI
+/// to the MIDI out jack. The built-in sounds can then only be accessed from a MIDI input (or an
+/// internal sequencer where applicable). When people use keyboards with external sequencing
+/// equipment local control is normally turned off, and the sounds are just driven through the
+/// sequencer. This prevents a phenomenon known as MIDI echo, where a sound is triggered directly by
+/// the keyboard, and then a very short time later the same note is played again due to the data
+/// being passed through the sequencer.
 #[derive(Clone, Copy, Debug, Default, Eq, PartialEq, Ord, PartialOrd, Hash)]
 pub struct LocalControlValue {
     channel: Channel,
@@ -173,6 +183,8 @@ impl LocalControlValue {
     }
 }
 
+/// When Mono mode is selected, a single voice is assigned per MIDI Channel. This means that only
+/// one note can be played on a given Channel at a given time.
 #[derive(Clone, Copy, Debug, Default, Eq, PartialEq, Ord, PartialOrd, Hash)]
 pub struct MonoModeOnValue {
     channel: Channel,
@@ -230,6 +242,12 @@ pub enum SystemRealtimeMessage {
     SystemReset = 0xff,
 }
 
+/// MIDI System Messages are classified as being System Common Messages, System Real Time Messages,
+/// or System Exclusive Messages. System Common messages are intended for all receivers in the
+/// system. System Real Time messages are used for synchronization between clock-based MIDI
+/// components. System Exclusive messages include a Manufacturer's Identification (ID) code, and are
+/// used to transfer any number of data bytes in a format specified by the referenced manufacturer.
+// TODO - add system exclusive messages (sysex)
 #[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
 #[allow(dead_code)]
 pub enum SystemMessage {
@@ -243,7 +261,14 @@ impl Default for SystemMessage {
     }
 }
 
+/// A MIDI message is made up of an eight-bit status byte which is generally followed by one or two
+/// data bytes. There are a number of different types of MIDI messages. At the highest level, MIDI
+/// messages are classified as being either Channel Messages or System Messages. Channel messages
+/// are those which apply to a specific Channel, and the Channel number is included in the status
+/// byte for these messages. System messages are not Channel specific, and no Channel number is
+/// indicated in their status bytes.
 #[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
+#[allow(missing_docs)]
 pub enum Message {
     NoteOff(NoteMessage),
     NoteOn(NoteMessage),
@@ -520,6 +545,7 @@ where
 /// byte. `Control` values greater than 31 are for the Lsb in these two-byte messages.
 #[repr(u8)]
 #[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Default)]
+#[allow(missing_docs)]
 pub enum Control {
     #[default]
     BankSelect = 0,

src/file/event.rs

@@ -77,6 +77,7 @@ pub struct TrackEvent {
 }
 
 impl TrackEvent {
+    /// Create a new track event.
     pub fn new(delta_time: u32, event: Event) -> Self {
         Self { delta_time, event }
     }

src/lib.rs

@@ -1,3 +1,9 @@
+/*!
+
+A library for reading, writing and creating MIDI files.
+
+!*/
+
 // one per line to simplify commenting certain ones out during development
 #![deny(arithmetic_overflow)]
 #![deny(clippy::complexity)]
@@ -6,7 +12,7 @@
 // TODO - maybe document all pub(crate) types
 // #![deny(missing_crate_level_docs)]
 // TODO - document all
-// #![deny(missing_docs)]
+#![warn(missing_docs)]
 #![deny(nonstandard_style)]
 #![deny(rust_2018_idioms)]
 #![deny(unreachable_patterns)]
@@ -183,6 +189,7 @@ impl MidiFile {
         self.write(&mut scribe)
     }
 
+    /// The number of tracks, i.e. the length of the vector of tracks.
     pub fn tracks_len(&self) -> u32 {
         u32::try_from(self.tracks.len()).unwrap_or(u32::MAX)
     }
@@ -201,6 +208,7 @@ impl MidiFile {
         self.tracks.get(i)
     }
 
+    /// Add a track to the file.
     pub fn push_track(&mut self, track: Track) -> Result<()> {
         ensure!(
             self.tracks_len() < u32::MAX,
@@ -213,6 +221,7 @@ impl MidiFile {
         Ok(())
     }
 
+    /// Insert a track at a certain place in the vector of tracks.
     pub fn insert_track(&mut self, index: u32, track: Track) -> Result<()> {
         ensure!(
             self.tracks_len() < u32::MAX,
@@ -232,6 +241,7 @@ impl MidiFile {
         Ok(())
     }
 
+    /// Remove a track from the file. Same behavior as `vec.remove(index)`.
     pub fn remove_track(&mut self, index: u32) -> Result<Track> {
         ensure!(
             index < self.tracks_len(),