From 3f98ec03ca076ee9061a33bdefc2eb26f55b8572 Mon Sep 17 00:00:00 2001 From: "D.R.racer" Date: Fri, 25 Jun 2021 12:03:41 +0200 Subject: [PATCH] Fix doxygen documentation for the logic layer --- src/logic/command_base.h | 15 ++++++++------- src/logic/cut_filament.h | 5 +++-- src/logic/eject_filament.h | 8 ++++---- src/logic/error_codes.h | 1 - src/logic/feed_to_bondtech.h | 6 +++--- src/logic/feed_to_finda.h | 6 +++--- src/logic/load_filament.h | 5 +++-- src/logic/no_command.h | 3 ++- src/logic/progress_codes.h | 1 - src/logic/tool_change.h | 5 +++-- src/logic/unload_filament.h | 6 +++--- src/logic/unload_to_finda.h | 11 +++++++---- 12 files changed, 39 insertions(+), 33 deletions(-) diff --git a/src/logic/command_base.h b/src/logic/command_base.h index d2c7671..2ebfc25 100644 --- a/src/logic/command_base.h +++ b/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 diff --git a/src/logic/cut_filament.h b/src/logic/cut_filament.h index 271f47a..01f1758 100644 --- a/src/logic/cut_filament.h +++ b/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 diff --git a/src/logic/eject_filament.h b/src/logic/eject_filament.h index b026522..9012ac9 100644 --- a/src/logic/eject_filament.h +++ b/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 diff --git a/src/logic/error_codes.h b/src/logic/error_codes.h index 77a24f8..3bdee56 100644 --- a/src/logic/error_codes.h +++ b/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 diff --git a/src/logic/feed_to_bondtech.h b/src/logic/feed_to_bondtech.h index 887815d..f9b2ad2 100644 --- a/src/logic/feed_to_bondtech.h +++ b/src/logic/feed_to_bondtech.h @@ -1,13 +1,13 @@ #pragma once #include +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, diff --git a/src/logic/feed_to_finda.h b/src/logic/feed_to_finda.h index 4d20736..169b147 100644 --- a/src/logic/feed_to_finda.h +++ b/src/logic/feed_to_finda.h @@ -1,14 +1,14 @@ #pragma once #include +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, diff --git a/src/logic/load_filament.h b/src/logic/load_filament.h index d123b6d..0ac217e 100644 --- a/src/logic/load_filament.h +++ b/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 diff --git a/src/logic/no_command.h b/src/logic/no_command.h index 52b10ff..adee86b 100644 --- a/src/logic/no_command.h +++ b/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 diff --git a/src/logic/progress_codes.h b/src/logic/progress_codes.h index 9cdb46d..55883f6 100644 --- a/src/logic/progress_codes.h +++ b/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 diff --git a/src/logic/tool_change.h b/src/logic/tool_change.h index d346d64..b4c9197 100644 --- a/src/logic/tool_change.h +++ b/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 diff --git a/src/logic/unload_filament.h b/src/logic/unload_filament.h index 7381059..6600e67 100644 --- a/src/logic/unload_filament.h +++ b/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 diff --git a/src/logic/unload_to_finda.h b/src/logic/unload_to_finda.h index c73ea12..bccb926 100644 --- a/src/logic/unload_to_finda.h +++ b/src/logic/unload_to_finda.h @@ -1,15 +1,15 @@ #pragma once #include -/// 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: