From cee5044ad37ec2a1f92828d61f24e095108ca2b6 Mon Sep 17 00:00:00 2001
From: VLAD EMINOVICI <veminovici@hotmail.com>
Date: Sun, 17 Mar 2024 21:56:50 +0200
Subject: [PATCH] Extract the consts and add comments

---
 src/note.rs | 89 +++++++++++++++++++++++++++++++++++++++++++++--------
 src/tone.rs |  7 +++++
 2 files changed, 84 insertions(+), 12 deletions(-)

diff --git a/src/note.rs b/src/note.rs
index e277e18..a4c6a6d 100644
--- a/src/note.rs
+++ b/src/note.rs
@@ -11,18 +11,19 @@ use super::{Tone, OCTAVE};
 pub struct Note(i8);
 
 impl Note {
-    pub fn base(&self) -> Self {
-        const M: i8 = 3;
-        let o = u8::from(OCTAVE) as i8;
+    const M: i8 = 3;
+    const O: i8 = OCTAVE.inner() as i8;
 
-        let mut note = self.0 + M;
+    /// Returns the base note (the one in the C4 octave)
+    pub fn base(&self) -> Self {
+        let mut note = self.0 + Self::M;
         if note < 0 {
-            let p = note / o;
-            note += (p.abs() + 1) * o;
+            let p = note / Self::O;
+            note += (p.abs() + 1) * Self::O;
         }
 
-        note %= o;
-        note -= M;
+        note %= Self::O;
+        note -= Self::M;
 
         let b: Self = note.into();
         debug_assert_eq!(
@@ -35,13 +36,14 @@ impl Note {
         b
     }
 
+    /// Returns the octave for the given note (eg. C4)
     pub fn octave(&self) -> i8 {
-        let octave = (self.0 + 3) / u8::from(OCTAVE) as i8;
-        let rest = (self.0 + 3) % u8::from(OCTAVE) as i8;
+        let octave = (self.0 + Self::M) / Self::O;
+        let rest = (self.0 + Self::M) % Self::O;
         if rest >= 0 {
-            octave + 4
+            octave + Self::M + 1
         } else {
-            octave + 3
+            octave + Self::M
         }
     }
 
@@ -49,30 +51,93 @@ impl Note {
     // Functions which build chords
     //
 
+    /// Builds a diminished7 chord with the root in the current note.
+    ///
+    /// # Example
+    /// ```
+    /// use musika_rs::*;
+    ///
+    /// let chord = C.diminished7();
+    /// println!("{:X}", chord);
+    /// ```
     pub fn diminished7(self) -> chords::Diminished7 {
         chords::Diminished7::from(self)
     }
 
+    /// Builds a dominant7 choard with the root in the current note.
+    ///
+    /// # Example
+    /// ```
+    /// use musika_rs::*;
+    ///
+    /// let chord = C.dominant7();
+    /// println!("{:X}", chord);
+    /// ```
     pub fn dominant7(self) -> chords::Dominant7 {
         chords::Dominant7::from(self)
     }
 
+    /// Builds a major chord with the root in the current note.
+    ///
+    /// # Example
+    /// ```
+    /// use musika_rs::*;
+    ///
+    /// let chord = C.major();
+    /// println!("{:X}", chord);
+    /// ```
     pub fn major(self) -> chords::Major {
         chords::Major::from(self)
     }
 
+    /// Builds a major7 chord with the root in the current note.
+    ///
+    /// # Example
+    /// ```
+    /// use musika_rs::*;
+    ///
+    /// let chord = C.major7();
+    /// println!("{:X}", chord);
+    /// ```
     pub fn major7(self) -> chords::Major7 {
         chords::Major7::from(self)
     }
 
+    /// Builds a minor chord with the root in the current note.
+    ///
+    /// # Example
+    /// ```
+    /// use musika_rs::*;
+    ///
+    /// let chord = C.minor();
+    /// println!("{:X}", chord);
+    /// ```
     pub fn minor(self) -> chords::Minor {
         chords::Minor::from(self)
     }
 
+    /// Builds a minor7 chord with the root in the current note.
+    ///
+    /// # Example
+    /// ```
+    /// use musika_rs::*;
+    ///
+    /// let chord = C.minor7();
+    /// println!("{:X}", chord);
+    /// ```
     pub fn minor7(self) -> chords::Minor7 {
         chords::Minor7::from(self)
     }
 
+    /// Builds a minor7b5 chord with the root in the current note.
+    ///
+    /// # Example
+    /// ```
+    /// use musika_rs::*;
+    ///
+    /// let chord = C.minor7b5();
+    /// println!("{:X}", chord);
+    /// ```
     pub fn minor7b5(self) -> chords::Minor7b5 {
         chords::Minor7b5::from(self)
     }
diff --git a/src/tone.rs b/src/tone.rs
index c3e6218..97da52c 100644
--- a/src/tone.rs
+++ b/src/tone.rs
@@ -3,6 +3,13 @@ use std::fmt::{Debug, Display};
 #[derive(PartialEq, Eq, PartialOrd, Ord)]
 pub struct Tone(u8);
 
+impl Tone {
+    /// Returns the inner value of the tone.
+    pub(crate) const fn inner(&self) -> u8 {
+        self.0
+    }
+}
+
 pub const SEMI_TONE: Tone = Tone(1);
 pub const TONE: Tone = Tone(2);
 pub const OCTAVE: Tone = Tone(12);