code and docs cleanup

examples/4_load_rtttl_melody/4_load_rtttl_melody.ino

@@ -1,5 +1,5 @@
 /**
- * Load an RTTTL melody from hardcoded literal string and from file.
+ * Load and play an RTTTL melody from hardcoded literal string and from file.
  */
 #include <melody_player.h>
 #include <melody_factory.h>
@@ -23,11 +23,11 @@ void setup() {
   Serial.println("Melody Player - Load RTTTL melody");
 
   Serial.print("Loading hardcoded melody... ");
-  Melody melody2 = MelodyFactory.loadRtttlString(melodyString);
-  if (melody2) {
+  Melody melody = MelodyFactory.loadRtttlString(melodyString);
+  if (melody) {
     Serial.println("Done!");
     Serial.print("Playing... ");
-    player.play(melody2);
+    player.play(melody);
     Serial.println("Done!");
   } else {
     Serial.println("Error");
@@ -40,7 +40,7 @@ void setup() {
   SPIFFS.begin();
 
   Serial.print("Loading melody from file... ");
-  Melody melody = MelodyFactory.loadRtttlFile(melodyFilePath);
+  melody = MelodyFactory.loadRtttlFile(melodyFilePath);
   if (!melody) {
     Serial.println("Error");
   } else {

src/melody_factory.cpp

@@ -61,7 +61,7 @@ Melody MelodyFactoryClass::load(String filepath, FS& fs) {
     notes->reserve(nNotes);
     bool error = false;
     while (f.available() && notes->size() < nNotes && !error) {
-      // let's try to read a token
+      // get a token
       String noteDuration = f.readStringUntil('|');
       error = !loadNote(noteDuration);
     }

src/melody_factory.h

@@ -77,7 +77,7 @@ class MelodyFactoryClass {
 
   ///////////// RTTTL helpers
   /**
-   * It is the default duration of a note. For example,
+   * The default duration of a note. For example,
    * "4" means that each note with no duration specifier
    * is by default considered a quarter note. Possibile values:
    * 1 - whole note
@@ -97,7 +97,8 @@ class MelodyFactoryClass {
   unsigned short octave;
 
   /**
-   * Beats per minute (BPM).
+   * The default BPM (beats per minute) value. BPM is arbitrarily limited between 10 and 300. Look
+   * at the implementation of parseBeat for more info.
    */
   const unsigned short defaultBeat = 63;
   unsigned short beat;

src/melody_player.cpp

@@ -71,9 +71,9 @@ void changeTone(MelodyPlayer* player) {
       < player->melodyState->melody.getLength()) {
     NoteDuration computedNote(player->melodyState->getCurrentComputedNote());
 
-    float duration = player->melodyState->getRemainingDuration();
+    float duration = player->melodyState->getRemainingNoteDuration();
     if (duration > 0) {
-      player->melodyState->resetRemainingDuration();
+      player->melodyState->resetRemainingNoteDuration();
     } else {
       if (player->melodyState->isSilence()) {
         duration = 0.3f * computedNote.duration;
@@ -149,7 +149,7 @@ void MelodyPlayer::pause() {
 
   haltPlay();
   state = State::PAUSE;
-  melodyState->saveRemainingDuration(supportSemiNote);
+  melodyState->saveRemainingNoteDuration(supportSemiNote);
 }
 
 void MelodyPlayer::transferMelodyTo(MelodyPlayer& destPlayer) {
@@ -161,7 +161,7 @@ void MelodyPlayer::transferMelodyTo(MelodyPlayer& destPlayer) {
 
   haltPlay();
   state = State::STOP;
-  melodyState->saveRemainingDuration(supportSemiNote);
+  melodyState->saveRemainingNoteDuration(supportSemiNote);
   destPlayer.melodyState = std::move(melodyState);
 
   if (playing) {
@@ -176,7 +176,7 @@ void MelodyPlayer::duplicateMelodyTo(MelodyPlayer& destPlayer) {
 
   destPlayer.stop();
   destPlayer.melodyState = make_unique<MelodyState>(*(this->melodyState));
-  destPlayer.melodyState->saveRemainingDuration(supportSemiNote);
+  destPlayer.melodyState->saveRemainingNoteDuration(supportSemiNote);
 
   if (isPlaying()) {
     destPlayer.playAsync();
@@ -220,8 +220,8 @@ void MelodyPlayer::turnOff() {
   ledcWrite(pwmChannel, 0);
   ledcDetachPin(pin);
 #else
-  // Remember that this will set LOW output,
-  // it doesn't mean that buzzer is off.
+  // Remember that this will set LOW output, it doesn't mean that buzzer is off (look at offLevel
+  // for more info).
   noTone(pin);
 #endif
 

src/melody_player.h

@@ -82,8 +82,8 @@ class MelodyPlayer {
 
   /**
    * Move the current melody and player's state to the given destination Player.
-   * The source player stops and lose the reference to the actual melody. You have to call
-   * play(Melody) to make it play again.
+   * The source player stops and lose the reference to the actual melody (i.e. you have to call
+   * play(Melody) to make the source player play again).
    */
   void transferMelodyTo(MelodyPlayer& destination);
 
@@ -112,13 +112,13 @@ class MelodyPlayer {
   bool offLevel;
 
   /**
-   * Store the current state of a Melody.
+   * Store the playback state of a melody and provide the methods to control it.
    */
   class MelodyState {
   public:
-    MelodyState() : first(true), index(0), partialNoteReproduction(0){};
+    MelodyState() : first(true), index(0), remainingNoteTime(0){};
     MelodyState(const Melody& melody)
-      : melody(melody), first(true), silence(false), index(0), partialNoteReproduction(0){};
+      : melody(melody), first(true), silence(false), index(0), remainingNoteTime(0){};
     Melody melody;
 
     unsigned short getIndex() const {
@@ -138,7 +138,7 @@ class MelodyPlayer {
         first = false;
         return;
       }
-      if (partialNoteReproduction != 0) { return; }
+      if (remainingNoteTime != 0) { return; }
 
       if (melody.getAutomaticSilence()) {
         if (silence) {
@@ -158,30 +158,33 @@ class MelodyPlayer {
     void reset() {
       first = true;
       index = 0;
-      partialNoteReproduction = 0;
+      remainingNoteTime = 0;
       silence = false;
     }
 
     /**
-     * Save the the time to finish the current note.
+     * Save the time to finish the current note.
      */
-    void saveRemainingDuration(unsigned long supportSemiNote) {
-      partialNoteReproduction = supportSemiNote - millis();
+    void saveRemainingNoteDuration(unsigned long supportSemiNote) {
+      remainingNoteTime = supportSemiNote - millis();
       // Ignore partial reproduction if the current value is below the threshold. This is needed
       // since Ticker may struggle with tight timings.
-      if (partialNoteReproduction < 10) { partialNoteReproduction = 0; }
+      if (remainingNoteTime < 10) { remainingNoteTime = 0; }
     }
 
     /**
      * Clear the partial note duration. It should be called after reproduction of the partial note
      * and it is propedeutic to advance() method.
      */
-    void resetRemainingDuration() {
-      partialNoteReproduction = 0;
+    void resetRemainingNoteDuration() {
+      remainingNoteTime = 0;
     }
 
-    unsigned short getRemainingDuration() const {
-      return partialNoteReproduction;
+    /**
+     * Get the remaining duration of the latest "saved" note.
+     */
+    unsigned short getRemainingNoteDuration() const {
+      return remainingNoteTime;
     }
 
     /**
@@ -204,7 +207,7 @@ class MelodyPlayer {
      * Variable to support precise pauses and move/duplicate melodies between Players.
      * Value are expressed in milliseconds.
      */
-    unsigned short partialNoteReproduction;
+    unsigned short remainingNoteTime;
   };
 
   enum class State { STOP, PLAY, PAUSE };
@@ -220,13 +223,13 @@ class MelodyPlayer {
   const static bool debug = false;
 
   /**
-   * Change the current note with next one.
+   * Change the current note with the next one.
    */
   friend void changeTone(MelodyPlayer* melody);
 
   /**
    * Halt the advancement of the melody reproduction.
-   * This is the common method for pause and stop.
+   * This is the shared method for pause and stop.
    */
   void haltPlay();
 
@@ -242,4 +245,4 @@ class MelodyPlayer {
   void turnOff();
 };
 
-#endif  // END MELODY_PLAYER_H
+#endif  // END MELODY_PLAYER_H

src/pitches_unordered_map.h

@@ -28,9 +28,7 @@
 #include <string>
 
 /**
- * NOTE: Use carefully with Arduino: this map is quite large
- * (could be around 1Kbyte), so if you're running low of RAM,
- * switch to the original pitches.h file (based on #define)
+ * NOTE: this map is the Achille's heel of this library: it takes about 1Kbyte.
  */
 extern const std::unordered_map<std::string, unsigned short> noteMapping;