Fix doxygen documentation for the logic layer

src/logic/command_base.h

@@ -3,14 +3,15 @@
 #include "error_codes.h"
 #include "progress_codes.h"
 
-/// Base class defining common API for high-level operations/commands/state machines
+/// The logic namespace handles the application logic on top of the modules.
+namespace logic {
+
+/// @brief Base class defining common API for high-level operations/commands/state machines
 ///
 /// Which state machines are high-level? Those which are being initiated either by a command over the serial line or from a button
 /// - they report their progress to the printer
 /// - they can be composed of other sub automata
-
-namespace logic {
-
+///
 /// Tasks derived from this base class are the top-level operations inhibited by the printer.
 /// These tasks report their progress and only one of these tasks is allowed to run at once.
 class CommandBase {
@@ -50,12 +51,12 @@ public:
     /// @returns status of the operation - e.g. RUNNING, OK, or an error code if the operation failed.
     ///
     /// Beware - the same rule about composite operations as with State() applies to Error() as well.
-    /// Please see @ErrorCode for more details
+    /// Please see ErrorCode for more details
     virtual ErrorCode Error() const { return error; }
 
 protected:
-    ProgressCode state;
-    ErrorCode error;
+    ProgressCode state; ///< current progress state of the state machine
+    ErrorCode error; ///< current error code
 };
 
 } // namespace logic

src/logic/cut_filament.h

@@ -6,14 +6,14 @@
 
 namespace logic {
 
-/// A high-level command state machine
-/// Handles the complex logic of cutting filament
+/// @brief  A high-level command state machine - handles the complex logic of cutting filament
 class CutFilament : public CommandBase {
 public:
     inline CutFilament()
         : CommandBase() {}
 
     /// Restart the automaton
+    /// @param param index of filament slot to perform cut onto
     void Reset(uint8_t param) override;
 
     /// @returns true if the state machine finished its job, false otherwise
@@ -32,6 +32,7 @@ private:
     void SelectFilamentSlot();
 };
 
+/// The one and only instance of CutFilament state machine in the FW
 extern CutFilament cutFilament;
 
 } // namespace logic

src/logic/eject_filament.h

@@ -5,23 +5,22 @@
 
 namespace logic {
 
-/// A high-level command state machine
-/// Handles the complex logic of ejecting filament:
+/// @brief  A high-level command state machine - handles the complex logic of ejecting filament
 ///
+/// The eject operation consists of:
 /// - Move selector sideways and push filament forward a little bit, so that the user can catch it
 /// - Unpark idler at the end so that the user can pull filament out.
 /// - If there is still some filament detected by PINDA unload it first.
 /// - If we want to eject fil 0-2, move selector to position 4 (right).
 /// - If we want to eject fil 3-4, move selector to position 0 (left)
 /// Optionally, we can also move the selector to its service position in the future.
-/// @param filament filament 0 to 4
-
 class EjectFilament : public CommandBase {
 public:
     inline EjectFilament()
         : CommandBase() {}
 
     /// Restart the automaton
+    /// @param param index of filament slot to eject
     void Reset(uint8_t param) override;
 
     /// @returns true if the state machine finished its job, false otherwise
@@ -38,6 +37,7 @@ private:
     void MoveSelectorAside();
 };
 
+/// The one and only instance of EjectFilament state machine in the FW
 extern EjectFilament ejectFilament;
 
 } // namespace logic

src/logic/error_codes.h

@@ -4,7 +4,6 @@
 /// A complete set of error codes which may be a result of a high-level command/operation
 /// This header file shall be included in the printer's firmware as well as a reference,
 /// therefore the error codes have been extracted to one place
-
 enum class ErrorCode : int_fast8_t {
     RUNNING = 0, ///< the operation is still running
     OK, ///< the operation finished OK

src/logic/feed_to_bondtech.h

@@ -1,13 +1,13 @@
 #pragma once
 #include <stdint.h>
 
+namespace logic {
+
 /// @brief Feed filament to Bondtech gears of the printer
 ///
 /// Continuously feed filament until the printer detects the filament in its filament sensor
-
-namespace logic {
-
 struct FeedToBondtech {
+    /// internal states of the state machine
     enum {
         EngagingIdler,
         PushingFilament,

src/logic/feed_to_finda.h

@@ -1,14 +1,14 @@
 #pragma once
 #include <stdint.h>
 
+namespace logic {
+
 /// @brief Feed filament to FINDA
 ///
 /// Continuously feed filament until FINDA is not switched ON
 /// and than retract to align filament 600 steps away from FINDA.
-
-namespace logic {
-
 struct FeedToFinda {
+    /// internal states of the state machine
     enum {
         EngagingIdler,
         PushingFilament,

src/logic/load_filament.h

@@ -6,14 +6,14 @@
 
 namespace logic {
 
-/// A high-level command state machine
-/// Handles the complex logic of loading filament
+/// @brief A high-level command state machine - handles the complex logic of loading filament into a filament slot.
 class LoadFilament : public CommandBase {
 public:
     inline LoadFilament()
         : CommandBase() {}
 
     /// Restart the automaton
+    /// @param param index of filament slot to load
     void Reset(uint8_t param) override;
 
     /// @returns true if the state machine finished its job, false otherwise
@@ -24,6 +24,7 @@ private:
     FeedToBondtech james; // bond ;)
 };
 
+/// The one and only instance of LoadFilament state machine in the FW
 extern LoadFilament loadFilament;
 
 } // namespace logic

src/logic/no_command.h

@@ -5,7 +5,7 @@
 
 namespace logic {
 
-/// A dummy No-command operation just to make the init of the firmware consistent (and cleaner code during processing)
+/// @brief A dummy No-command operation just to make the init of the firmware consistent (and cleaner code during processing).
 class NoCommand : public CommandBase {
 public:
     inline NoCommand()
@@ -18,6 +18,7 @@ public:
     bool Step() override { return true; }
 };
 
+/// The one and only instance of NoCommand state machine in the FW
 extern NoCommand noCommand;
 
 } // namespace logic

src/logic/progress_codes.h

@@ -4,7 +4,6 @@
 /// A complete set of progress codes which may be reported while running a high-level command/operation
 /// This header file shall be included in the printer's firmware as well as a reference,
 /// therefore the progress codes have been extracted to one place
-
 enum class ProgressCode : uint_fast8_t {
     OK = 0, ///< finished ok
 

src/logic/tool_change.h

@@ -6,14 +6,14 @@
 
 namespace logic {
 
-/// A high-level command state machine
-/// Handles the complex logic of tool change
+/// @brief  A high-level command state machine - handles the complex logic of tool change - which is basically a chain of an Unload and a Load operation.
 class ToolChange : public CommandBase {
 public:
     inline ToolChange()
         : CommandBase() {}
 
     /// Restart the automaton
+    /// @param param index of filament slot to change to - i.e. to load
     void Reset(uint8_t param) override;
 
     /// @returns true if the state machine finished its job, false otherwise
@@ -29,6 +29,7 @@ private:
     uint8_t plannedSlot;
 };
 
+/// The one and only instance of ToolChange state machine in the FW
 extern ToolChange toolChange;
 
 } // namespace logic

src/logic/unload_filament.h

@@ -5,8 +5,7 @@
 
 namespace logic {
 
-/// A high-level command state machine
-/// Handles the complex logic of unloading filament
+/// @brief A high-level command state machine - handles the complex logic of unloading filament
 class UnloadFilament : public CommandBase {
 public:
     inline UnloadFilament()
@@ -14,7 +13,7 @@ public:
 
     /// Restart the automaton
     /// @param param is not used, always unloads from the active slot
-    void Reset(uint8_t /*param*/) override;
+    void Reset(uint8_t param) override;
 
     /// @returns true if the state machine finished its job, false otherwise
     bool Step() override;
@@ -24,6 +23,7 @@ private:
     UnloadToFinda unl;
 };
 
+/// The one and only instance of UnloadFilament state machine in the FW
 extern UnloadFilament unloadFilament;
 
 } // namespace logic

src/logic/unload_to_finda.h

@@ -1,15 +1,15 @@
 #pragma once
 #include <stdint.h>
 
-/// Unload to FINDA "small" state machine
+namespace logic {
+
+/// @brief Unload to FINDA "small" state machine
+///
 /// "small" state machines will serve as building blocks for high-level commands/operations
 /// - engage/disengage idler
 /// - rotate pulley to some direction as long as the FINDA is on/off
 /// - rotate some axis to some fixed direction
 /// - load/unload to finda
-
-namespace logic {
-
 /// A "small" automaton example - Try to unload filament to FINDA and if it fails try to recover several times.
 /// \dot
 /// digraph example {
@@ -20,6 +20,7 @@ namespace logic {
 ///}
 ///\enddot
 struct UnloadToFinda {
+    /// internal states of the state machine
     enum {
         EngagingIdler,
         WaitingForFINDA,
@@ -30,11 +31,13 @@ struct UnloadToFinda {
         : maxTries(3) {}
 
     /// Restart the automaton
+    /// @param maxTries maximum number of retried attempts before reporting a fail
     void Reset(uint8_t maxTries);
 
     /// @returns true if the state machine finished its job, false otherwise
     bool Step();
 
+    /// @returns internal state of the state machine
     inline uint8_t State() const { return state; }
 
 private: