From 0c16a3c3bbb04b87573f9af9b5dc9b13b50e274d Mon Sep 17 00:00:00 2001 From: Will Hedgecock Date: Mon, 18 Nov 2024 23:02:48 -0600 Subject: [PATCH] Update all context mod documentation --- amm_sdk/src/context/clef.rs | 12 ++++-- amm_sdk/src/context/dynamic.rs | 24 +++++++++--- amm_sdk/src/context/key.rs | 52 ++++++++++++------------- amm_sdk/src/context/mod.rs | 3 ++ amm_sdk/src/context/tempo.rs | 2 +- amm_sdk/src/context/tempo_suggestion.rs | 11 ++++-- amm_sdk/src/context/time_signature.rs | 19 ++++----- 7 files changed, 74 insertions(+), 49 deletions(-) diff --git a/amm_sdk/src/context/clef.rs b/amm_sdk/src/context/clef.rs index 93fbc87..9c3ad71 100644 --- a/amm_sdk/src/context/clef.rs +++ b/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, } diff --git a/amm_sdk/src/context/dynamic.rs b/amm_sdk/src/context/dynamic.rs index 40b5c87..c0cc7e2 100644 --- a/amm_sdk/src/context/dynamic.rs +++ b/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), } diff --git a/amm_sdk/src/context/key.rs b/amm_sdk/src/context/key.rs index 53a9d04..f98f05b 100644 --- a/amm_sdk/src/context/key.rs +++ b/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 { diff --git a/amm_sdk/src/context/mod.rs b/amm_sdk/src/context/mod.rs index 33ac3af..748721a 100644 --- a/amm_sdk/src/context/mod.rs +++ b/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; diff --git a/amm_sdk/src/context/tempo.rs b/amm_sdk/src/context/tempo.rs index fea9f79..164ff89 100644 --- a/amm_sdk/src/context/tempo.rs +++ b/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, diff --git a/amm_sdk/src/context/tempo_suggestion.rs b/amm_sdk/src/context/tempo_suggestion.rs index 33455b0..3bac4e4 100644 --- a/amm_sdk/src/context/tempo_suggestion.rs +++ b/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 { diff --git a/amm_sdk/src/context/time_signature.rs b/amm_sdk/src/context/time_signature.rs index 96f4456..2eada0a 100644 --- a/amm_sdk/src/context/time_signature.rs +++ b/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]