Added documenttion according to #3

README.md

@@ -1,28 +1,28 @@
-# LED-ClockShelf
+# LED-Pixel-Clock
 <p align="center">
   <img src="https://github.com/florianL21/LED-ClockShelf/blob/master/doc/images/Animation.gif?raw=true" alt="Animation example"/>
 </p>
 
 This is the software of a variation of the LED clock from [here.](https://www.instructables.com/id/How-to-Build-a-Giant-Hidden-Shelf-Edge-Clock/)
-I have a seperate branch with a ready to use configuration which works on the original version of this clock out of the box [here](https://github.com/florianL21/LED-ClockShelf/tree/diy-machines-version)
+I have a separate branch with a ready to use configuration which works on the original version of this clock out of the box [here](https://github.com/florianL21/LED-ClockShelf/tree/diy-machines-version)
 
-I decided to code it completley from scratch at I wanted to use a ESP32 instead of the Arduino nano and RTC that is used in the original project.
+I decided to code it completely from scratch at I wanted to use a ESP32 instead of the Arduino nano and RTC that is used in the original project.
 This enables some cool features like smartphone app control, OTA updates and fetching of the time using the internet.
 
-Additionally this has full support for animations. By default I provide all needed anmiations for a 12h clock to morph one digit into another soothly.
+Additionally this has full support for animations. By default I provide all needed animations for a 12h clock to morph one digit into another soothly.
 Further animations can be easily added and existing animation can be adjusted to your liking.
 
 The whole codebase is highly modular and configurable and can be tweaked exactly to your preferences.
 
-Detailed documentation is avaliable on the [Wiki.](https://github.com/florianL21/LED-ClockShelf/wiki)
+Detailed documentation is available on the [Wiki.](https://github.com/florianL21/LED-ClockShelf/wiki)
 
-If you are interested in my variation of the design which uses a lot of wood instad of the 3D prints and is a bit bigger than the original you can find it on [thingiverse here](https://www.thingiverse.com/thing:4352352)
+If you are interested in my variation of the design which uses a lot of wood instead of the 3D prints and is a bit bigger than the original you can find it on [thingiverse here](https://www.thingiverse.com/thing:4352352)
 
 # Development Environment:
 
 I am using VScode with PlatformIO.
 VSCode can be downloaded from [here.](https://code.visualstudio.com/)
-And PlatformIO is an extention that can easily be installed from inside of VSCode.
+And PlatformIO is an extension that can easily be installed from inside of VSCode.
 
 Via the PlatformIO home the following libraries have to be installed:
  * "Blynk" by Volodymyr Shymanskyy
@@ -34,4 +34,4 @@ Files that are important for configuration (sorted by importance):
  1. At the top of /include/Configuration.h -> Contains almost all important settings, like WIFI config, pin configurations etc.
  2. /src/DisplayManager/DisplayConfiguration.cpp -> Configuration of which leds belong to which segments and which segments belong to which display, the order of the segments and their animation directions *It is really important to get this one right!*
  3. /src/SevenSegment/SegmentTransitions.cpp -> Configuring the animations between the digits
- 4. /src/DisplayManager/Animations.cpp -> configuration of anmimations like the loading animation
+ 4. /src/DisplayManager/Animations.cpp -> configuration of animations like the loading animation

lib/LED_clock/Modules/DisplayManager/src/DisplayManager.cpp

@@ -289,22 +289,22 @@ void DisplayManager::setDotLEDColor(CRGB color)
 	#endif
 }
 
-void DisplayManager::AnimationManagersTemporaryOverride(Animator* OverrideanimationManager)
-{
-	for (uint16_t i = 0; i < NUM_DISPLAYS; i++)
-	{
-		animationManagerTempBuffer[i] = Displays[i]->AnimationHandler;
-		Displays[i]->AnimationHandler = OverrideanimationManager;
-	}
-}
-
-void DisplayManager::restoreAnimationManagers()
-{
-	for (uint16_t i = 0; i < NUM_DISPLAYS; i++)
-	{
-		Displays[i]->AnimationHandler = animationManagerTempBuffer[i];
-	}
-}
+// void DisplayManager::AnimationManagersTemporaryOverride(Animator* OverrideanimationManager)
+// {
+// 	for (uint16_t i = 0; i < NUM_DISPLAYS; i++)
+// 	{
+// 		animationManagerTempBuffer[i] = Displays[i]->AnimationHandler;
+// 		Displays[i]->AnimationHandler = OverrideanimationManager;
+// 	}
+// }
+
+// void DisplayManager::restoreAnimationManagers()
+// {
+// 	for (uint16_t i = 0; i < NUM_DISPLAYS; i++)
+// 	{
+// 		Displays[i]->AnimationHandler = animationManagerTempBuffer[i];
+// 	}
+// }
 
 void DisplayManager::showLoadingAnimation()
 {

lib/LED_clock/Modules/SevenSegment/inc/AnimationEffects.h

@@ -1,3 +1,9 @@
+/**
+ * \file AnimationEffects.h
+ * \author Florian Laschober
+ * \brief All avaliable animation effects which can be applied to sone segment are listed here
+ */
+
 #ifndef __ANIMATION_EFFECT_H_
 #define __ANIMATION_EFFECT_H_
 

lib/LED_clock/Modules/SevenSegment/inc/Segment.h

@@ -1,3 +1,9 @@
+/**
+ * \file Segment.h
+ * \author Florian Laschober
+ * \brief Class definition of one single segment
+ */
+
 #ifndef __SEGMENT_H_
 #define __SEGMENT_H_
 
@@ -8,9 +14,17 @@
 
 
 class AnimationEffects;
+
+/**
+ * \brief Single segment class definition. used to store which LEDs belong to one segment and applying animations on it.
+ *
+ */
 class Segment: public AnimatableObject
 {
 public:
+	/**
+	 * \brief Direction in which the LED strip is wired in.
+	 */
 	enum direction {LEFT_TO_RIGHT = false, RIGHT_TO_LEFT = true, TOP_TO_BOTTTOM = false, BOTTOM_TO_TOP = true};
 
 private:
@@ -27,8 +41,28 @@ class Segment: public AnimatableObject
 	bool isOn();
 
 public:
+	/**
+	 * \brief Construct a new Segment object
+	 *
+	 * \param LEDBuffer Array of all LEDs connected in one string. Substitution of this buffer is done internally
+	 * \param indexOfFirstLEDInSegment Index of the first LED in the whole LED string that belongs to this segment
+	 * \param segmentLength Number of LEDs which belong to this segment
+	 * \param Direction Defines which way the LED segment is wired in
+	 * \param segmentColor initial color of the segment
+	 */
 	Segment(CRGB LEDBuffer[], uint16_t indexOfFirstLEDInSegment, uint8_t segmentLength, direction Direction, CRGB segmentColor = CRGB::Black);
+
+	/**
+	 * \brief Destroy the Segment object
+	 */
 	~Segment();
+
+	/**
+	 * \brief Set the current animation state of the segment to a defined value
+	 *
+	 * \param currentState The current state of the animation starting at 0, relative to it's absolute animation length.
+	 * 					   Over and undershoot is also possible.
+	 */
 	void tick(int32_t currentState);
 
 	/**
@@ -41,15 +75,23 @@ class Segment: public AnimatableObject
 	 */
 	void updateColor(CRGB SegmentColor);
 
+
 	/**
-	 * \brief Sets the color of the segment and immediately writes is out to the leds
+	 * \brief Write the current animation color to all LEDs that belong to this segment. Writes to the LED buffer
+	 * 		  but relies on an external FastLED.show() call to actually write that change to the LEDs
 	 */
-	void displayColor(CRGB SegmentColor);
 	void display();
+
 	/**
 	 * \brief Turns off the leds of this segment but doesn't change the stored color of the segment
 	 */
 	void off();
+
+	/**
+	 * \brief Change tha animation color, also possible to do while an animation is in progress.
+	 *
+	 * \param newColor new color to use in for the current segment and animation
+	 */
 	void updateAnimationColor(CRGB newColor);
 };
 

lib/LED_clock/Modules/SevenSegment/inc/SevenSegment.h

@@ -1,3 +1,9 @@
+/**
+ * \file SevenSegment.h
+ * \author Florian Laschober
+ * \brief Definition of the SevenSegment class and some helper enums and definitions
+ */
+
 #ifndef __SEVEN_SEGMENT_H_
 #define __SEVEN_SEGMENT_H_
 
@@ -9,6 +15,9 @@
 #include "SegmentTransitions.h"
 #include "AnimationEffects.h"
 
+/**
+ * \brief Enum for addressing certain Segments in the display for animation them
+ */
 enum SegmentPositions_t {
 TOP_LEFT_SEGMENT 		= 0,
 TOP_MIDDLE_SEGMENT	 	= 1,
@@ -19,11 +28,21 @@ BOTTOM_MIDDLE_SEGMENT 	= 5,
 BOTTOM_RIGHT_SEGMENT 	= 6
 };
 
+/**
+ * \brief Helper for easier readability of the complex animation definitions
+ */
 #define SEGMENT_OFF		10
 
+/**
+ * \brief Class definition for SevenSegment which groups together all Segment objects which
+ * 		  belong to together and provides some wrapper functions to manage all seven segments together
+ */
 class SevenSegment : AnimatableObject
 {
 public:
+	/**
+	 * \brief Segment positions for addressing the internal segment mapping table - Please use #SegmentPositions_t for all external uses instead.
+	 */
 	enum SegmentPosition {
 		LeftTopSegment = 1 << TOP_LEFT_SEGMENT,
 		MiddleTopSegment = 1 << TOP_MIDDLE_SEGMENT,
@@ -34,10 +53,14 @@ class SevenSegment : AnimatableObject
 		RightBottomSegment = 1 << BOTTOM_RIGHT_SEGMENT
 	};
 
+	/**
+	 * \brief The mode of the seven segment display. This also defines which segments ave to be linked and which ones can be left out,
+	 * 		  also which digits can be displayed by this paricular instance of the seven segment display
+	 */
 	enum SevenSegmentMode {
-		FULL_SEGMENT, 	// has 7 segments
-		HALF_SEGMENT, 	// has only the 3 horizontal segments
-		ONLY_ONE		// has only the right 2 vertical segments
+		FULL_SEGMENT, 	/** has 7 segments */
+		HALF_SEGMENT, 	/** has only the 3 horizontal segments */
+		ONLY_ONE		/** has only the right 2 vertical segments */
 	};
 
 private:
@@ -46,6 +69,7 @@ class SevenSegment : AnimatableObject
 	static uint8_t segmentMap[10];
 	uint8_t currentValue;
 	bool isAnimationInitialized;
+	Animator* AnimationHandler;
 
 	uint8_t getIndexOfSegment(SegmentPosition positionInDisplay);
 	bool isConfigComplete();
@@ -54,20 +78,76 @@ class SevenSegment : AnimatableObject
 
 public:
 
-	Animator* AnimationHandler;
-
+	/**
+	 * \brief Construct a new Seven Segment object
+	 *
+	 * \param mode defines which digits can be displayed and which segments will not be assigned
+	 * \param DisplayAnimationHandler Animation handler which will be resposible for refreshing this display.
+	 */
 	SevenSegment(SevenSegmentMode mode, Animator* DisplayAnimationHandler);
+
+	/**
+	 * \brief Destroy the Seven Segment object
+	 */
 	~SevenSegment();
+
+	/**
+	 * \brief Add a single segment to the Seven segment display
+	 *
+	 * \param segmentToAdd Segment which shall be added
+	 * \param positionInDisplay Position of the added segment withing the seven segment display
+	 */
 	void add(Segment* segmentToAdd, SegmentPosition positionInDisplay);
+
+	/**
+	 * \brief Display a number on the display. If the display is not able to display the passed number nothing will happen
+	 *
+	 * \param value Number to display \range 0 - 9
+	 */
 	void DisplayNumber(uint8_t value);
+
+	/**
+	 * \brief Display a character on a Display. NOTE: Currently not implemented (only supports 0-9 as characters)
+	 *
+	 * \param value Number to display \range '0' - '9'
+	 */
 	void DisplayChar(char value);
+
+	/**
+	 * \brief Plays a fading in and out animation on the middle (or two middle, if segment length is even) LEDs of one or multiple segment/s
+	 * 		  The function will internally display the animation on the right segments depending on the #SevenSegment::SevenSegmentMode
+	 *
+	 * \param numDots Number of dots to display \range 0-2
+	 */
 	void FlashMiddleDot(uint8_t numDots);
+
+	/**
+	 * \brief checks if a particular character can be displayed on this display.
+	 *
+	 * \param charToCheck Char which shall be checked for
+	 * \return true if the char can be displayed
+	 * \return false  if the char cannot be displayed
+	 */
 	bool canDisplay(char charToCheck);
+
+	/**
+	 * \brief Sets the animation color which will be displayed on the LEDs the next time an animation ticks
+	 *
+	 * \param color Color to set
+	 */
 	void setColor(CRGB color);
+
+	/**
+	 * \brief Sets the current and also the animation color which will be displayed on the LEDs the next time the LEDs are updated
+	 *
+	 * \param color Color to set
+	 */
 	void updateColor(CRGB color);
-	void displayColor(CRGB color);
+
+	/**
+	 * \brief Turn all LEDs in this seven segment display off. will be pushed to the LEDs with the next call of FastLED.show()
+	 */
 	void off();
-	void addAnimator(Animator* AnimationManager);
 };
 
 

lib/LED_clock/Modules/SevenSegment/src/AnimationEffects.cpp

@@ -1,3 +1,16 @@
+/**
+ * \file AnimationEffects.cpp
+ * \author Florian Laschober
+ * \brief Implementation of the basic animations that are avaliable for all segments
+ * 		  Requirements to such an animation function:
+ * 			- All animations have to have the same prototype
+ * 			- An animation function always has to set the state of all LEDs that it is affecting for every step. This is required because an
+ * 			   animation can also be played backwards or multiple directions during the lifetime of one animation (for example a bounce easing)
+ * 			- The animation always starts when the current step is 0, but undershoot is also possible so it also has to be considered what
+ * 			  happens if current step goes negative. This should also result in a logical animation being displayed
+ * 			- The current step can go higher than totalSteps, this would then be an overshoot. Same considerations as above should be taken into account.
+ */
+
 #include "AnimationEffects.h"
 
 AnimatableObject::AnimationFunction AnimationEffects::AnimateOutToRight = &OutToRight;
@@ -14,16 +27,6 @@ AnimatableObject::AnimationFunction AnimationEffects::AnimateOutFromMiddle = &Ou
 AnimatableObject::AnimationFunction AnimationEffects::AnimateInFromMiddle = &InFromMiddle;
 AnimatableObject::AnimationFunction AnimationEffects::AnimateMiddleDotFlash = &MiddleDotFlash;
 
-AnimationEffects::AnimationEffects()
-{
-
-}
-
-AnimationEffects::~AnimationEffects()
-{
-}
-
-
 void AnimationEffects::OutToRight(CRGB* leds, uint16_t length, CRGB animationColor, uint16_t totalSteps, int32_t currentStep, bool invert)
 {
     if(invert == true)

lib/LED_clock/Modules/SevenSegment/src/Segment.cpp

@@ -1,3 +1,9 @@
+/**
+ * \file Segment.cpp
+ * \author Florian Laschober
+ * \brief Implementation of the member functions of the Segment class
+ */
+
 #include "Segment.h"
 
 Segment::Segment(CRGB LEDBuffer[], uint16_t indexOfFirstLEDInSegment, uint8_t segmentLength, direction Direction, CRGB segmentColor) : AnimatableObject(0, 0)
@@ -42,12 +48,6 @@ void Segment::setColor(CRGB SegmentColor)
 	updateAnimationColor(color);
 }
 
-void Segment::displayColor(CRGB SegmentColor)
-{
-	setColor(SegmentColor);
-	display();
-}
-
 void Segment::off()
 {
 	writeToLEDs(CRGB::Black);