Update all context mod documentation

amm_sdk/src/context/clef.rs

@@ -9,12 +9,18 @@ use wasm_bindgen::prelude::*;
 #[cfg_attr(target_arch = "wasm32", wasm_bindgen)]
 #[derive(Copy, Clone, Debug, Default, Eq, PartialEq, JsonDeserialize, JsonSerialize)]
 pub enum ClefSymbol {
-  /// ![G Clef](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/g-clef.png)
+  /// ![G Clef](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/clef-G.png)
+  /// 
+  /// The middle curl of the G clef wraps around the staff line used to notate a pitch of G4.
   #[default]
   GClef,
-  /// ![C Clef](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/c-clef.png)
+  /// ![C Clef](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/clef-C.png)
+  /// 
+  /// The middle of the C clef indicates the staff line used to notate a pitch of C4 (middle C).
   CClef,
-  /// ![F Clef](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/f-clef.png)
+  /// ![F Clef](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/clef-F.png)
+  /// 
+  /// The two dots of the F clef surround the staff line used to notate a pitch of F3.
   FClef,
 }
 

amm_sdk/src/context/dynamic.rs

@@ -4,19 +4,31 @@ use amm_macros::{JsonDeserialize, JsonSerialize};
 /// Represents a dynamic marking in music notation.
 #[derive(Copy, Clone, Debug, Default, Eq, PartialEq, JsonDeserialize, JsonSerialize)]
 pub enum Dynamic {
-  /// ![Forte](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/forte.png)
+  /// ![Forte](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/f.png)
   ///
-  /// The magnitude of the dynamic marking is specified by the `u8` value.
+  /// A `forte` dynamic marking indicates that corresponding music should be played
+  /// relatively loudly.
+  /// 
+  /// The magnitude of the notated forte is specified by the `u8` value.
   /// For example, `Forte(3)` represents a dynamic marking of `fff`.
   Forte(u8),
   #[default]
-  /// ![Mezzo Forte](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/mezzo-forte.png)
+  /// ![Mezzo Forte](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/mf.png)
+  /// 
+  /// A `mezzo-forte` dynamic marking indicates that corresponding music should be played
+  /// only slightly louder than average.
   MezzoForte,
-  /// ![Mezzo Piano](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/mezzo-piano.png)
+  /// ![Mezzo Piano](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/mp.png)
+  /// 
+  /// A `mezzo-piano` dynamic marking indicates that corresponding music should be played
+  /// only slightly softer than average.
   MezzoPiano,
-  /// ![Piano](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/piano.png)
+  /// ![Piano](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/p.png)
   ///
-  /// The magnitude of the dynamic marking is specified by the `u8` value.
+  /// A `piano` dynamic marking indicates that corresponding music should be played
+  /// relatively softly.
+  /// 
+  /// The magnitude of the notated piano is specified by the `u8` value.
   /// For example, `Piano(3)` represents a dynamic marking of `ppp`.
   Piano(u8),
 }

amm_sdk/src/context/key.rs

@@ -36,7 +36,7 @@ const FIFTHS_D_SHARP_MINOR: i8 = 6;
 const FIFTHS_E_MINOR: i8 = 1;
 const FIFTHS_E_FLAT_MINOR: i8 = -6;
 
-/// Represents the relative interval between notes in musical scale.
+/// Represents the relative intervals between notes in a musical scale.
 #[cfg_attr(target_arch = "wasm32", wasm_bindgen)]
 #[derive(Copy, Clone, Debug, Default, Eq, PartialEq, JsonDeserialize, JsonSerialize)]
 pub enum KeyMode {
@@ -54,57 +54,57 @@ pub enum KeyMode {
 }
 
 /// Represents the key signature of a musical piece, not taking
-/// into account its mode (i.e., major or minor).
+/// into account its mode (i.e., major, minor, etc.).
 #[cfg_attr(target_arch = "wasm32", wasm_bindgen)]
 #[derive(Copy, Clone, Debug, Default, Eq, PartialEq, JsonDeserialize, JsonSerialize)]
 pub enum KeySignature {
-  /// ![Key of A](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/key-a.png)
+  /// The key of A is defined by a scale with a root note (tonic) of A.
   A,
-  /// ![Key of A#](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/key-a-sharp.png)
+  /// The key of A# is defined by a scale with a root note (tonic) of A#.
   ASharp,
-  /// ![Key of A♭](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/key-a-flat.png)
+  /// The key of A♭ is defined by a scale with a root note (tonic) of A♭.
   AFlat,
-  /// ![Key of B](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/key-b.png)
+  /// The key of B is defined by a scale with a root note (tonic) of B.
   B,
-  /// ![Key of B♭](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/key-b-flat.png)
+  /// The key of B♭ is defined by a scale with a root note (tonic) of B♭.
   BFlat,
-  /// ![Key of C](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/key-c.png)
+  /// The key of C is defined by a scale with a root note (tonic) of C.
   #[default]
   C,
-  /// ![Key of C#](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/key-c-sharp.png)
+  /// The key of C# is defined by a scale with a root note (tonic) of C#.
   CSharp,
-  /// ![Key of C♭](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/key-c-flat.png)
+  /// The key of C♭ is defined by a scale with a root note (tonic) of C♭.
   CFlat,
-  /// ![Key of D](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/key-d.png)
+  /// The key of D is defined by a scale with a root note (tonic) of D.
   D,
-  /// ![Key of D#](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/key-d-sharp.png)
+  /// The key of D# is defined by a scale with a root note (tonic) of D#.
   DSharp,
-  /// ![Key of D♭](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/key-d-flat.png)
+  /// The key of D♭ is defined by a scale with a root note (tonic) of D♭.
   DFlat,
-  /// ![Key of E](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/key-e.png)
+  /// The key of E is defined by a scale with a root note (tonic) of E.
   E,
-  /// ![Key of E♭](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/key-e-flat.png)
+  /// The key of E♭ is defined by a scale with a root note (tonic) of E♭.
   EFlat,
-  /// ![Key of F](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/key-f.png)
+  /// The key of F is defined by a scale with a root note (tonic) of F.
   F,
-  /// ![Key of F#](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/key-f-sharp.png)
+  /// The key of F# is defined by a scale with a root note (tonic) of F#.
   FSharp,
-  /// ![Key of G](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/key-g.png)
+  /// The key of G is defined by a scale with a root note (tonic) of G.
   G,
-  /// ![Key of G#](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/key-g-sharp.png)
+  /// The key of G# is defined by a scale with a root note (tonic) of G#.
   GSharp,
-  /// ![Key of G♭](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/key-g-flat.png)
+  /// The key of G♭ is defined by a scale with a root note (tonic) of G♭.
   GFlat,
 }
 
 /// Represents the key of a musical piece, including both its
-/// mode (i.e., major or minor) and its signature.
+/// mode (i.e., major, minor, etc.) and its signature (defining root note).
 #[cfg_attr(target_arch = "wasm32", wasm_bindgen)]
 #[derive(Copy, Clone, Debug, Default, Eq, PartialEq, JsonDeserialize, JsonSerialize)]
 pub struct Key {
-  /// The mode of the key (i.e., major or minor).
+  /// The mode of the key (i.e., major, minor, etc.).
   pub mode: KeyMode,
-  /// The signature of the key (i.e., A, A♭, B, etc).
+  /// The defining root note of the key (i.e., A, A♭, B, etc).
   pub signature: KeySignature,
 }
 
@@ -194,7 +194,7 @@ impl Key {
     }
   }
 
-  /// Returns a new key with the same tonic as the current key,
+  /// Returns a new key with the same tonic (root note) as the current key,
   /// but with the opposite mode (i.e., the parallel key of C-Major
   /// would be C-Minor and vice versa).
   #[must_use]
@@ -224,8 +224,8 @@ impl Key {
 
   /// Converts the current key into its parallel key.
   ///
-  /// A parallel key is a key with the same tonic as the current key,
-  /// but with the opposite mode (i.e., the parallel key of C-Major
+  /// A parallel key is a key with the same tonic (root note) as the current
+  /// key, but with the opposite mode (i.e., the parallel key of C-Major
   /// would be C-Minor and vice versa).
   pub fn make_parallel(&mut self) {
     self.mode = if self.mode == KeyMode::Major {

amm_sdk/src/context/mod.rs

@@ -1,3 +1,6 @@
+//! This module contains all of the data types used to represent
+//! the contextual content and information in a music score.
+
 mod clef;
 mod dynamic;
 mod id;

amm_sdk/src/context/tempo.rs

@@ -8,7 +8,7 @@ use wasm_bindgen::prelude::*;
 #[cfg_attr(target_arch = "wasm32", wasm_bindgen)]
 #[derive(Copy, Clone, Debug, Eq, PartialEq, JsonDeserialize, JsonSerialize)]
 pub struct Tempo {
-  /// The base note which represents a "beat" in the tempo.
+  /// The base note which represents a single "beat" in the tempo.
   pub base_note: Duration,
   /// The number of beats per minute.
   pub beats_per_minute: u16,

amm_sdk/src/context/tempo_suggestion.rs

@@ -67,7 +67,7 @@ impl TempoSuggestion {
     Self { marking }
   }
 
-  /// Returns a description of the tempo suggestion.
+  /// Returns a textual description of the tempo suggestion.
   #[must_use]
   pub fn description(&self) -> String {
     String::from(match self.marking {
@@ -95,7 +95,8 @@ impl TempoSuggestion {
     })
   }
 
-  /// Returns the minimum beats per minute for the tempo suggestion.
+  /// Returns the minimum beats per minute that the tempo suggestion is
+  /// likely to represent.
   #[must_use]
   pub fn bpm_min(&self) -> u16 {
     match self.marking {
@@ -121,7 +122,8 @@ impl TempoSuggestion {
     }
   }
 
-  /// Returns the maximum beats per minute for the tempo suggestion.
+  /// Returns the maximum beats per minute that the tempo suggestion is
+  /// likely to represent.
   #[must_use]
   pub fn bpm_max(&self) -> u16 {
     match self.marking {
@@ -142,7 +144,8 @@ impl TempoSuggestion {
     }
   }
 
-  /// Returns the average beats per minute for the tempo suggestion.
+  /// Returns the average beats per minute that the tempo suggestion is
+  /// likely to represent.
   #[must_use]
   pub fn value(&self) -> u16 {
     match self.marking {

amm_sdk/src/context/time_signature.rs

@@ -7,19 +7,20 @@ use wasm_bindgen::prelude::*;
 #[cfg_attr(target_arch = "wasm32", wasm_bindgen)]
 #[derive(Copy, Clone, Debug, Default, Eq, PartialEq, JsonDeserialize, JsonSerialize)]
 pub enum TimeSignatureType {
-  /// ![Common Time](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/common-time.png)
+  /// ![Common Time](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/time-symbol-common.png)
   ///
-  /// Represents an explicit time signature of 4/4.
+  /// Equivalent to a [`TimeSignatureType::Explicit`] time signature of 4/4.
   #[default]
   CommonTime,
-  /// ![Cut Time](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/cut-time.png)
+  /// ![Cut Time](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/time-symbol-cut.png)
   ///
-  /// Represents an explicit time signature of 2/2.
+  /// Equivalent to a [`TimeSignatureType::Explicit`] time signature of 2/2.
   CutTime,
-  /// ![Explicit Time](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/explicit-time.png)
+  /// ![Explicit Time](https://hedgetechllc.github.io/amm-sdk/amm_sdk/images/time-symbol-normal.png)
   ///
-  /// Represents the number of beats in each measure and the
-  /// note value which represents a beat.
+  /// Represents the number of beats in each measure (numerator) and the
+  /// note value which represents a beat (denominator). For example, `3/4`
+  /// represents 3 beats per measure, with a quarter note receiving one beat.
   Explicit,
   /// Represents an explicit lack of time signature,
   /// also called "senza misura".
@@ -67,10 +68,10 @@ impl TimeSignature {
     }
   }
 
-  /// Creates a new time signature with the given *explicit* type.
+  /// Creates a new time signature with the given *explicit* value.
   ///
   /// The `numerator` indicates the number of beats in each measure,
-  /// and the `denominator` designates the note value which represents
+  /// and the `denominator` designates the note value that represents
   /// a beat in the measure (e.g., `4` = quarter note, `8` = eighth note,
   /// etc.).
   #[must_use]