From 8f1b8c9ce6435b51fe2e47aed780d6fd0cddc1f5 Mon Sep 17 00:00:00 2001 From: Trent Houliston Date: Mon, 12 Aug 2024 10:36:51 +1000 Subject: [PATCH 1/2] Connect vscode to SonarCloud (#112) Sets up the connection between SonarCloud and VSCode so that it can display warnings in the IDE --- .vscode/settings.json | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index 78a6e13f3..425358153 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -11,5 +11,9 @@ "C_Cpp.preferredPathSeparator": "Forward Slash", "editor.rulers": [120], "cmake.configureOnOpen": true, - "C_Cpp.default.configurationProvider": "vector-of-bool.cmake-tools" + "C_Cpp.default.configurationProvider": "vector-of-bool.cmake-tools", + "sonarlint.connectedMode.project": { + "connectionId": "fastcode", + "projectKey": "Fastcode_NUClear" + } } From d595e0d2fe7921780817ff6d8a4ad96eb7399801 Mon Sep 17 00:00:00 2001 From: Trent Houliston Date: Mon, 12 Aug 2024 13:31:27 +1000 Subject: [PATCH 2/2] Remove @brief and @details and reflow comments to try to adhere to sentence per line (#113) The docs style was inconsistent, try to maintain this style from now on. (I wish there were a doxygen autoformatter) --- docs/extension.rst | 7 +- src/Configuration.hpp | 4 +- src/Environment.hpp | 13 +- src/LogLevel.hpp | 64 +++---- src/PowerPlant.hpp | 117 ++++++------ src/PowerPlant.ipp | 2 +- src/Reactor.hpp | 46 +++-- src/clock.hpp | 33 ++-- src/dsl/Fusion.hpp | 2 +- src/dsl/fusion/BindFusion.hpp | 19 +- src/dsl/fusion/GetFusion.hpp | 6 +- src/dsl/fusion/GroupFusion.hpp | 10 +- src/dsl/fusion/NoOp.hpp | 8 +- src/dsl/fusion/PoolFusion.hpp | 10 +- src/dsl/fusion/PostconditionFusion.hpp | 10 +- src/dsl/fusion/PreconditionFusion.hpp | 10 +- src/dsl/fusion/PriorityFusion.hpp | 10 +- src/dsl/fusion/has_bind.hpp | 2 +- src/dsl/fusion/has_get.hpp | 2 +- src/dsl/fusion/has_group.hpp | 6 +- src/dsl/fusion/has_pool.hpp | 6 +- src/dsl/fusion/has_postcondition.hpp | 3 +- src/dsl/fusion/has_precondition.hpp | 3 +- src/dsl/fusion/has_priority.hpp | 6 +- src/dsl/operation/CacheGet.hpp | 8 +- src/dsl/operation/ChronoTask.hpp | 45 +++-- src/dsl/operation/DSLProxy.hpp | 11 +- src/dsl/operation/TypeBind.hpp | 10 +- src/dsl/operation/Unbind.hpp | 12 +- src/dsl/store/DataStore.hpp | 9 +- src/dsl/store/ThreadStore.hpp | 16 +- src/dsl/store/TypeCallbackStore.hpp | 12 +- src/dsl/trait/is_transient.hpp | 12 +- src/dsl/validation/Validation.hpp | 10 +- src/dsl/word/Always.hpp | 27 ++- src/dsl/word/Buffer.hpp | 14 +- src/dsl/word/Every.hpp | 38 ++-- src/dsl/word/Group.hpp | 38 ++-- src/dsl/word/IO.hpp | 58 +++--- src/dsl/word/Idle.hpp | 14 +- src/dsl/word/Last.hpp | 64 +++---- src/dsl/word/MainThread.hpp | 9 +- src/dsl/word/Network.hpp | 20 +-- src/dsl/word/Once.hpp | 11 +- src/dsl/word/Optional.hpp | 32 ++-- src/dsl/word/Pool.hpp | 26 ++- src/dsl/word/Priority.hpp | 34 ++-- src/dsl/word/Shutdown.hpp | 21 ++- src/dsl/word/Single.hpp | 10 +- src/dsl/word/Startup.hpp | 14 +- src/dsl/word/Sync.hpp | 40 +++-- src/dsl/word/TCP.hpp | 39 ++-- src/dsl/word/Trigger.hpp | 23 ++- src/dsl/word/UDP.hpp | 66 ++++--- src/dsl/word/Watchdog.hpp | 97 +++++----- src/dsl/word/With.hpp | 33 ++-- src/dsl/word/emit/Delay.hpp | 28 ++- src/dsl/word/emit/Direct.hpp | 26 ++- src/dsl/word/emit/Initialise.hpp | 28 ++- src/dsl/word/emit/Local.hpp | 16 +- src/dsl/word/emit/Network.hpp | 26 +-- src/dsl/word/emit/UDP.hpp | 16 +- src/dsl/word/emit/Watchdog.hpp | 81 ++++----- src/extension/ChronoController.hpp | 12 +- src/extension/IOController_Posix.hpp | 53 +++--- src/extension/IOController_Windows.hpp | 46 ++--- src/extension/network/NUClearNetwork.cpp | 6 +- src/extension/network/NUClearNetwork.hpp | 98 +++++----- src/extension/network/wire_protocol.hpp | 4 +- src/id.hpp | 2 +- src/message/CommandLineArguments.hpp | 2 +- src/message/LogMessage.hpp | 20 +-- src/message/NetworkConfiguration.hpp | 10 +- src/message/ReactionStatistics.hpp | 22 +-- src/message/TimeTravel.hpp | 14 +- src/threading/Reaction.hpp | 45 +++-- src/threading/ReactionHandle.hpp | 62 +++---- src/threading/ReactionIdentifiers.hpp | 20 +-- src/threading/ReactionTask.hpp | 60 +++---- src/threading/TaskScheduler.hpp | 190 ++++++++++---------- src/util/FileDescriptor.hpp | 33 ++-- src/util/FunctionFusion.hpp | 146 ++++++++------- src/util/GeneratedCallback.hpp | 12 +- src/util/GroupDescriptor.hpp | 8 +- src/util/MetaProgramming.hpp | 6 +- src/util/Sequence.hpp | 16 +- src/util/ThreadPoolDescriptor.hpp | 14 +- src/util/TypeList.hpp | 6 +- src/util/TypeMap.hpp | 28 +-- src/util/apply.hpp | 14 +- src/util/demangle.cpp | 4 +- src/util/main_thread_id.hpp | 6 +- src/util/network/get_interfaces.hpp | 24 +-- src/util/network/if_number_from_address.hpp | 6 +- src/util/network/resolve.hpp | 13 +- src/util/platform.hpp | 2 +- src/util/serialise/xxhash.cpp | 7 +- src/util/serialise/xxhash.hpp | 8 +- src/util/unpack.hpp | 30 ++-- tests/test_util/TestBase.hpp | 8 +- tests/tests/api/ReactionHandle.cpp | 2 +- tests/tests/api/ReactionStatistics.cpp | 2 +- tests/tests/dsl/Always.cpp | 2 +- tests/tests/dsl/ArgumentFission.cpp | 2 +- tests/tests/dsl/BlockNoData.cpp | 2 +- tests/tests/dsl/Buffer.cpp | 2 +- tests/tests/dsl/CustomGet.cpp | 2 +- tests/tests/dsl/DSLOrdering.cpp | 2 +- tests/tests/dsl/DSLProxy.cpp | 2 +- tests/tests/dsl/FlagMessage.cpp | 2 +- tests/tests/dsl/IO.cpp | 4 +- tests/tests/dsl/Idle.cpp | 2 +- tests/tests/dsl/IdleSync.cpp | 2 +- tests/tests/dsl/Last.cpp | 2 +- tests/tests/dsl/MainThread.cpp | 2 +- tests/tests/dsl/MissingArguments.cpp | 2 +- tests/tests/dsl/Optional.cpp | 2 +- tests/tests/dsl/Priority.cpp | 2 +- tests/tests/dsl/RawFunction.cpp | 21 +-- tests/tests/dsl/Shutdown.cpp | 2 +- tests/tests/dsl/Startup.cpp | 2 +- tests/tests/dsl/Sync.cpp | 2 +- tests/tests/dsl/SyncOrder.cpp | 2 +- tests/tests/dsl/TCP.cpp | 2 +- tests/tests/dsl/Transient.cpp | 2 +- tests/tests/dsl/Trigger.cpp | 2 +- tests/tests/dsl/UDP.cpp | 2 +- tests/tests/dsl/Watchdog.cpp | 2 +- tests/tests/dsl/With.cpp | 2 +- tests/tests/dsl/emit/Delay.cpp | 4 +- tests/tests/dsl/emit/EmitFusion.cpp | 2 +- tests/tests/dsl/emit/Initialise.cpp | 2 +- 132 files changed, 1269 insertions(+), 1368 deletions(-) diff --git a/docs/extension.rst b/docs/extension.rst index f5b2f6cee..093fe1c51 100644 --- a/docs/extension.rst +++ b/docs/extension.rst @@ -156,11 +156,11 @@ The template is used to have multiple static contexts. using task_ptr = std::unique_ptr; - /// @brief our queue which sorts tasks by priority + /// Our queue which sorts tasks by priority static std::priority_queue queue; - /// @brief how many tasks are currently running + /// How many tasks are currently running static volatile bool running; - /// @brief a mutex to ensure data consistency + /// A mutex to ensure data consistency static std::mutex mutex; Now we define the `reschedule` to interrupt any new tasks if we are currently running. Recall that NUClear is @@ -218,4 +218,3 @@ We need to instantiate our static members outside the class definition. template std::mutex Sync::mutex; - diff --git a/src/Configuration.hpp b/src/Configuration.hpp index c51d678ad..7cd7256d6 100644 --- a/src/Configuration.hpp +++ b/src/Configuration.hpp @@ -29,10 +29,10 @@ namespace NUClear { /** - * @brief This class holds the configuration for a PowerPlant. + * This class holds the configuration for a PowerPlant. */ struct Configuration { - /// @brief The number of threads the system will use + /// The number of threads the system will use size_t thread_count = std::thread::hardware_concurrency() == 0 ? 2 : std::thread::hardware_concurrency(); }; diff --git a/src/Environment.hpp b/src/Environment.hpp index 5bf2d43d4..2122fea27 100644 --- a/src/Environment.hpp +++ b/src/Environment.hpp @@ -34,13 +34,10 @@ class Reactor; class PowerPlant; /** - * @brief - * Environment defines variables that are passed from the installing PowerPlant context - * into a Reactor. + * Environment defines variables that are passed from the installing PowerPlant context into a Reactor. * - * @details - * The Environment is used to provide information from the PowerPlant to Reactors. - * Each Reactor owns it's own environment and can use it to access useful information. + * The Environment is used to provide information from the PowerPlant to Reactors. + * Each Reactor owns it's own environment and can use it to access useful information. */ class Environment { public: @@ -51,9 +48,9 @@ class Environment { friend class PowerPlant; friend class Reactor; - /// @brief The PowerPlant to use in this reactor + /// The PowerPlant to use in this reactor PowerPlant& powerplant; - /// @brief The name of the reactor + /// The name of the reactor std::string reactor_name; }; diff --git a/src/LogLevel.hpp b/src/LogLevel.hpp index ebf1494c3..da7826e26 100644 --- a/src/LogLevel.hpp +++ b/src/LogLevel.hpp @@ -32,16 +32,14 @@ namespace NUClear { /** - * @brief LogLevel defines the different levels log messages can be set to. + * LogLevel defines the different levels log messages can be set to. * - * @details - * Log levels are used to provide different levels of detail on a per-reactor basis. - * The logging level of a reactor can be changed by setting it in the install function. + * Log levels are used to provide different levels of detail on a per-reactor basis. + * The logging level of a reactor can be changed by setting it in the install function. */ enum LogLevel { /** - * @brief - * Don't use this log level when emitting logs, it is for setting reactor log level from non reactor sources. + * Don't use this log level when emitting logs, it is for setting reactor log level from non reactor sources. * * Specifically when a NUClear::log is called from code that is not running in a reaction (even transitively) then * the reactor_level will be set to UNKNOWN. @@ -49,66 +47,52 @@ enum LogLevel { UNKNOWN, /** - * @brief - * The Trace level contains messages that are used to trace the exact flow of execution. + * The Trace level contains messages that are used to trace the exact flow of execution. * - * @details - * This level is extremely verbose and often has a message per line of code. + * This level is extremely verbose and often has a message per line of code. */ TRACE, /** - * @brief - * Debug contains messages that represent the inputs and outputs of different - * computation units. + * Debug contains messages that represent the inputs and outputs of different computation units. * - * @details - * If you have a function that performs three steps to do something - * then it's likely that you will have a message for the input and output of those - * three steps. Additionally you would likely have messages that check if it hit - * different branches. + * If you have a function that performs three steps to do something then it's likely that you will have a message + * for the input and output of those three steps. + * Additionally you would likely have messages that check if it hit different branches. */ DEBUG, /** - * @brief - * The info level is used to provide high level goal messages such as function start - * or successful completion. + * The info level is used to provide high level goal messages such as function start or successful completion. * - * @details - * This shows when key user-facing functionality is executed and tells us that everything - * is working without getting into the details. + * This shows when key user-facing functionality is executed and tells us that everything is working without getting + * into the details. */ INFO, /** - * @brief The warning level is used to notify us that everything might not be working perfectly. + * The warning level is used to notify us that everything might not be working perfectly. * - * @details - * Warnings are errors or inconsistencies that aren't fatal and generally do not completely - * break the system. However a warning message should require action from someone and should - * point to a section of the system that needs attention. + * Warnings are errors or inconsistencies that aren't fatal and generally do not completely break the system. + * However a warning message should require action and should point to a section of the system that needs attention. */ WARN, /** - * @brief - * The error level is used to report unexpected behavior. + * The error level is used to report unexpected behavior. - * @details - * This level doesn't need to prefix a program-crashing issue but should be used to report major - * unexpected branches in logic or other constraint breaking problems such as failed assertions. - * All errors should require action from someone and should be addressed immediately. + * This level doesn't need to prefix a program-crashing issue but should be used to report major unexpected branches + * in logic or other constraint breaking problems such as failed assertions. + * All errors should require action from someone and should be addressed immediately. */ ERROR, /** - * @brief Fatal is a program destroying error that needs to be addressed immediately. + * Fatal is a program destroying error that needs to be addressed immediately. * - * @details - * If a fatal message is sent it should point to something that should never ever happen and - * ideally provide as much information as possible as to why it crashed. Fatal messages - * require action immediately and should always be addressed. + * If a fatal message is sent it should point to something that should never ever happen and ideally provide as much + * information as possible as to why it crashed. + * Fatal messages require action immediately and should always be addressed. */ FATAL }; diff --git a/src/PowerPlant.hpp b/src/PowerPlant.hpp index ec327ec81..27270e0f6 100644 --- a/src/PowerPlant.hpp +++ b/src/PowerPlant.hpp @@ -54,12 +54,11 @@ namespace NUClear { class Reactor; /** - * @brief The PowerPlant is the core of a NUClear system. It holds all Reactors in it and manages their communications. + * The PowerPlant is the core of a NUClear system. It holds all Reactors in it and manages their communications. * - * @details - * At the centre of every NUClear system is a PowerPlant. A PowerPlant contains all of the reactors that are - * used within the system and sets up their reactions. It is also responsible for storing information between - * reactions and ensuring that all threading is handled appropriately. + * At the centre of every NUClear system is a PowerPlant. + * A PowerPlant contains all of the reactors that are used within the system and sets up their reactions. + * It is also responsible for storing information between reactions and ensuring threading is handled appropriately. */ class PowerPlant { // Reactors and PowerPlants are very tightly linked @@ -70,15 +69,13 @@ class PowerPlant { static PowerPlant* powerplant; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) /** - * @brief - * Constructs a PowerPlant with the given configuration and provides access - * to argv for all reactors. + * Constructs a PowerPlant with the given configuration and provides access to argv for all reactors. * - * @details Arguments passed to this function will be emitted as a CommandLineArguments message. + * Arguments passed to this function will be emitted as a CommandLineArguments message. * * @param config The PowerPlant's configuration - * @param argc The number of command line arguments - * @param argv The command line argument strings + * @param argc The number of command line arguments + * @param argv The command line argument strings */ // NOLINTNEXTLINE(cppcoreguidelines-avoid-c-arrays,modernize-avoid-c-arrays) PowerPlant(Configuration config = Configuration(), int argc = 0, const char* argv[] = nullptr); @@ -91,40 +88,38 @@ class PowerPlant { PowerPlant& operator=(const PowerPlant&& other) = delete; /** - * @brief Starts up the PowerPlant's components in order and begins it running. + * Starts up the PowerPlant's components in order and begins it running. * - * @details - * Starts up the PowerPlant instance and starts all the pool threads. This - * method is blocking and will release when the PowerPlant shuts down. - * It should only be called from the main thread so that statics are not - * destructed. + * Starts up the PowerPlant instance and starts all the pool threads. + * This method is blocking and will release when the PowerPlant shuts down. + * It should only be called from the main thread so that statics are not destructed. */ void start(); /** - * @brief Shuts down the PowerPlant, tells all component threads to terminate, - * Then releases the main thread. + * Shuts down the PowerPlant, tells all component threads to terminate and waits for them to finish. */ void shutdown(); /** - * @brief Returns true if the PowerPlant is running or not intending to shut down soon. Returns false otherwise. + * Gets the current running state of the PowerPlant. + * + * @return True if the PowerPlant is running, false if it is shut down, or is in the process of shutting down. */ bool running() const; /** - * @brief Installs a reactor of a particular type to the system. + * Installs a reactor of a particular type to the system. * - * @details - * This function constructs a new Reactor of the template type. - * It passes through the specified LogLevel - * in the environment of that reactor so that it can be used to filter logs. + * This function constructs a new Reactor of the template type. + * It passes through the specified LogLevel + * in the environment of that reactor so that it can be used to filter logs. * - * @tparam T The type of the reactor to build and install - * @tparam Args The types of the extra arguments to pass to the reactor constructor - * @tparam level The initial logging level for this reactor to use + * @tparam T The type of the reactor to build and install + * @tparam Args The types of the extra arguments to pass to the reactor constructor + * @tparam level The initial logging level for this reactor to use * - * @param arg Extra arguments to pass to the reactor constructor + * @param arg Extra arguments to pass to the reactor constructor * * @return A reference to the installed reactor */ @@ -132,22 +127,22 @@ class PowerPlant { T& install(Args&&... args); /** - * @brief Adds an idle task to the task scheduler. + * Adds an idle task to the task scheduler. * * This function adds an idle task to the task scheduler, which will be executed when the thread pool associated - * with the given `pool_id` has no other tasks to execute. The `task` parameter is a callable object that - * represents the idle task to be executed. + * with the given `pool_id` has no other tasks to execute. + * The `task` parameter is a callable object that represents the idle task to be executed. * - * @param id The ID of the task. + * @param id The ID of the task * @param pool_descriptor The descriptor for the thread pool to test for idle - * @param task The idle task to be executed. + * @param task The idle task to be executed */ void add_idle_task(const NUClear::id_t& id, const util::ThreadPoolDescriptor& pool_descriptor, std::function&& task); /** - * @brief Removes an idle task from the task scheduler. + * Removes an idle task from the task scheduler. * * This function removes an idle task from the task scheduler. The `id` and `pool_id` parameters are used to * identify the idle task to be removed. @@ -158,7 +153,7 @@ class PowerPlant { void remove_idle_task(const NUClear::id_t& id, const util::ThreadPoolDescriptor& pool_descriptor); /** - * @brief Generic submit function for submitting tasks to the thread pool. + * Generic submit function for submitting tasks to the thread pool. * * @param id an id for ordering the task * @param priority the priority of the task between 0 and 1000 @@ -175,20 +170,18 @@ class PowerPlant { std::function&& task); /** - * @brief Submits a new task to the ThreadPool to be queued and then executed. + * Submits a new task to the ThreadPool to be queued and then executed. * - * @param task The Reaction task to be executed in the thread pool - * @param immediate if this task should run immediately in the current thread + * @param task The Reaction task to be executed in the thread pool + * @param immediate If this task should run immediately in the current thread */ void submit(std::unique_ptr&& task, const bool& immediate = false) noexcept; /** - * @brief Log a message through NUClear's system. + * Log a message through NUClear's system. * - * @details - * Logs a message through the system so the various log handlers - * can access it. The arguments being logged should be able to - * be added into a stringstream. + * Logs a message through the system so the various log handlers can access it. + * The arguments being logged should be able to be added into a stringstream. * * @tparam level The level to log at (defaults to DEBUG) * @tparam Arguments The types of the arguments we are logging @@ -199,10 +192,9 @@ class PowerPlant { static void log(Arguments&&... args); /** - * @brief Emits data to the system and routes it to the other systems that use it. + * Emits data to the system and routes it to the other systems that use it. * - * @details - * Emits at Local scope which creates tasks using the thread pool. + * Emits at Local scope which creates tasks using the thread pool. * * @see NUClear::dsl::word::emit::Local for info about Local scope. * @@ -216,23 +208,24 @@ class PowerPlant { void emit(std::unique_ptr& data); /** - * @brief Emits data to the system and routes it to the other systems that use it. + * Emits data to the system and routes it to the other systems that use it. * - * @details - * This is for the special case of emitting a shared_ptr. The types are Fused and the reaction is started. If the - * Fusion fails, a static_assert fails. + * This is for the special case of emitting a shared_ptr. + * The types are Fused and the reaction is started. + * If the Fusion fails, a static_assert fails. * - * @note Emitting shared data can be helpful for forwarding data which has already been emitted and forwarding it on - * to external parties, without needing to copy it. + * @note + * Emitting shared data can be helpful for forwarding data which has already been emitted and forwarding it on to + * external parties, without needing to copy it. * * @see NUClear::util::FunctionFusion * * @warning This shouldn't be used without a specific reason - usually forwarding data. * - * @tparam First The first handler to use for this emit - * @tparam Remainder The remaining handlers to use for this emit - * @tparam T The type of the data that we are emitting - * @tparam Arguments The additional arguments that will be provided to the handlers + * @tparam First The first handler to use for this emit + * @tparam Remainder The remaining handlers to use for this emit + * @tparam T The type of the data that we are emitting + * @tparam Arguments The additional arguments that will be provided to the handlers * * @param data The data we are emitting */ @@ -264,18 +257,18 @@ class PowerPlant { void emit(Arguments&&... args); private: - /// @brief A list of tasks that must be run when the powerplant starts up + /// A list of tasks that must be run when the powerplant starts up std::vector> tasks; - /// @brief Our TaskScheduler that handles distributing task to the pool threads + /// Our TaskScheduler that handles distributing task to the pool threads threading::TaskScheduler scheduler; - /// @brief Our vector of Reactors, will get destructed when this vector is + /// Our vector of Reactors, will get destructed when this vector is std::vector> reactors; - /// @brief True if the powerplant is running + /// True if the powerplant is running std::atomic is_running{false}; }; /** - * @brief This free floating log function can be called from anywhere and will use the singleton PowerPlant + * This free floating log function can be called from anywhere and will use the singleton PowerPlant. * * @see NUClear::PowerPlant::log() * diff --git a/src/PowerPlant.ipp b/src/PowerPlant.ipp index 002c15d5c..a2873ee80 100644 --- a/src/PowerPlant.ipp +++ b/src/PowerPlant.ipp @@ -86,7 +86,7 @@ void PowerPlant::emit(std::unique_ptr& data, Arguments&&... args) { } /** - * @brief This is our Function Fusion wrapper class that allows it to call emit functions + * This is our Function Fusion wrapper class that allows it to call emit functions * * @tparam Handler The emit handler that we are wrapping for */ diff --git a/src/Reactor.hpp b/src/Reactor.hpp index cbff255d5..a1102542b 100644 --- a/src/Reactor.hpp +++ b/src/Reactor.hpp @@ -131,15 +131,16 @@ namespace dsl { template WatchdogServicer ServiceWatchdog(); } // namespace emit - } // namespace word + } // namespace word } // namespace dsl /** - * @brief Base class for any system that wants to react to events/data from the rest of the system. + * Base class for any system that wants to react to events/data from the rest of the system. * - * @details - * Provides functionality for binding callbacks to incoming data events. Callbacks are executed - * in a transparent, multithreaded manner. TODO needs to be expanded and updated + * Provides functionality for binding callbacks to incoming data events. + * Callbacks are executed in a transparent, multithreaded manner. + * + * TODO needs to be expanded and updated. */ class Reactor { public: @@ -164,20 +165,20 @@ class Reactor { std::vector reaction_handles{}; public: - /// @brief The powerplant that this reactor is running in + /// The powerplant that this reactor is running in PowerPlant& powerplant; - /// @brief The demangled string name of this reactor + /// The demangled string name of this reactor const std::string reactor_name{}; protected: - /// @brief The level that this reactor logs at + /// The level that this reactor logs at LogLevel log_level{LogLevel::INFO}; /*************************************************************************************************************** * The types here are imported from other contexts so that when extending from the Reactor type in normal * - * usage there does not need to be any namespace declarations on the used types. This affords a simpler API * - * for the user. * + * usage there does not need to be any namespace declarations on the used types. * + * This affords a simpler API for the user. * **************************************************************************************************************/ /// @copydoc dsl::word::Trigger @@ -304,7 +305,7 @@ class Reactor { using WATCHDOG = dsl::word::emit::Watchdog; }; - /// @brief This provides functions to modify how an on statement runs after it has been created + /// This provides functions to modify how an on statement runs after it has been created using ReactionHandle = threading::ReactionHandle; public: @@ -364,11 +365,10 @@ class Reactor { // FUNCTIONS /** - * @brief The on function is the method used to create a reaction in the NUClear system. + * The on function is the method used to create a reaction in the NUClear system. * - * @details - * This function is used to create a Reaction in the system. By providing the correct - * template parameters, this function can modify how and when this reaction runs. + * This function is used to create a Reaction in the system. + * By providing the correct template parameters, this function can modify how and when this reaction runs. * * @tparam DSL The NUClear domain specific language information * @tparam Arguments The types of the arguments passed into the function @@ -387,13 +387,11 @@ class Reactor { } /** - * @brief Emits data into the system so that other reactors can use it. - * - * @details - * This function emits data to the rest of the system so that it can be used. - * This results in it being the new data used when a with is used, and triggering - * any reaction that is set to be triggered on this data type. + * Emits data into the system so that other reactors can use it. * + * This function emits data to the rest of the system so that it can be used. + * This results in it being the new data used when a with is used, and triggering any reaction that is set to be + * triggered on this data type. * * @tparam Handlers The handlers for this emit (e.g. LOCAL, NETWORK etc) * @tparam T The type of the data we are emitting, for some handlers (e.g. WATCHDOG) this is optional @@ -414,11 +412,9 @@ class Reactor { } /** - * @brief Log a message through NUClear's system. + * Log a message through NUClear's system. * - * @details - * Logs a message through the system so the various log handlers - * can access it. + * Logs a message through the system so the various log handlers can access it. * * @tparam level The level to log at (defaults to DEBUG) * @tparam Arguments The types of the arguments we are logging diff --git a/src/clock.hpp b/src/clock.hpp index 9526f6450..5acb0d088 100644 --- a/src/clock.hpp +++ b/src/clock.hpp @@ -36,14 +36,15 @@ namespace NUClear { /** - * @brief A clock class that extends a base clock type and allows for clock adjustment and setting. + * A clock class that extends a base clock type and allows for clock adjustment and setting. */ template struct nuclear_clock : public NUCLEAR_CLOCK_TYPE { using base_clock = NUCLEAR_CLOCK_TYPE; /** - * @brief Get the current time of the clock. + * Get the current time of the clock. + * * @return The current time of the clock. */ static time_point now() { @@ -52,9 +53,10 @@ struct nuclear_clock : public NUCLEAR_CLOCK_TYPE { } /** - * @brief Adjust the clock by a specified duration and real-time factor. + * Adjust the clock by a specified duration and real-time factor. + * * @param adjustment The duration by which to adjust the clock. - * @param rtf The real-time factor to apply to the clock. + * @param rtf The real-time factor to apply to the clock. */ static void adjust_clock(const duration& adjustment, const double& rtf = 1.0) { const std::lock_guard lock(mutex); @@ -72,9 +74,10 @@ struct nuclear_clock : public NUCLEAR_CLOCK_TYPE { } /** - * @brief Set the clock to a specified time and real-time factor. + * Set the clock to a specified time and real-time factor. + * * @param time The time to set the clock to. - * @param rtf The real-time factor to apply to the clock. + * @param rtf The real-time factor to apply to the clock. */ static void set_clock(const time_point& time, const double& rtf = 1.0) { const std::lock_guard lock(mutex); @@ -92,7 +95,8 @@ struct nuclear_clock : public NUCLEAR_CLOCK_TYPE { /** - * @brief Get the real-time factor of the clock. + * Get the real-time factor of the clock. + * * @return The real-time factor of the clock. */ static double rtf() { @@ -101,10 +105,13 @@ struct nuclear_clock : public NUCLEAR_CLOCK_TYPE { private: /** - * @brief Convert a duration to the clock's duration type. + * Convert a duration to the clock's duration type. + * * @tparam T The type of the duration. + * * @param t The duration to convert. - * @return The converted duration. + * + * @return The converted duration. */ template duration static dc(const T& t) { @@ -112,7 +119,7 @@ struct nuclear_clock : public NUCLEAR_CLOCK_TYPE { } /** - * @brief Data structure to hold clock information. + * Data structure to hold clock information. */ struct ClockData { /// When the clock was last updated under the true time @@ -125,13 +132,13 @@ struct nuclear_clock : public NUCLEAR_CLOCK_TYPE { ClockData() = default; }; - /// @brief The mutex to protect the clock data. + /// The mutex to protect the clock data static std::mutex mutex; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) - /// @brief The clock data for the system. + /// The clock data for the system static std::array data; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) - /// @brief The active clock data index. + /// The active clock data index static std::atomic active; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) }; diff --git a/src/dsl/Fusion.hpp b/src/dsl/Fusion.hpp index 046031ab2..a164cef97 100644 --- a/src/dsl/Fusion.hpp +++ b/src/dsl/Fusion.hpp @@ -35,7 +35,7 @@ namespace NUClear { namespace dsl { - /// @brief All of the words from a reaction handle "fused" together into one type + /// All of the words from a reaction handle "fused" together into one type template struct Fusion : public fusion::BindFusion diff --git a/src/dsl/fusion/BindFusion.hpp b/src/dsl/fusion/BindFusion.hpp index dfba839c1..838046c6e 100644 --- a/src/dsl/fusion/BindFusion.hpp +++ b/src/dsl/fusion/BindFusion.hpp @@ -33,7 +33,7 @@ namespace dsl { namespace fusion { /** - * @brief This is our Function Fusion wrapper class that allows it to call bind functions + * This is our Function Fusion wrapper class that allows it to call bind functions. * * @tparam Function the bind function that we are wrapping for * @tparam DSL the DSL that we pass to our bind function @@ -42,7 +42,8 @@ namespace dsl { struct BindCaller { /** - * @brief This struct is used if there is a return type. It just passes the returned data back up. + * This struct is used if there is a return type. + * It just passes the returned data back up. * * @return the data that is returned by the bind call */ @@ -54,8 +55,8 @@ namespace dsl { }; /** - * @brief This struct is used if the return type of the bind function is void. It wraps it into an empty - * tuple instead. + * This struct is used if the return type of the bind function is void. + * It wraps it into an empty tuple instead. * * @return an empty tuple */ @@ -89,11 +90,11 @@ namespace dsl { struct BindWords; /** - * @brief Metafunction that extracts all of the Words with a bind function + * Metafunction that extracts all of the Words with a bind function. * - * @tparam Word1 The word we are looking at - * @tparam WordN The words we have yet to look at - * @tparam FoundWords The words we have found with bind functions + * @tparam Word1 The word we are looking at + * @tparam WordN The words we have yet to look at + * @tparam FoundWords The words we have found with bind functions */ template struct BindWords, std::tuple> @@ -102,7 +103,7 @@ namespace dsl { /*F*/ BindWords, std::tuple>> {}; /** - * @brief Termination case for the BindWords metafunction + * Termination case for the BindWords metafunction * * @tparam FoundWords The words we have found with bind functions */ diff --git a/src/dsl/fusion/GetFusion.hpp b/src/dsl/fusion/GetFusion.hpp index 26a7ff8fa..b4a42f3ed 100644 --- a/src/dsl/fusion/GetFusion.hpp +++ b/src/dsl/fusion/GetFusion.hpp @@ -33,7 +33,7 @@ namespace dsl { namespace fusion { /** - * @brief This is our Function Fusion wrapper class that allows it to call get functions + * This is our Function Fusion wrapper class that allows it to call get functions. * * @tparam Function the get function that we are wrapping for * @tparam DSL the DSL that we pass to our get function @@ -49,7 +49,7 @@ namespace dsl { struct GetWords; /** - * @brief Metafunction that extracts all of the Words with a get function + * Metafunction that extracts all of the Words with a get function. * * @tparam Word1 the word we are looking at * @tparam WordN the words we have yet to look at @@ -62,7 +62,7 @@ namespace dsl { /*F*/ GetWords, std::tuple>> {}; /** - * @brief Termination case for the GetWords metafunction + * Termination case for the GetWords metafunction. * * @tparam GetWords The words we have found with get functions */ diff --git a/src/dsl/fusion/GroupFusion.hpp b/src/dsl/fusion/GroupFusion.hpp index fb71fa987..5f5493abe 100644 --- a/src/dsl/fusion/GroupFusion.hpp +++ b/src/dsl/fusion/GroupFusion.hpp @@ -44,11 +44,11 @@ namespace dsl { struct GroupWords; /** - * @brief Metafunction that extracts all of the Words with a group function + * Metafunction that extracts all of the Words with a group function. * - * @tparam Word1 The word we are looking at - * @tparam WordN The words we have yet to look at - * @tparam FoundWords The words we have found with group functions + * @tparam Word1 The word we are looking at + * @tparam WordN The words we have yet to look at + * @tparam FoundWords The words we have found with group functions */ template struct GroupWords, std::tuple> @@ -58,7 +58,7 @@ namespace dsl { /*F*/ GroupWords, std::tuple>> {}; /** - * @brief Termination case for the GroupWords metafunction + * Termination case for the GroupWords metafunction. * * @tparam FoundWords The words we have found with group functions */ diff --git a/src/dsl/fusion/NoOp.hpp b/src/dsl/fusion/NoOp.hpp index f33661b9e..907948def 100644 --- a/src/dsl/fusion/NoOp.hpp +++ b/src/dsl/fusion/NoOp.hpp @@ -36,8 +36,8 @@ namespace dsl { namespace fusion { /** - * @brief Struct to act as a DSL word that does nothing. Used as a placeholder to satisfy some dead template - * branches that are required for the code to compile. + * Struct to act as a DSL word that does nothing. + * Used as a placeholder to satisfy some dead template branches that are required for the code to compile. */ struct NoOp { @@ -78,8 +78,8 @@ namespace dsl { }; /** - * @brief Struct to act as Parsed DSL statement that does nothing. Used as a placeholder to satisfy some - * dead template branches that are required for the code to compile. + * Struct to act as Parsed DSL statement that does nothing. + * Used as a placeholder to satisfy some dead template branches that are required for the code to compile. */ struct ParsedNoOp { struct DSL {}; diff --git a/src/dsl/fusion/PoolFusion.hpp b/src/dsl/fusion/PoolFusion.hpp index 795dcb3f9..b14c7302b 100644 --- a/src/dsl/fusion/PoolFusion.hpp +++ b/src/dsl/fusion/PoolFusion.hpp @@ -44,11 +44,11 @@ namespace dsl { struct PoolWords; /** - * @brief Metafunction that extracts all of the Words with a pool function + * Metafunction that extracts all of the Words with a pool function. * - * @tparam Word1 The word we are looking at - * @tparam WordN The words we have yet to look at - * @tparam FoundWords The words we have found with pool functions + * @tparam Word1 The word we are looking at + * @tparam WordN The words we have yet to look at + * @tparam FoundWords The words we have found with pool functions */ template struct PoolWords, std::tuple> @@ -58,7 +58,7 @@ namespace dsl { /*F*/ PoolWords, std::tuple>> {}; /** - * @brief Termination case for the PoolWords metafunction + * Termination case for the PoolWords metafunction. * * @tparam FoundWords The words we have found with pool functions */ diff --git a/src/dsl/fusion/PostconditionFusion.hpp b/src/dsl/fusion/PostconditionFusion.hpp index 1a926233a..754846768 100644 --- a/src/dsl/fusion/PostconditionFusion.hpp +++ b/src/dsl/fusion/PostconditionFusion.hpp @@ -41,11 +41,11 @@ namespace dsl { struct PostconditionWords; /** - * @brief Metafunction that extracts all of the Words with a postcondition function + * Metafunction that extracts all of the Words with a postcondition function. * - * @tparam Word1 The word we are looking at - * @tparam WordN The words we have yet to look at - * @tparam FoundWords The words we have found with postcondition functions + * @tparam Word1 The word we are looking at + * @tparam WordN The words we have yet to look at + * @tparam FoundWords The words we have found with postcondition functions */ template struct PostconditionWords, std::tuple> @@ -57,7 +57,7 @@ namespace dsl { /*F*/ PostconditionWords, std::tuple>> {}; /** - * @brief Termination case for the PostconditionWords metafunction + * Termination case for the PostconditionWords metafunction. * * @tparam PostconditionWords The words we have found with postcondition functions */ diff --git a/src/dsl/fusion/PreconditionFusion.hpp b/src/dsl/fusion/PreconditionFusion.hpp index bd47ee743..68741d987 100644 --- a/src/dsl/fusion/PreconditionFusion.hpp +++ b/src/dsl/fusion/PreconditionFusion.hpp @@ -41,11 +41,11 @@ namespace dsl { struct PreconditionWords; /** - * @brief Metafunction that extracts all of the Words with a precondition function + * Metafunction that extracts all of the Words with a precondition function. * - * @tparam Word1 The word we are looking at - * @tparam WordN The words we have yet to look at - * @tparam FoundWords The words we have found with precondition functions + * @tparam Word1 The word we are looking at + * @tparam WordN The words we have yet to look at + * @tparam FoundWords The words we have found with precondition functions */ template struct PreconditionWords, std::tuple> @@ -57,7 +57,7 @@ namespace dsl { /*F*/ PreconditionWords, std::tuple>> {}; /** - * @brief Termination case for the PreconditionWords metafunction + * Termination case for the PreconditionWords metafunction. * * @tparam FoundWords The words we have found with precondition functions */ diff --git a/src/dsl/fusion/PriorityFusion.hpp b/src/dsl/fusion/PriorityFusion.hpp index dcd3bcf75..e337572e4 100644 --- a/src/dsl/fusion/PriorityFusion.hpp +++ b/src/dsl/fusion/PriorityFusion.hpp @@ -41,11 +41,11 @@ namespace dsl { struct PriorityWords; /** - * @brief Metafunction that extracts all of the Words with a priority function + * Metafunction that extracts all of the Words with a priority function. * - * @tparam Word1 The word we are looking at - * @tparam WordN The words we have yet to look at - * @tparam FoundWords The words we have found with priority functions + * @tparam Word1 The word we are looking at + * @tparam WordN The words we have yet to look at + * @tparam FoundWords The words we have found with priority functions */ template struct PriorityWords, std::tuple> @@ -55,7 +55,7 @@ namespace dsl { /*F*/ PriorityWords, std::tuple>> {}; /** - * @brief Termination case for the PriorityWords metafunction + * Termination case for the PriorityWords metafunction. * * @tparam FoundWords The words we have found with priority functions */ diff --git a/src/dsl/fusion/has_bind.hpp b/src/dsl/fusion/has_bind.hpp index 2ccc299ef..7991f5da2 100644 --- a/src/dsl/fusion/has_bind.hpp +++ b/src/dsl/fusion/has_bind.hpp @@ -31,7 +31,7 @@ namespace dsl { namespace fusion { /** - * @brief SFINAE struct to test if the passed class has a bind function that conforms to the NUClear DSL + * SFINAE struct to test if the passed class has a bind function that conforms to the NUClear DSL. * * @tparam T the class to check */ diff --git a/src/dsl/fusion/has_get.hpp b/src/dsl/fusion/has_get.hpp index ddd3b9a88..0649519ce 100644 --- a/src/dsl/fusion/has_get.hpp +++ b/src/dsl/fusion/has_get.hpp @@ -31,7 +31,7 @@ namespace dsl { namespace fusion { /** - * @brief SFINAE struct to test if the passed class has a get function that conforms to the NUClear DSL + * SFINAE struct to test if the passed class has a get function that conforms to the NUClear DSL. * * @tparam T the class to check */ diff --git a/src/dsl/fusion/has_group.hpp b/src/dsl/fusion/has_group.hpp index 611ff96ea..6c2a83d82 100644 --- a/src/dsl/fusion/has_group.hpp +++ b/src/dsl/fusion/has_group.hpp @@ -31,7 +31,7 @@ namespace dsl { namespace fusion { /** - * @brief SFINAE struct to test if the passed class has a group function that conforms to the NUClear DSL + * SFINAE struct to test if the passed class has a group function that conforms to the NUClear DSL. * * @tparam T the class to check */ @@ -42,8 +42,8 @@ namespace dsl { using no = std::false_type; template - static auto test(int) - -> decltype(U::template group(std::declval()), yes()); + static auto test(int) -> decltype(U::template group(std::declval()), + yes()); template static no test(...); diff --git a/src/dsl/fusion/has_pool.hpp b/src/dsl/fusion/has_pool.hpp index 8ec86e103..9715e7b3a 100644 --- a/src/dsl/fusion/has_pool.hpp +++ b/src/dsl/fusion/has_pool.hpp @@ -31,7 +31,7 @@ namespace dsl { namespace fusion { /** - * @brief SFINAE struct to test if the passed class has a pool function that conforms to the NUClear DSL + * SFINAE struct to test if the passed class has a pool function that conforms to the NUClear DSL. * * @tparam T the class to check */ @@ -42,8 +42,8 @@ namespace dsl { using no = std::false_type; template - static auto test(int) - -> decltype(U::template pool(std::declval()), yes()); + static auto test(int) -> decltype(U::template pool(std::declval()), + yes()); template static no test(...); diff --git a/src/dsl/fusion/has_postcondition.hpp b/src/dsl/fusion/has_postcondition.hpp index fcd6c26dd..d782ab43a 100644 --- a/src/dsl/fusion/has_postcondition.hpp +++ b/src/dsl/fusion/has_postcondition.hpp @@ -31,8 +31,7 @@ namespace dsl { namespace fusion { /** - * @brief SFINAE struct to test if the passed class has a postcondition function that conforms to the - * NUClear DSL + * SFINAE struct to test if the passed class has a postcondition function that conforms to the NUClear DSL. * * @tparam T the class to check */ diff --git a/src/dsl/fusion/has_precondition.hpp b/src/dsl/fusion/has_precondition.hpp index cc512c4b8..4fa9e36f9 100644 --- a/src/dsl/fusion/has_precondition.hpp +++ b/src/dsl/fusion/has_precondition.hpp @@ -31,8 +31,7 @@ namespace dsl { namespace fusion { /** - * @brief SFINAE struct to test if the passed class has a precondition function that conforms to the - * NUClear DSL + * SFINAE struct to test if the passed class has a precondition function that conforms to the NUClear DSL. * * @tparam T the class to check */ diff --git a/src/dsl/fusion/has_priority.hpp b/src/dsl/fusion/has_priority.hpp index 212580265..e033b2716 100644 --- a/src/dsl/fusion/has_priority.hpp +++ b/src/dsl/fusion/has_priority.hpp @@ -31,7 +31,7 @@ namespace dsl { namespace fusion { /** - * @brief SFINAE struct to test if the passed class has a priority function that conforms to the NUClear DSL + * SFINAE struct to test if the passed class has a priority function that conforms to the NUClear DSL. * * @tparam T the class to check */ @@ -42,8 +42,8 @@ namespace dsl { using no = std::false_type; template - static auto test(int) - -> decltype(U::template priority(std::declval()), yes()); + static auto test(int) -> decltype(U::template priority(std::declval()), + yes()); template static no test(...); diff --git a/src/dsl/operation/CacheGet.hpp b/src/dsl/operation/CacheGet.hpp index 4796cd28c..91b640226 100644 --- a/src/dsl/operation/CacheGet.hpp +++ b/src/dsl/operation/CacheGet.hpp @@ -30,11 +30,11 @@ namespace dsl { namespace operation { /** - * @brief Accesses a variable from the shared data cache when used. + * Accesses a variable from the shared data cache when used. * - * @details NUClear maintains a datastore of the latest data emitted of each type in the system. - * This utility type accesses this shared cache and accesses the latest data using get. - * To use this utility inherit from this type with the DataType to listen for. + * NUClear maintains a datastore of the latest data emitted of each type in the system. + * This utility type accesses this shared cache and accesses the latest data using get. + * To use this utility inherit from this type with the DataType to listen for. * * @tparam DataType the data type that will be accessed from the cache */ diff --git a/src/dsl/operation/ChronoTask.hpp b/src/dsl/operation/ChronoTask.hpp index f270fd262..362270e8c 100644 --- a/src/dsl/operation/ChronoTask.hpp +++ b/src/dsl/operation/ChronoTask.hpp @@ -31,23 +31,22 @@ namespace dsl { namespace operation { /** - * @brief Emit to schedule a function to be run at a particular time. + * Emit to schedule a function to be run at a particular time. * - * @details When the Chrono system is running, tasks emitted using this struct will be scheduled to execute - * at the given time and are passed this time as a reference. The return value from this function - * is used to indicate that the function should be called again in the future. If it is true the - * function will not be purged after execution. If the task is to be executed again it should - * modify the time reference to the next time that this should be executed. + * When the Chrono system is running, tasks emitted using this struct will be scheduled to execute at the given + * time and are passed this time as a reference. + * The return value from this function is used to indicate that the function should be called again. + * If it is true the function will not be purged after execution. + * If the task is to be executed again it should modify the time reference to the next time to be executed. */ struct ChronoTask { /** - * @brief Constructs a new ChronoTask to execute + * Constructs a new ChronoTask to execute. * - * @param task the task to run, takes the time to execute as a reference so it can be updated for - * future runs - * @param time the time to execute this task - * @param id the unique identifier for this task + * @param task The task to run, takes the time to execute as a reference so it can be updated + * @param time The time to execute this task + * @param id The unique identifier for this task */ ChronoTask(std::function&& task, const NUClear::clock::time_point& time, @@ -55,42 +54,42 @@ namespace dsl { : task(std::move(task)), time(time), id(id) {} /** - * @brief Run the task and return true if the time has been updated to run again + * Run the task and return true if the time has been updated to run again. * - * @return true if the task updated the time to run to a new time + * @return `true` if the task updated the time to run to a new time */ inline bool operator()() { return task(time); } /** - * @brief Compares tasks in order of soonest to execute first + * Compares tasks in order of soonest to execute first. * - * @param other the other task to compare to + * @param other The other task to compare to * - * @return true if the other task is after this task + * @return `true` if the other task is after this task */ inline bool operator<(const ChronoTask& other) const { return time < other.time; } /** - * @brief Compares tasks in order of soonest to execute first + * Compares tasks in order of soonest to execute first. * - * @param other the other task to compare to + * @param other The other task to compare to * - * @return true if the other task is before this task + * @return `true` if the other task is before this task */ inline bool operator>(const ChronoTask& other) const { return time > other.time; } /** - * @brief Check if tasks share the same execution time + * Check if tasks share the same execution time. * - * @param other the other task to compare to + * @param other The other task to compare to * - * @return true if the other task is at the same time as this task + * @return `true` if the other task is at the same time as this task */ inline bool operator==(const ChronoTask& other) const { return time == other.time; @@ -108,4 +107,4 @@ namespace dsl { } // namespace dsl } // namespace NUClear -#endif // NUCLEAR_DSL_OPERATION_TYPEBIND_HPP +#endif // NUCLEAR_DSL_OPERATION_CHRONOTASK_HPP diff --git a/src/dsl/operation/DSLProxy.hpp b/src/dsl/operation/DSLProxy.hpp index 5c4654bda..295bbf4d6 100644 --- a/src/dsl/operation/DSLProxy.hpp +++ b/src/dsl/operation/DSLProxy.hpp @@ -28,14 +28,13 @@ namespace dsl { namespace operation { /** - * @brief A proxy template to be used to provide NUClear DSL methods without altering the original object + * A proxy template to be used to provide NUClear DSL methods without altering the original object * - * @details - * Sometimes you want to make a type part of the DSL but cannot (or don't want to) alter the original - * object. In this case you are able to partially specialise this type and it will be used instead - * if the original does not have the functions needed. + * Sometimes you want to make a type part of the DSL but cannot (or don't want to) alter the original object. + * In this case you are able to partially specialise this type and it will be used instead if the original does + * not have the functions needed. * - * @tparam Word the type that will act as the DSL word + * @tparam Word The type that will act as the DSL word */ template struct DSLProxy {}; diff --git a/src/dsl/operation/TypeBind.hpp b/src/dsl/operation/TypeBind.hpp index aa3adeed1..56a7c528e 100644 --- a/src/dsl/operation/TypeBind.hpp +++ b/src/dsl/operation/TypeBind.hpp @@ -30,12 +30,12 @@ namespace dsl { namespace operation { /** - * @brief Binds a function to execute when a specific type is emitted + * Binds a function to execute when a specific type is emitted. * - * @details A common pattern in NUClear is to execute a function when a particular type is emitted. - * This utility class is used to simplify executing a function when a type is emitted. - * To use this utility inherit from this type with the DataType to listen for. - * If the callback also needs the data emitted you should also extend from CacheGet + * A common pattern in NUClear is to execute a function when a particular type is emitted. + * This utility class is used to simplify executing a function when a type is emitted. + * To use this utility inherit from this type with the DataType to listen for. + * If the callback also needs the data emitted you should also extend from CacheGet. * * @tparam DataType the data type that will be bound to */ diff --git a/src/dsl/operation/Unbind.hpp b/src/dsl/operation/Unbind.hpp index 23b60d5e3..0d4b18363 100644 --- a/src/dsl/operation/Unbind.hpp +++ b/src/dsl/operation/Unbind.hpp @@ -30,17 +30,17 @@ namespace dsl { namespace operation { /** - * @brief Signals that the reaction with this id servicing this type should be unbound and its resources - * cleaned up + * Signals that the reaction with this id servicing this type should be unbound and its resources cleaned up. * - * @details When a reaction is finished and won't be run again, this type should be emitted along with the - * original DSL word that created it. This signals to its handler to clean it up and not run it again. + * When a reaction is finished and won't be run again, this type should be emitted along with the original DSL + * word that created it. + * This signals to its handler to clean it up and not run it again. * - * @tparam Word the DSL word that created this binding (or another helper type) + * @tparam Word The DSL word that created this binding (or another helper type) */ template struct Unbind { - explicit Unbind(const NUClear::id_t& id) : id(id){}; + explicit Unbind(const NUClear::id_t& id) : id(id) {}; /// The id of the task to unbind const NUClear::id_t id{0}; diff --git a/src/dsl/store/DataStore.hpp b/src/dsl/store/DataStore.hpp index 0c037a021..ed04cccb1 100644 --- a/src/dsl/store/DataStore.hpp +++ b/src/dsl/store/DataStore.hpp @@ -32,11 +32,12 @@ namespace dsl { namespace store { /** - * @brief The main datastore used in the system. + * The main datastore used in the system. * - * @details This datastore is the main one used by the system. When data is emitted it is stored in this - * typed datastore. This allows constant time access to any datatype without having to look it up. - * This is possible as the exact location of the store is known at compile time. + * This datastore is the main one used by the system. + * When data is emitted it is stored in this typed datastore. + * This allows constant time access to any datatype without having to look it up. + * This is possible as the exact location of the store is known at compile time. * * @tparam DataType the type of data stored in this particular datastore location */ diff --git a/src/dsl/store/ThreadStore.hpp b/src/dsl/store/ThreadStore.hpp index 26bd08902..12c1ea942 100644 --- a/src/dsl/store/ThreadStore.hpp +++ b/src/dsl/store/ThreadStore.hpp @@ -30,15 +30,15 @@ namespace dsl { namespace store { /** - * @brief Thread local datastore used for out of band communication. + * Thread local datastore used for out of band communication. * - * @details In NUClear, there is a disjoint that must exist between reactions which are opaque and the - * internals of these reactions which are strongly typed to ensure speed. This creates a problem - * where handlers for reactions want to pass data to them but cannot directly access them. This - * datastore is used in this case to provide thread local storage that is typed. Using this - * variable a handler can store a stack variable it has and when it generates a ReactionTask as - * that happens on the same thread, the get functions inside can access this same variable to - * bypass the opaque barrier between the handler and the reaction. + * In NUClear, there is a disjoint that must exist between reactions which are opaque and the internals of these + * reactions which are strongly typed to ensure speed. + * This creates a problem where handlers for reactions want to pass data but cannot directly access them. + * This datastore is used in this case to provide thread local storage that is typed. + * Using this variable a handler can store a stack variable it has and when it generates a ReactionTask as that + * happens on the same thread, the get functions inside can access this same variable to bypass the opaque + * barrier between the handler and the reaction. * * @tparam DataType the datatype that is to be stored * @tparam Index an optional index that can be used in the event that multiple variables of the same type diff --git a/src/dsl/store/TypeCallbackStore.hpp b/src/dsl/store/TypeCallbackStore.hpp index bb1e085a7..5d0f6f959 100644 --- a/src/dsl/store/TypeCallbackStore.hpp +++ b/src/dsl/store/TypeCallbackStore.hpp @@ -33,13 +33,13 @@ namespace dsl { namespace store { /** - * @brief The main callback store for reactions that are executed when a particular type is emitted. + * The main callback store for reactions that are executed when a particular type is emitted. * - * @details This store is the main location that callbacks that are executed on type are stored. - * This method of storing is how the system realises compile time message dispatch. By storing each - * different type of message user in its own location the system knows exactly which reactions to - * executing without having to do an expensive lookup. This reduces the latency and computational - * power involved in spawning a new reaction when a type is emitted. + * This store is the main location that callbacks that are executed on type are stored. + * This method of storing is how the system realises compile time message dispatch. + * By storing each different type of message user in its own location the system knows exactly which reactions + * to executing without having to do an expensive lookup. + * This reduces the latency and computational power involved in spawning a new reaction when a type is emitted. * * @tparam TriggeringType the type that when emitted will start this function */ diff --git a/src/dsl/trait/is_transient.hpp b/src/dsl/trait/is_transient.hpp index 9c287926e..1a8d9a0fc 100644 --- a/src/dsl/trait/is_transient.hpp +++ b/src/dsl/trait/is_transient.hpp @@ -28,13 +28,13 @@ namespace dsl { namespace trait { /** - * @brief Indicates that a type is transient in the context of data availablity + * Indicates that a type is transient in the context of data availability. * - * @details Often when extending the get dsl attachment point, data from that get is only available when - * that get is run in specific circumstances such as from a ThreadStore. - * When this trait is true, Reactors handle this data being unavaible differently. - * They will instead cache the last copy of the data that was provided and if no new data - * comes from the get function, they will instead provide this cached data. + * Often when extending the get dsl attachment point, data from that get is only available when that get is run + * in specific circumstances such as from a ThreadStore. + * When this trait is true, Reactors handle this data being unavailable differently. + * They will instead cache the last copy of the data that was provided and if no new data comes from the get + * function, they will instead provide this cached data. * * @see NUClear::dsl::store::ThreadStore * diff --git a/src/dsl/validation/Validation.hpp b/src/dsl/validation/Validation.hpp index 33a4f2a65..3fbc30402 100644 --- a/src/dsl/validation/Validation.hpp +++ b/src/dsl/validation/Validation.hpp @@ -30,13 +30,13 @@ namespace dsl { namespace validation { /** - * @brief Validates the provided DSL is able to be used by the system and give a more sensible error + * Validates the provided DSL is able to be used by the system and give a more sensible error. * - * @details This is where checks to see if the DSL words that were provided make sense and are useable. - * For example, it will check to make sure there is at least one bind function there. If there is - * not a bind function, there is no way the provided callback will ever run. + * This is where checks to see if the DSL words that were provided make sense and are useable. + * For example, it will check to make sure there is at least one bind function there. + * If there is not a bind function, there is no way the provided callback will ever run. * - * @tparam Words the DSL words to be validated + * @tparam Words The DSL words to be validated */ template struct ValidateDSL { diff --git a/src/dsl/word/Always.hpp b/src/dsl/word/Always.hpp index 70e328268..5ac74d94a 100644 --- a/src/dsl/word/Always.hpp +++ b/src/dsl/word/Always.hpp @@ -36,19 +36,17 @@ namespace dsl { namespace word { /** - * @brief - * This is used to request any continuous reactions in the system. + * This is used to request any continuous reactions in the system. * - * @details - * @code on @endcode - * This request will ensure a single instance of the associated reaction is running at all times. - * That is, as one instance is completed, a new instance of the task will spawn. + * @code on @endcode + * This request will ensure a single instance of the associated reaction is running at all times. + * That is, as one instance is completed, a new instance of the task will spawn. * - * Any reactions requested using this keyword will initialise upon system start-up and execute continually - * until system shut-down. + * Any reactions requested using this keyword will initialise upon system start-up and execute continually + * until system shut-down. * - * Note that a task spawned from this request will execute in its own unique thread rather than the default - * thread pool. + * @note + * A task spawned from this request will execute in its own unique thread rather than the default thread pool. * * @par Infinite Loops * This word should be used in place of any reactions which would contain an infinite loop. That is, @@ -96,16 +94,17 @@ namespace dsl { reaction_store = {}; /** - * Generate a new reaction for an idle task + * Generate a new reaction for an idle task. + * * The purpose of this reaction is to ensure that the always reaction is resubmitted in the event that - * the precondition fails (e.g. on> will fail the precondition if there are no X + * the precondition fails. (e.g. on> will fail the precondition if there are no X * messages previously emitted) * * In the event that the precondition on the always reaction fails this idle task will run and resubmit - * both the always reaction and the idle reaction + * both the always reaction and the idle reaction. * * The idle reaction must have a lower priority than the always reaction and must also run in the same - * thread pool and group as the always reaction + * thread pool and group as the always reaction. */ auto idle_reaction = std::make_shared( always_reaction->reactor, diff --git a/src/dsl/word/Buffer.hpp b/src/dsl/word/Buffer.hpp index 9d6a1d19e..8fb42a5ea 100644 --- a/src/dsl/word/Buffer.hpp +++ b/src/dsl/word/Buffer.hpp @@ -30,20 +30,18 @@ namespace dsl { namespace word { /** - * @brief - * This is used to specify that up to n instances of the associated reaction can execute during runtime. + * This is used to specify that up to n instances of the associated reaction can execute during runtime. * - * @details - * @code on, Buffer>>() @endcode - * In the case above, when the subscribing reaction is triggered, should there be less than n existing + * @code on, Buffer>>() @endcode + * In the case above, when the subscribing reaction is triggered, should there be less than n existing * tasks associated with this reaction (either executing or in the queue), then a new task will be created and - * scheduled. However, should n tasks already be allocated, then this new task request will be ignored. + * scheduled. + * However, should n tasks already be allocated, then this new task request will be ignored. * * @par Implements * Precondition, Fusion * - * @tparam n - * the number of tasks (instances of the subscribing reaction) which can be running at a given time. + * @tparam n The number of tasks (instances of the subscribing reaction) which can be running at a given time. */ template struct Buffer { diff --git a/src/dsl/word/Every.hpp b/src/dsl/word/Every.hpp index 14b4cf1f7..cd9340d88 100644 --- a/src/dsl/word/Every.hpp +++ b/src/dsl/word/Every.hpp @@ -35,8 +35,7 @@ namespace dsl { namespace word { /** - * @brief - * This type is used within an every in order to measure a frequency rather then a period. + * This type is used within an every in order to measure a frequency rather then a period. */ template struct Per; @@ -49,21 +48,19 @@ namespace dsl { }; /** - * @brief - * This is used to request any periodic reactions in the system. + * This is used to request any periodic reactions in the system. * - * @details - * @code on>() @endcode - * This request will enact the execution of a task at a periodic rate. To set the timing, simply specify the - * desired period with the request. For example, to run a task every two seconds, the following request would - * be used: * - * @code on() @endcode + * @code on>() @endcode + * This request will enact the execution of a task at a periodic rate. + * To set the timing, simply specify the desired period with the request. + * For example, to run a task every two seconds, the following request would be used: + * @code on() @endcode * - * Note that the period argument can also be wrapped in a Per<> template so that the inverse relation - * can be invoked. For instance, to execute a callback to initialise two tasks every second, then the - * request would be used: - * @code on>() @endcode + * Note that the period argument can also be wrapped in a Per<> template so that the inverse relation can be + * invoked. + * For instance, to execute a callback to initialise two tasks every second, then the request would be used: + * @code on>() @endcode * * @attention * The period which is used to measure the ticks must be greater than or equal to clock::duration or the @@ -72,13 +69,12 @@ namespace dsl { * @par Implements * Bind * - * @tparam ticks - * the number of ticks of a particular type to wait - * @tparam period - * a type of duration (e.g. std::chrono::seconds) to measure the ticks in. This will default to clock - * duration, but can accept any of the defined std::chrono durations (nanoseconds, microseconds, milliseconds, - * seconds, minutes, hours). Note that you can also define your own unit: See - * http://en.cppreference.com/w/cpp/chrono/duration + * @tparam ticks The number of ticks of a particular type to wait + * @tparam period A type of duration (e.g. std::chrono::seconds) to measure the ticks in. + * This will default to clock duration, but can accept any of the defined std::chrono durations. + * i.e. nanoseconds, microseconds, milliseconds, seconds, minutes, hours. + * Note that you can also define your own unit. + * See http://en.cppreference.com/w/cpp/chrono/duration */ template struct Every; diff --git a/src/dsl/word/Group.hpp b/src/dsl/word/Group.hpp index d8eaa7211..9464ead03 100644 --- a/src/dsl/word/Group.hpp +++ b/src/dsl/word/Group.hpp @@ -35,34 +35,34 @@ namespace dsl { namespace word { /** - * @brief - * This is used to specify that up to GroupConcurrency reactions in this GroupType can run concurrently. + * This is used to specify that up to GroupConcurrency reactions in this GroupType can run concurrently. * - * @details - * @code on, Group>() @endcode - * When a group of tasks has been synchronised, only N task(s) from the group will execute at a given time. + * @code on, Group>() @endcode + * When a group of tasks has been synchronised, only N task(s) from the group will execute at a given time. * - * Should another task from this group be scheduled/requested (during execution of the current N task(s)), it - * will be sidelined into the task queue. + * Should another task from this group be scheduled/requested (during execution of the current N task(s)), it + * will be sidelined into the task queue. * - * Tasks in the queue are ordered based on their priority level, then their task id. + * Tasks in the queue are ordered based on their priority level, then their task id. * * @attention - * When using NUClear, developers should be careful when using devices like a mutex. In the case of a mutex, - * threads will run and then block (leading to wasted resources on a number of inactive threads). By using - * Sync, NUClear will have task and thread control so that system resources can be efficiently managed. + * When using NUClear, developers should be careful when using devices like a mutex. + * In the case of a mutex, threads will run and then block. + * This will potentially lead to wasted resources on a number of inactive threads. + * By using Sync, NUClear will have task and thread control so system resources can be efficiently managed. * * @par Implements * Group * - * @tparam GroupType - * the type/group to synchronize on. This needs to be a declared type within the system. It is common to - * simply use the reactors name (i.e; if the reactor is only syncing with one group). Should more than one - * group be required, the developer can declare structs within the system, to act as a group reference. - * Note that the developer is not limited to the use of a struct; any declared type will work. - * @tparam GroupConcurrency - * the number of tasks that should be allowed to run concurrently in this group. It is an error to specify a - * group concurrency less than 1. + * @tparam GroupType The type/group to synchronize on. + * This needs to be a declared type within the system. + * It is common to simply use the reactors name for a reactor with one group. + * Should more than one group be required, the developer can declare structs within the + * system, to act as a group reference. + * Note that the developer is not limited to the use of a struct; any declared type + * will work. + * @tparam GroupConcurrency The number of tasks that should be allowed to run concurrently in this group. + * It is an error to specify a group concurrency less than 1. */ template struct Group { diff --git a/src/dsl/word/IO.hpp b/src/dsl/word/IO.hpp index 14a890cc2..4f2390725 100644 --- a/src/dsl/word/IO.hpp +++ b/src/dsl/word/IO.hpp @@ -43,55 +43,52 @@ namespace dsl { #endif /** - * @brief This message is sent to the IO controller to configure a new IO operation. + * This message is sent to the IO controller to configure a new IO operation. */ struct IOConfiguration { IOConfiguration(fd_t fd, event_t events, std::shared_ptr reaction) : fd(fd), events(events), reaction(std::move(reaction)) {} - /// @brief The file descriptor to watch + /// The file descriptor to watch fd_t fd; - /// @brief The events to watch for on this file descriptor + /// The events to watch for on this file descriptor event_t events; - /// @brief The reaction to trigger when this file descriptor has an event + /// The reaction to trigger when this file descriptor has an event std::shared_ptr reaction; }; /** - * @brief This is emitted when an IO operation has finished. + * This is emitted when an IO operation has finished. */ struct IOFinished { explicit IOFinished(const NUClear::id_t& id) : id(id) {} - /// @brief The id of the reaction that has finished + /// The id of the reaction that has finished NUClear::id_t id; }; /** - * @brief - * This is used to trigger reactions based on standard I/O operations using file descriptors. + * This is used to trigger reactions based on standard I/O operations using file descriptors. * - * @details - * @code on(file_descriptor) @endcode - * This function works for any I/O communication which uses a file descriptor. The associated reaction is - * triggered when the communication line matches the descriptor. + * @code on(file_descriptor) @endcode + * This function works for any I/O communication which uses a file descriptor. + * The associated reaction is triggered when the communication line matches the descriptor. * - * When using this feature, runtime arguments should be provided, to specify the file descriptor. + * When using this feature, runtime arguments should be provided, to specify the file descriptor. * - * Example Use + * Example Use * - * File reading: triggers a reaction when the pipe/stream/communication line has data available to read. - * @code on(pipe/stream/comms, IO::READ) @endcode - * File writing: triggers a reaction when the pipe/stream/communication line has data to be written. - * @code on(pipe/stream/comms, IO::WRITE) @endcode - * File close: triggers a reaction when the pipe/stream/communication line is closed. - * @code on(pipe/stream/comms, IO::CLOSE) @endcode - * File error: triggers a reaction when the pipe/stream/communication line reports an error. - * @code on(pipe/stream/comms, IO::CLOSE) @endcode - * Multiple states: this feature can trigger a reaction when the pipe/stream/communication line - * matches multiple states. For example; - * @code on(pipe/stream/comms, IO::READ | IO::ERROR) @endcode + * File reading: triggers a reaction when the file descriptor has data available to read. + * @code on(pipe/stream/comms, IO::READ) @endcode + * File writing: triggers a reaction when the file descriptor has data to be written. + * @code on(pipe/stream/comms, IO::WRITE) @endcode + * File close: triggers a reaction when the file descriptor is closed. + * @code on(pipe/stream/comms, IO::CLOSE) @endcode + * File error: triggers a reaction when the file descriptor reports an error. + * @code on(pipe/stream/comms, IO::CLOSE) @endcode + * Multiple states: this feature can trigger a reaction when the file descriptor matches multiple states. + * @code on(pipe/stream/comms, IO::READ | IO::ERROR) @endcode * * @attention - * Note that reactions triggered by an on request are implicitly single. + * While a reaction is processing an IO event, no other IO triggers will fire until the reaction has completed. * * @par Implements * Bind @@ -118,12 +115,12 @@ namespace dsl { #endif struct Event { - /// @brief The file descriptor that this event is for + /// The file descriptor that this event is for fd_t fd; - /// @brief The events that have occurred on this file descriptor + /// The events that have occurred on this file descriptor event_t events; - /// @brief Returns true if the event is for the given event type + /// Returns true if the event is for the given event type operator bool() const { return fd != INVALID_SOCKET; } @@ -165,11 +162,10 @@ namespace dsl { } // namespace word namespace trait { - template <> struct is_transient : public std::true_type {}; - } // namespace trait + } // namespace dsl } // namespace NUClear diff --git a/src/dsl/word/Idle.hpp b/src/dsl/word/Idle.hpp index beb64f90b..cb5eab4ae 100644 --- a/src/dsl/word/Idle.hpp +++ b/src/dsl/word/Idle.hpp @@ -37,7 +37,7 @@ namespace dsl { namespace word { /** - * @brief A base type to handle the common code for idling after turning the pool descriptor into an id. + * A base type to handle the common code for idling after turning the pool descriptor into an id. */ inline void bind_idle(const std::shared_ptr& reaction, const util::ThreadPoolDescriptor& pool_descriptor) { @@ -53,18 +53,16 @@ namespace dsl { } /** - * @brief Execute a task when there is nothing currently running on the thread pool. + * Execute a task when there is nothing currently running on the thread pool. * - * @details - * @code on>() @endcode - * When the thread pool is idle, this task will be executed. This is use + * @code on>() @endcode + * When the thread pool is idle, this task will be executed. * * @par Implements * Bind * - * @tparam PoolType the descriptor that was used to create the thread pool - * void for the default pool - * MainThread for the main thread pool + * @tparam PoolType The descriptor that was used to create the thread pool. + * `void` for the default pool MainThread for the main thread pool. */ template struct Idle { diff --git a/src/dsl/word/Last.hpp b/src/dsl/word/Last.hpp index 1bdb192b6..58d7f63c9 100644 --- a/src/dsl/word/Last.hpp +++ b/src/dsl/word/Last.hpp @@ -34,7 +34,7 @@ namespace dsl { namespace word { /** - * @brief A class that stores the last received items from a reaction + * A class that stores the last received items from a reaction * * This class stores the received items and provides conversion operators so that when passed into the reaction * it can be converted to an appropriate type. @@ -47,20 +47,20 @@ namespace dsl { LastItemStorage() = default; /** - * @brief Constructs a LastItemStorage object with the given data. + * Constructs a LastItemStorage object with the given data. * * @param data The data to store. */ explicit LastItemStorage(T&& data) : list({std::move(data)}) {} /** - * @brief Constructs a LastItemStorage object with the given data. + * Constructs a LastItemStorage object with the given data. * * @param data The data to store. */ explicit LastItemStorage(const T& data) : list({data}) {} /** - * @brief Converts the stored list to a list of the given type. + * Converts the stored list to a list of the given type. * * @tparam Output The type of the output list. * @@ -79,7 +79,7 @@ namespace dsl { } /** - * @brief Converts the stored list to a vector of the given type. + * Converts the stored list to a vector of the given type. * * @tparam Output The type of the output vector. * @@ -98,7 +98,7 @@ namespace dsl { } /** - * @brief Bool operator to allow the reaction to decide not to run if there is no data. + * Bool operator to allow the reaction to decide not to run if there is no data. * * @return true If the list is not empty. * @return false If the list is empty. @@ -112,45 +112,44 @@ namespace dsl { }; /** - * @brief - * This instructs the powerplant to store the last n messages (of the associated type) to the cache and - * provide read-only access to the subscribing reaction. + * This instructs the Reactor to store the last n messages to a cache and provide read-only access to the + * subscribing reaction. * - * @details - * @code on>>() @endcode - * During system runtime, the PowerPlant will keep a record of the last [0-n] messages which were provided to - * the subscribing reaction. This list is ordered such that the oldest element is first, and the newest - * element is last. Once n messages are stored, the trigger of a new reaction task will cause the - * newest copy to be appended to the list, and the oldest copy to be dropped. * - * This word is a modifier, and should be used to modify any "Get" DSL word. + * @code on>>() @endcode + * During system runtime, the PowerPlant will keep a record of the last [0-n] messages which were provided to + * the subscribing reaction. + * This list is ordered such that the oldest element is first, and the newest element is last. + * Once n messages are stored, the trigger of a new reaction task will cause the newest copy to be appended to + * the list, and the oldest copy to be dropped. + * + * This word is a modifier, and should be used to modify any "Get" DSL word. * * @par Multiple Statements * @code on, With>() @endcode - * When applying this modifier to multiple get statements, a list will be returned for each statement. In - * this example, a list of up to n references for T1 and another list of up to n references for T2 will be + * When applying this modifier to multiple get statements, a list will be returned for each statement. + * In this example, a list of up to n references for T1 and another list of up to n references for T2 will be * provided to the subscribing reaction. * * @par Get Statements * @code on, With>() @endcode * When applied to a request containing a pure "Get" statement (such as the With statement), the data in the - * associated list will reference that which was available whenever the reaction was triggered. That is, the - * list for T2 may not represent the last n emissions of the data, but rather, only the data which was - * available at the time of generating the last n tasks. + * associated list will reference that which was available whenever the reaction was triggered. + * That is, the list for T2 may not represent the last n emissions of the data, but rather, only the data which + * was available at the time of generating the last n tasks. * * @par IO Keywords * @code on>>() @endcode * When working with a DSL word that returns more than one item (such as the I/O Keywords), a list for each - * item will be returned. In the example above, a list of up to n references for port addresses, and another - * list of up to n references for T will be returned. + * item will be returned. + * In the example above, a list of up to n references for port addresses, and another list of up to n + * references for T will be returned. * * @par Implements * Modification * - * @tparam n - * the number of records to be stored in the cache. - * @tparam DSLWords - * the DSL word/activity being modified. + * @tparam n The number of records to be stored in the cache. + * @tparam DSLWords The DSL word/activity being modified. */ template struct Last : public Fusion { @@ -164,11 +163,12 @@ namespace dsl { public: template - static inline auto get(threading::Reaction& reaction) -> decltype(wrap( - Fusion::template get(reaction), - util::GenerateSequence< - 0, - std::tuple_size::template get(reaction))>::value>())) { + static inline auto get(threading::Reaction& reaction) + -> decltype(wrap( + Fusion::template get(reaction), + util::GenerateSequence< + 0, + std::tuple_size::template get(reaction))>::value>())) { // Wrap all of our data in last list wrappers return wrap(Fusion::template get(reaction), diff --git a/src/dsl/word/MainThread.hpp b/src/dsl/word/MainThread.hpp index de4830f71..53a102912 100644 --- a/src/dsl/word/MainThread.hpp +++ b/src/dsl/word/MainThread.hpp @@ -31,12 +31,11 @@ namespace dsl { namespace word { /** - * @brief - * This is used to specify that the associated task will need to execute using the main thread. + * This is used to specify that the associated task will need to execute using the main thread. * - * @details - * @code on, MainThread>() @endcode - * This will most likely be used with graphics related tasks. + * @code on, MainThread>() @endcode + * This can be used with graphics related tasks. + * For example, OpenGL requires all calls to be made from the main thread. */ struct MainThread { diff --git a/src/dsl/word/Network.hpp b/src/dsl/word/Network.hpp index e1377b015..fba46da02 100644 --- a/src/dsl/word/Network.hpp +++ b/src/dsl/word/Network.hpp @@ -52,27 +52,23 @@ namespace dsl { }; /** - * @brief - * NUClear provides a networking protocol to send messages to other devices on the network. + * NUClear provides a networking protocol to send messages to other devices on the network. * - * @details - * @code on>() @endcode - * This request can be used to make a multi-processed NUClear instance, or communicate with other programs - * running NUClear. Note that the serialization and deserialization is handled by NUClear. + * @code on>() @endcode + * This request can be used to communicate with other programs running NUClear. + * Note that the serialization and deserialization is handled by NUClear. * - * When the reaction is triggered, read-only access to T will be provided to the triggering unit via a - * callback. + * When the reaction is triggered, read-only access to T will be provided to the triggering unit via a callback. * * @attention * When using an on> request, the associated reaction will only be triggered when T is emitted to - * the system using the emission Scope::NETWORK. Should T be emitted to the system under any other scope, this - * reaction will not be triggered. + * the system using the emission Scope::NETWORK. + * Should T be emitted to the system under any other scope, this reaction will not be triggered. * * @par Implements * Bind, Get * - * @tparam T - * the datatype on which the reaction callback will be triggered. + * @tparam T The datatype on which the reaction callback will be triggered. */ template struct Network { diff --git a/src/dsl/word/Once.hpp b/src/dsl/word/Once.hpp index c0f3fcec9..043f3ebac 100644 --- a/src/dsl/word/Once.hpp +++ b/src/dsl/word/Once.hpp @@ -31,14 +31,11 @@ namespace dsl { namespace word { /** - * @brief - * This is used to specify reactions which should occur only 1 time. - * - * @details - * @code on() @endcode - * Any reactions listed with this DSL word will run only once. This is the only time these reactions - * will run as the postcondition Unbinds the current reaction, after processing. + * This is used to specify reactions which should occur only 1 time. * + * @code on() @endcode + * Any reactions listed with this DSL word will run only once. + * This is the only time these reactions will run as the postcondition Unbinds the current reaction. */ struct Once : public Single { diff --git a/src/dsl/word/Optional.hpp b/src/dsl/word/Optional.hpp index 8831b6457..a2b785f18 100644 --- a/src/dsl/word/Optional.hpp +++ b/src/dsl/word/Optional.hpp @@ -45,24 +45,21 @@ namespace dsl { }; /** - * @brief - * This is used to signify any optional properties in the DSL request. + * This is used to signify any optional properties in the DSL request. * - * @details - * @code on, Optional() @endcode - * During system runtime, optional data does not need to be present when initialising a reaction within the - * system. In the case above, when T1 is emitted to the system, the associated task will be queued for - * execution. Should T2 be available, read-only access to the most recent emission of T2 will be provided to - * the subscribing reaction. However, should T2 not be present, the task will run without a reference to - * this data. + * @code on, Optional() @endcode + * During system runtime, optional data does not need to be present when initialising a reaction system. + * In the case above, when T1 is emitted to the system, the associated task will be queued for execution. + * Should T2 be available, read-only access to the most recent emission of T2 will be provided to the + * subscribing reaction. + * However, should T2 not be present, the task will run without a reference to this data. * - * This word is a modifier, and should be used to modify any "Get" DSL word. + * This word is a modifier, and should be used to modify any "Get" DSL word. * *@par Implements * Modification * - * @tparam DSLWords - * the DSL word/activity being modified. + * @tparam DSLWords The DSL word/activity being modified. */ template struct Optional : public Fusion { @@ -76,11 +73,12 @@ namespace dsl { public: template - static inline auto get(threading::Reaction& reaction) -> decltype(wrap( - Fusion::template get(reaction), - util::GenerateSequence< - 0, - std::tuple_size::template get(reaction))>::value>())) { + static inline auto get(threading::Reaction& reaction) + -> decltype(wrap( + Fusion::template get(reaction), + util::GenerateSequence< + 0, + std::tuple_size::template get(reaction))>::value>())) { // Wrap all of our data in optional wrappers return wrap(Fusion::template get(reaction), diff --git a/src/dsl/word/Pool.hpp b/src/dsl/word/Pool.hpp index 7f7844807..05069e541 100644 --- a/src/dsl/word/Pool.hpp +++ b/src/dsl/word/Pool.hpp @@ -35,19 +35,17 @@ namespace dsl { namespace word { /** - * @brief - * This is used to specify that this reaction should run in the designated thread pool + * This is used to specify that this reaction should run in the designated thread pool * - * @details - * @code on, Pool>() @endcode - * This DSL will cause the creation of a new thread pool with a specific number of threads allocated to it. + * @code on, Pool>() @endcode + * This DSL will cause the creation of a new thread pool with a specific number of threads allocated to it. * - * All tasks for this reaction will be queued to run on threads from this thread pool. + * All tasks for this reaction will be queued to run on threads from this thread pool. * - * Tasks in the queue are ordered based on their priority level, then their task id. + * Tasks in the queue are ordered based on their priority level, then their task id. * - * When this DSL is not specified the default thread pool will be used. For tasks that need to run on the main - * thread use MainThread. + * When this DSL is not specified the default thread pool will be used. + * For tasks that need to run on the main thread use MainThread. * * @attention * This DSL should be used sparingly as having an increased number of threads running concurrently on the @@ -56,9 +54,9 @@ namespace dsl { * @par Implements * pool * - * @tparam PoolType - * A struct that contains the details of the thread pool to create. This struct should contain a static int - * member that sets the number of threads that should be allocated to this pool. + * @tparam PoolType A struct that contains the details of the thread pool to create. + * This struct should contain a static int member that sets the number of threads that should + * be allocated to this pool. * @code * struct ThreadPool { * static constexpr int thread_count = 2; @@ -70,11 +68,11 @@ namespace dsl { static_assert(PoolType::thread_count > 0, "Can not have a thread pool with less than 1 thread"); - /// @brief the description of the thread pool to be used for this PoolType + /// The description of the thread pool to be used for this PoolType static const util::ThreadPoolDescriptor pool_descriptor; /** - * @brief Sets which thread pool to use for any tasks initiated from this reaction + * Sets which thread pool to use for any tasks initiated from this reaction. * * @tparam DSL the DSL used for this reaction */ diff --git a/src/dsl/word/Priority.hpp b/src/dsl/word/Priority.hpp index d30f93340..dc8eb91f9 100644 --- a/src/dsl/word/Priority.hpp +++ b/src/dsl/word/Priority.hpp @@ -30,29 +30,31 @@ namespace dsl { namespace word { /** - * @brief - * Task priority can be controlled using an assigned setting. + * Task priority can be controlled using an assigned setting. * - * @details - * @code on, Priority::HIGH>() @endcode - * The PowerPlant uses this setting to determine the scheduling order (for the associated task) in the - * threadpool, as well as assign a priority to the thread. + * @code on, Priority::HIGH>() @endcode + * The PowerPlant uses this setting to determine the scheduling order in the threadpool, as well as assign a + * priority to the thread on the OS. * - * The available priority settings are: + * The available priority settings are: * - * REALTIME: Tasks assigned with this will be queued with all other REALTIME tasks. + * REALTIME: Tasks assigned with this will be queued with all other REALTIME tasks. * - * HIGH: Tasks assigned with this will be queued with all other HIGH tasks. They will be scheduled for - * execution when there are no REALTIME tasks in the queue. + * HIGH: + * Tasks assigned with this will be queued with all other HIGH tasks. + * They will be scheduled for execution when there are no REALTIME tasks in the queue. * - * NORMAL: Tasks assigned with this will be queued with all other NORMAL tasks. They will be scheduled - * for execution when there are no REALTIME and HIGH tasks in the queue. + * NORMAL: + * Tasks assigned with this will be queued with all other NORMAL tasks. + * They will be scheduled for execution when there are no REALTIME and HIGH tasks in the queue. * - * LOW: Tasks assigned with this will be queued with all other LOW tasks. They will be scheduled for - * execution when there are no REALTIME, HIGH and NORMAL tasks in the queue. + * LOW: + * Tasks assigned with this will be queued with all other LOW tasks. + * They will be scheduled for execution when there are no REALTIME, HIGH and NORMAL tasks in the queue. * - * IDLE: Tasks assigned with this priority will be queued with all other IDLE tasks. They will be - * scheduled for execution when there are no other tasks running in the system. + * IDLE: + * Tasks assigned with this priority will be queued with all other IDLE tasks. + * They will be scheduled for execution when there are no other tasks running in the system. * * @par Default Behaviour * @code on>() @endcode diff --git a/src/dsl/word/Shutdown.hpp b/src/dsl/word/Shutdown.hpp index 1b0191eb8..3893edc53 100644 --- a/src/dsl/word/Shutdown.hpp +++ b/src/dsl/word/Shutdown.hpp @@ -30,21 +30,20 @@ namespace dsl { namespace word { /** - * @brief - * This is used to specify any reactions/tasks which should occur during shutdown. + * This is used to specify any reactions/tasks which should occur during shutdown. * - * @details - * @code on() @endcode - * Once the shutdown command has been emitted to the PowerPlant, all existing tasks within the system will - * complete their processing as per their current place in the queue. + * @code on() @endcode + * Once the shutdown command has been emitted to the PowerPlant, all existing tasks within the system will + * complete their processing as per their current place in the queue. * - * Any reactions listed with this keyword will then be queued and processed. Tasks in this queue are ordered - * based on their priority level, then their emission timestamp. + * Any reactions listed with this keyword will then be queued and processed. + * Tasks in this queue are ordered based on their priority level, then their emission timestamp. * - * After the shutdown event is triggered, any other reactions/events which would normally occur based on - * system emissions will not be processed. That is, all tasks baring the shutdown tasks will be ignored. + * After the shutdown event is triggered, any other reactions/events which would normally occur based on + * system emissions will not be processed. + * That is, all tasks baring the shutdown tasks will be ignored. * - * Once all Shutdown tasks have finished processing, the system will terminate. + * Once all Shutdown tasks have finished processing, the system will terminate. * * @attention * An on() request simply specifies a reaction/task which should run during the system shutdown diff --git a/src/dsl/word/Single.hpp b/src/dsl/word/Single.hpp index afaf5411c..089ae3ff9 100644 --- a/src/dsl/word/Single.hpp +++ b/src/dsl/word/Single.hpp @@ -30,13 +30,11 @@ namespace dsl { namespace word { /** - * @brief - * This is used to specify that only one instance of the associated reaction can execute during runtime. + * This is used to specify that only one instance of the associated reaction can execute during runtime. * - * @details - * @code on, Single>() @endcode - * When this keyword is used, if the subscribing reaction is triggered while an existing task for this reaction - * is either in the queue or still executing, then the new task request will be ignored/dropped. + * @code on, Single>() @endcode + * When this keyword is used, if the subscribing reaction is triggered while an existing task for this reaction + * is either in the queue or still executing, then the new task request will be ignored/dropped. * * @par Implements * Precondition diff --git a/src/dsl/word/Startup.hpp b/src/dsl/word/Startup.hpp index d1cfc2cf3..bef76039e 100644 --- a/src/dsl/word/Startup.hpp +++ b/src/dsl/word/Startup.hpp @@ -30,17 +30,11 @@ namespace dsl { namespace word { /** - * @brief - * This is used to specify reactions which should occur at startup. + * This is used to specify reactions which should occur at startup. * - * @details - * @code on() @endcode - * Any reactions listed with this DSL word will run directly after all reactors have been installed into the - * PowerPlant but before the system starts the main execution phase. This is the only time these reactions - * will run. - * - * Note that this request is generally used by reactor's which require information provided by another - * reactor's constructor. + * @code on() @endcode + * Any reactions listed with this DSL word will run directly after when start is called on the PowerPlant. + * However it will execute before the system starts the main execution phase. * * @par Implements * Bind diff --git a/src/dsl/word/Sync.hpp b/src/dsl/word/Sync.hpp index 8c74e018a..d7d1fe84d 100644 --- a/src/dsl/word/Sync.hpp +++ b/src/dsl/word/Sync.hpp @@ -36,36 +36,38 @@ namespace dsl { namespace word { /** - * @brief - * This is used to specify that only one reaction in this SyncGroup can run concurrently. + * This is used to specify that only one reaction in this SyncGroup can run concurrently. * - * @details - * @code on, Sync>() @endcode - * When a group of tasks has been synchronised, only one task from the group will execute at a given time. * - * Should another task from this group be scheduled/requested (during execution of the current task), it will - * be sidelined into the task queue. + * @code on, Sync>() @endcode + * When a group of tasks has been synchronised, only one task from the group will execute at a given time. * - * Tasks in the queue are ordered based on their priority level, then their task id. + * Should another task from this group be scheduled/requested (during execution of the current task), it will + * be sidelined into the task queue. + * + * Tasks in the queue are ordered based on their priority level, then their task id. * * @par When should I use Sync - * Consider a reactor with a number of a reactions which modify its state. It would be unwise to allow the - * reactions to run concurrently. To avoid race conditions, it is recommended that any reactions which modify - * the state be synced. + * Consider a reactor with a number of a reactions which modify its state. + * It would be unwise to allow the reactions to run concurrently. + * To avoid race conditions, it is recommended that any reactions which modify the state be synced. * * @attention - * When using NUClear, developers should not make use of devices like a mutex. In the case of a mutex, threads - * will run and then block (leading to wasted resources on a number of inactive threads). By using Sync, - * NUClear will have task and thread control so that system resources can be efficiently managed. + * When using NUClear, developers should avoid using blocking features such as mutexes. + * In the case of a mutex, threads will run and then block. + * As they are using a thread pool, this can lead to wasted resources by the of inactive threads. + * By using Sync, NUClear will have task and thread control so that system resources can be efficiently managed. * * @par Implements * Group * - * @tparam SyncGroup - * the type/group to synchronize on. This needs to be a declared type within the system. It is common to - * simply use the reactors name (i.e; if the reactor is only syncing with one group). Should more than one - * group be required, the developer can declare structs within the system, to act as a group reference. - * Note that the developer is not limited to the use of a struct; any declared type will work. + * @tparam GroupType The type/group to synchronize on. + * This needs to be a declared type within the system. + * It is common to simply use the reactors name for a reactor with one group. + * Should more than one group be required, the developer can declare structs within the + * system, to act as a group reference. + * Note that the developer is not limited to the use of a struct; any declared type + * will work. */ template struct Sync : Group {}; diff --git a/src/dsl/word/TCP.hpp b/src/dsl/word/TCP.hpp index 7d01fcaa9..c2926032a 100644 --- a/src/dsl/word/TCP.hpp +++ b/src/dsl/word/TCP.hpp @@ -38,25 +38,24 @@ namespace dsl { namespace word { /** - * @brief - * This allows a reaction to be triggered based on TCP activity. + * This allows a reaction to be triggered based on TCP activity. * - * @details - * @code on(port) @endcode - * When a connection is identified on the assigned port, the associated reaction will be triggered. The - * request for a TCP based reaction can use a runtime argument to reference a specific port. Note that the - * port reference can be changed during the systems execution phase. + * @code on(port) @endcode + * When a connection is identified on the assigned port, the associated reaction will be triggered. + * The request for a TCP based reaction can use a runtime argument to reference a specific port. + * Note that the port reference can be changed during the systems execution phase. * - * @code on() @endcode - * Should the port reference be omitted, then the system will bind to a currently unassigned port. + * @code on() @endcode + * Should the port reference be omitted, then the system will bind to a currently unassigned port. * - * @code on(port, port) @endcode - * A reaction can also be triggered via connectivity on more than one port. + * @code on(port, port) @endcode + * A reaction can also be triggered via connectivity on more than one port. * * @attention - * Because TCP communications are stream based, the on< TCP >() request will often require an on< IO >() - * request also be specified within its definition. It is the later request which will define the reaction to - * run when activity on the stream is detected. For example: + * Because TCP communications are stream based, the on() request will often require an on() + * request also be specified within its definition. + * It is the later request which will define the reaction to run when activity on the stream is detected. + * For example: * @code on(port).then([this](const TCP::Connection& connection){ * on(connection.fd, IO::READ | IO::CLOSE).then([this](IO::Event event) * } @endcode @@ -69,22 +68,22 @@ namespace dsl { struct Connection { struct Target { - /// @brief The address of the connection + /// The address of the connection std::string address; - /// @brief The port of the connection + /// The port of the connection uint16_t port; }; - /// @brief The local address of the connection + /// The local address of the connection Target local; - /// @brief The remote address of the connection + /// The remote address of the connection Target remote; - /// @brief The file descriptor for the connection + /// The file descriptor for the connection fd_t fd; /** - * @brief Casts this packet to a boolean to check if it is valid + * Casts this packet to a boolean to check if it is valid * * @return true if the packet is valid */ diff --git a/src/dsl/word/Trigger.hpp b/src/dsl/word/Trigger.hpp index 8916478c9..17cd01c15 100644 --- a/src/dsl/word/Trigger.hpp +++ b/src/dsl/word/Trigger.hpp @@ -32,25 +32,22 @@ namespace dsl { namespace word { /** - * @brief - * This is used to request any data dependent reactions in the system. + * This is used to request any data dependent reactions in the system. * - * @details - * @code on>() @endcode - * This will enact the execution of a task whenever T is emitted into the system. When this occurs, read-only - * access to T will be provided to the triggering unit via a callback. + * @code on>() @endcode + * This will enact the execution of a task whenever T is emitted into the system. + * When this occurs, read-only access to T will be provided to the triggering unit via a callback. * - * @code on>() @endcode - * Note that a this request can handle triggers on multiple types. When using multiple types in the request, - * the reaction will only be triggered once all of the trigger types have been emitted (at least once) - * since the last occurrence of the event. + * @code on>() @endcode + * Note that a this request can handle triggers on multiple types. + * When using multiple types in the request the reaction will only be triggered once all of the trigger + * types have been emitted (at least once) since the last occurrence of the event. * * @par Implements * Bind, Get * - * @tparam Ts - * The datatype on which a reaction callback will be triggered. Emission of this datatype into the system - * will trigger the subscribing reaction. + * @tparam Ts The datatype on which a reaction callback will be triggered. + * Emission of this datatype into the system will trigger the subscribing reaction. */ template struct Trigger : public Fusion..., operation::CacheGet...> {}; diff --git a/src/dsl/word/UDP.hpp b/src/dsl/word/UDP.hpp index 2eb36a70f..9cec17e70 100644 --- a/src/dsl/word/UDP.hpp +++ b/src/dsl/word/UDP.hpp @@ -40,28 +40,26 @@ namespace dsl { namespace word { /** - * @brief - * This allows a reaction to be triggered based on UDP activity originating from external sources, or UDP - * emissions within the system. + * This allows a reaction to be triggered based on UDP activity originating from external sources, or UDP + * emissions within the system. * - * @details - * @code on(port) @endcode - * When a connection is identified on the assigned port, the associated reaction will be triggered. The - * request for a UDP based reaction can use a runtime argument to reference a specific port. Note that the - * port reference can be changed during the systems execution phase. + * @code on(port) @endcode + * When a connection is identified on the assigned port, the associated reaction will be triggered. + * The request for a UDP based reaction can use a runtime argument to reference a specific port. + * Note that the port reference cannot be changed during the systems execution phase. * * @code on(port, bind_address) @endcode - * The `bind_address` parameter can be used to specify which interface to bind on. If `bind_address` is an - * empty string, the system will bind to any available interface. + * The `bind_address` parameter can be used to specify which interface to bind on. + * If `bind_address` is an empty string, the system will bind to any available interface. * - * @code on() @endcode - * Should the port reference be omitted, then the system will bind to a currently unassigned port. + * @code on() @endcode + * Should the port reference be omitted, then the system will bind to a currently unassigned port. * - * @code on(port) - * on(multicast_address, port) @endcode - * If needed, this trigger can also listen for UDP activity such as broadcast and multicast. + * @code on(port) + * on(multicast_address, port) @endcode + * If needed, this trigger can also listen for UDP activity such as broadcast and multicast. * - * These requests support both IPv4 and IPv6 addressing. + * These requests support both IPv4 and IPv6 addressing. * * @par Implements * Bind @@ -69,32 +67,32 @@ namespace dsl { struct UDP : public IO { private: /** - * @brief This structure is used to configure the UDP connection + * This structure is used to configure the UDP connection */ struct ConnectOptions { - /// @brief The type of connection we are making + /// The type of connection we are making enum class Type { UNICAST, BROADCAST, MULTICAST }; - /// @brief The type of connection we are making + /// The type of connection we are making Type type{}; - /// @brief The address we are binding to or empty for any + /// The address we are binding to or empty for any std::string bind_address{}; - /// @brief The port we are binding to or 0 for any + /// The port we are binding to or 0 for any in_port_t port = 0; - /// @brief The multicast address we are listening on or empty for any + /// The multicast address we are listening on or empty for any std::string target_address{}; }; /** - * @brief This structure is used to return the result of a recvmsg call + * This structure is used to return the result of a recvmsg call */ struct RecvResult { - /// @brief If the packet is valid + /// If the packet is valid bool valid{false}; - /// @brief The data that was received + /// The data that was received std::vector payload{}; - /// @brief The local address that the packet was received on + /// The local address that the packet was received on util::network::sock_t local{}; - /// @brief The remote address that the packet was received from + /// The remote address that the packet was received from util::network::sock_t remote{}; }; @@ -102,29 +100,29 @@ namespace dsl { struct Packet { Packet() = default; - /// @brief If the packet is valid (it contains data) + /// If the packet is valid (it contains data) bool valid{false}; struct Target { Target() = default; Target(std::string address, const uint16_t& port) : address(std::move(address)), port(port) {} - /// @brief The address of the target + /// The address of the target std::string address{}; - /// @brief The port of the target + /// The port of the target uint16_t port{0}; }; - /// @brief The information about this packets destination + /// The information about this packets destination Target local; - /// @brief The information about this packets source + /// The information about this packets source Target remote; - /// @brief The data to be sent in the packet + /// The data to be sent in the packet std::vector payload{}; /** - * @brief Casts this packet to a boolean to check if it is valid + * Casts this packet to a boolean to check if it is valid * * @return true if the packet is valid */ diff --git a/src/dsl/word/Watchdog.hpp b/src/dsl/word/Watchdog.hpp index 0987018e0..89420d86d 100644 --- a/src/dsl/word/Watchdog.hpp +++ b/src/dsl/word/Watchdog.hpp @@ -36,16 +36,15 @@ namespace dsl { namespace word { /** - * @brief - * Handles the data store for the case when runtime arguments specified - * @code on>(data) @endcode - * @code emit(data) @endcode + * Handles the data store for the case when runtime arguments specified. * - * @tparam WatchdogGroup - * the type/group of tasks the watchdog will track. This needs to be a declared type within the system - * (be it a reactor, reaction, or other type). - * @tparam RuntimeType - * the type of the runtime argument. const/volatile specifiers are stripped from this type + * @code on>(data) @endcode + * @code emit(data) @endcode + * + * @tparam WatchdogGroup The type/group of tasks the watchdog will track. + * This needs to be a declared type within the system. + * @tparam RuntimeType The type of the runtime argument. + * const/volatile specifiers are stripped from this type. */ template struct WatchdogDataStore { @@ -53,7 +52,7 @@ namespace dsl { using WatchdogStore = util::TypeMap>; /** - * @brief Ensures the data store is initialised correctly + * Ensures the data store is initialised correctly. * * @param data The runtime argument for the current watchdog in the WatchdogGroup/RuntimeType group */ @@ -67,7 +66,7 @@ namespace dsl { } /** - * @brief Gets the current service time for the WatchdogGroup/RuntimeType/data watchdog + * Gets the current service time for the WatchdogGroup/RuntimeType/data watchdog * * @param data The runtime argument for the current watchdog in the WatchdogGroup/RuntimeType group */ @@ -81,7 +80,7 @@ namespace dsl { } /** - * @brief Cleans up any allocated storage for the WatchdogGroup/RuntimeType/data watchdog + * Cleans up any allocated storage for the WatchdogGroup/RuntimeType/data watchdog * * @param data The runtime argument for the current watchdog in the WatchdogGroup/RuntimeType group */ @@ -93,21 +92,20 @@ namespace dsl { }; /** - * @brief - * Handles the data store for the case when no runtime arguments are specified - * @code on>() @endcode - * @code emit() @endcode + * Handles the data store for the case when no runtime arguments are specified. + * + * @code on>() @endcode + * @code emit() @endcode * - * @tparam WatchdogGroup - * the type/group of tasks the watchdog will track. This needs to be a declared type within the system - * (be it a reactor, reaction, or other type). + * @tparam WatchdogGroup The type/group of tasks the watchdog will track. + * This needs to be a declared type within the system. */ template struct WatchdogDataStore { using WatchdogStore = util::TypeMap; /** - * @brief Ensures the data store is initialised correctly + * Ensures the data store is initialised correctly. */ static void init() { if (WatchdogStore::get() == nullptr) { @@ -116,7 +114,7 @@ namespace dsl { } /** - * @brief Gets the current service time for the WatchdogGroup watchdog + * Gets the current service time for the WatchdogGroup watchdog. */ static const NUClear::clock::time_point& get() { if (WatchdogStore::get() == nullptr) { @@ -127,7 +125,7 @@ namespace dsl { } /** - * @brief Cleans up any allocated storage for the WatchdogGroup watchdog + * Cleans up any allocated storage for the WatchdogGroup watchdog. */ static void unbind() { if (WatchdogStore::get() != nullptr) { @@ -137,17 +135,15 @@ namespace dsl { }; /** - * @brief - * This can be used to monitor task(s); if the monitored task(s) have not occurred within a desired timeframe, + * This can be used to monitor task(s); if the monitored task(s) have not occurred within a desired timeframe, * the watchdog can be serviced to trigger a specified reaction. * - * @details - * @code on>() @endcode - * This is a useful tool for anything in the system which might stall, and needs to be kick-started. + * @code on>() @endcode + * This is a useful tool for anything in the system which might stall, and needs to be kick-started. * - * The watchdog can monitor a single task, or group of tasks, over a period of time. If no activity is - * detected after the specified timeframe, the watchdog will be serviced. When the watchdog is serviced, the - * timer resets. + * The watchdog can monitor a single task, or group of tasks, over a period of time. If no activity is + * detected after the specified timeframe, the watchdog will be serviced. + * When the watchdog is serviced, the timer resets. * * @par Single Reaction * @code on>() @endcode @@ -166,7 +162,7 @@ namespace dsl { * the SampleReactor group has not occurred for 10 milliseconds, the watchdog for that instance of data will * be serviced. * - * @par Service the Watcdog + * @par Service the Watchdog * @code emit(ServiceWatchdog()) @endcode * The watchdog will need to be serviced by a watchdog service emission. The emission must use the same * template type as the watchdog. Each time this emission occurs, the watchdog timer will be reset. @@ -183,27 +179,26 @@ namespace dsl { * @par Implements * Bind * - * @tparam WatchdogGroup - * the type/group of tasks the watchdog will track. This needs to be a declared type within the system (be it - * a reactor, reaction, or other type). - * @tparam ticks - * the number of ticks of a particular type to wait - * @tparam period - * a type of duration (e.g. std::chrono::seconds) to measure the ticks in. This will default to clock - * duration, but can accept any of the defined std::chrono durations (nanoseconds, microseconds, milliseconds, - * seconds, minutes, hours). Note that you can also define your own unit: See - * http://en.cppreference.com/w/cpp/chrono/duration + * @tparam WatchdogGroup The type/group of tasks the watchdog will track. + * This needs to be a declared type within the system. + * + * @tparam ticks The number of ticks of a particular type to wait + * @tparam period A type of duration (e.g. std::chrono::seconds) to measure the ticks in. + * This will default to clock duration, but can accept any of the defined std::chrono durations. + * i.e. nanoseconds, microseconds, milliseconds, seconds, minutes, hours. + * Note that you can also define your own unit. + * See http://en.cppreference.com/w/cpp/chrono/duration */ template struct Watchdog { /** - * @brief Binder for Watchdog reactions with a runtime argument + * Binder for Watchdog reactions with a runtime argument. * * @tparam DSL * - * @tparam RuntimeType - * the type of the runtime argument. const/volatile specifiers are stripped from this type + * @tparam RuntimeType The type of the runtime argument. + * const/volatile specifiers are stripped from this type. * @param reaction the reaction object that we are binding * @param data the runtime argument for the current watchdog in the WatchdogGroup/RuntimeType group */ @@ -232,7 +227,7 @@ namespace dsl { } /** - * @brief Binder for Watchdog reactions with no runtime argument + * Binder for Watchdog reactions with no runtime argument. */ template static inline void bind(const std::shared_ptr& reaction) { @@ -258,13 +253,13 @@ namespace dsl { private: /** - * @brief updates the service time for the current reaction + * updates the service time for the current reaction. + * + * @param reaction The reaction we are servicing + * @param service_time The last service time of the watchdog + * @param time The time when this watchdog should be checked next * - * @param reaction the reaction we are servicing - * @param service_time the last service time of the watchdog - * @param time the time when this watchdog should be checked next - * @return true the chrono task should run again - * @return false the chrono task should not run again + * @return `true` if the chrono task should run again */ static bool chrono_task(const std::shared_ptr& reaction, const NUClear::clock::time_point& service_time, diff --git a/src/dsl/word/With.hpp b/src/dsl/word/With.hpp index e83681120..bf7aa983f 100644 --- a/src/dsl/word/With.hpp +++ b/src/dsl/word/With.hpp @@ -31,29 +31,30 @@ namespace dsl { namespace word { /** - * @brief - * This is used to define any extra data which should be provided to a subscribing a reaction. + * This is used to define any extra data which should be provided to a subscribing a reaction. * - * @details - * @code on>() @endcode - * Note that during runtime, the emission of data using this word will not trigger a reaction within the - * system. For best use, this word should be fused with at least one other binding DSL word. * - * @code on, With>() @endcode - * In the example above, when T2 is emitted into the system, it will not trigger a callback to the - * triggering reaction. Yet when T1 is emitted into the system, read-only access to the most recent copy of - * both T1 and T2 will be provided via a callback to the reaction. + * @code on>() @endcode + * Note that during runtime, the emission of data using this word will not trigger a reaction within the + * system. + * This word must be fused with at least one other binding DSL word. * - * If a copy of T2 is not present when T1 is emitted into the system, the task will be dropped (i.e the - * reaction will not run). To override this functionality, include the DSL keyword "Optional" in the request. - * For example: - * @code on, Optional>>() @endcode + * @code on, With>() @endcode + * In the example above, when T2 is emitted into the system, it will not trigger a callback to the + * triggering reaction. + * Yet when T1 is emitted into the system, read-only access to the most recent copy of both T1 and T2 will be + * provided via a callback to the reaction. + * + * If a copy of T2 is not present when T1 is emitted into the system, the task will be dropped (i.e the + * reaction will not run). + * To override this functionality, include the DSL keyword "Optional" in the request. + * For example: + * @code on, Optional>>() @endcode * * @par Implements * Get * - * @tparam T - * the datatype/s which will be provided to a subscribing reaction when the reaction is triggered. + * @tparam T The datatype/s which will be provided to a subscribing reaction when the reaction is triggered. */ template struct With : public Fusion...> {}; diff --git a/src/dsl/word/emit/Delay.hpp b/src/dsl/word/emit/Delay.hpp index e683910e2..72aa53d56 100644 --- a/src/dsl/word/emit/Delay.hpp +++ b/src/dsl/word/emit/Delay.hpp @@ -32,24 +32,18 @@ namespace dsl { namespace emit { /** - * @brief - * This will emit data, after the provided delay. + * This will emit data, after the provided delay. * - * @details - * @code emit(data, delay(ticks), dataType); @endcode - * Emissions under this scope will wait for the provided time delay, and then emit the object utilising a - * local emit (that is, normal thread pool distribution). * - * @param data - * the data to emit - * @param delay(ticks) - * the time to wait before emitting this object. Use delay to specify the unit in which to measure the - * ticks, this will default to clock duration, but can accept any of the defined std::chrono durations - * (nanoseconds, microseconds, milliseconds, seconds, minutes, hours). Note that you can also define your - * own unit: See http://en.cppreference.com/w/cpp/chrono/duration. Use an int to specify the number of - * ticks to wait. - * @tparam DataType - * the datatype of the object to emit + * @code emit(data, delay(ticks), dataType); @endcode + * Emissions under this scope will wait for the provided time delay, and then emit the object utilising a + * local emit (that is, normal thread pool distribution). + * + * + * @tparam DataType The datatype of the object to emit + * + * @param data The data to emit + * @param delay The time to wait before emitting this object. */ template struct Delay { @@ -96,7 +90,7 @@ namespace dsl { }; } // namespace emit - } // namespace word + } // namespace word } // namespace dsl } // namespace NUClear diff --git a/src/dsl/word/emit/Direct.hpp b/src/dsl/word/emit/Direct.hpp index 1adc0f01b..84cbe4a29 100644 --- a/src/dsl/word/emit/Direct.hpp +++ b/src/dsl/word/emit/Direct.hpp @@ -34,24 +34,22 @@ namespace dsl { namespace emit { /** - * @brief - * When emitting data under this scope, the tasks created as a result of this emission will bypass the - * thread pool, and be executed immediately. + * When emitting data under this scope, the tasks created as a result of this emission will bypass the + * thread pool, and be executed immediately. * - * @details - * @code emit(data, dataType); @endcode - * When data is emitted via this scope, the task which is currently executing will be paused. At this time - * any tasks created as a result of this emission are executed one at a time sequentially, using the - * current thread. This type of emission will always run even when the system is in its Shutdown process - * or before the system has started up to the main phase. + * @code emit(data, dataType); @endcode + * When data is emitted via this scope, the task which is currently executing will be paused. + * At this time any tasks created as a result of this emission are executed one at a time sequentially, + * using the current thread. + * This type of emission will always run even when the system is in its Shutdown process or before the + * system has started up to the main phase. * * @attention * This scope is useful for reactors which emit data to themselves. * - * @param data - * the data to emit - * @tparam DataType - * the datatype that is being emitted + * @tparam DataType The datatype that is being emitted + * + * @param data The data to emit */ template struct Direct { @@ -74,7 +72,7 @@ namespace dsl { }; } // namespace emit - } // namespace word + } // namespace word } // namespace dsl } // namespace NUClear diff --git a/src/dsl/word/emit/Initialise.hpp b/src/dsl/word/emit/Initialise.hpp index 844ee0269..a2fbf02c2 100644 --- a/src/dsl/word/emit/Initialise.hpp +++ b/src/dsl/word/emit/Initialise.hpp @@ -31,26 +31,24 @@ namespace dsl { namespace emit { /** - * @brief - * This scope emits data as the system starts up. + * This scope emits data as the system starts up. * - * @details - * @code emit(data, dataType); @endcode - * This should be used to emit any data required during system start up (that is, as the reactor is being - * installed into the powerPlant). When running emissions under this scope, the message will wait until - * all Reactors are installed into the powerPlant before triggering any callbacks based on the emission. + * + * @code emit(data, dataType); @endcode + * This should be used to emit any data required during system start up. + * i.e. as the reactor is being installed into the powerPlant. + * When running emissions under this scope, the message will wait until `.start()` is called on PowerPlant. + * Which should be after all Reactors are installed. * * @attention * Tasks triggered by data emitted under this scope will only execute while the system is in the - * initialisation phase. These tasks are the final activity which occur before the system shifts into the - * execution phase. Any emissions under this scope while the system is in the execution phase will be - * ignored. + * initialisation phase. + * These tasks are the final activity which occur before the system shifts into the execution phase. + * Emitting with this scope while the system is in the execution phase will act as normal emits. * - * @param data - * The data to emit + * @tparam DataType The type of the data to be emitted * - * @tparam DataType - * The type of the data to be emitted + * @param data The data to emit */ template struct Initialise { @@ -68,7 +66,7 @@ namespace dsl { }; } // namespace emit - } // namespace word + } // namespace word } // namespace dsl } // namespace NUClear diff --git a/src/dsl/word/emit/Local.hpp b/src/dsl/word/emit/Local.hpp index 50fc5f18b..aa93d50d9 100644 --- a/src/dsl/word/emit/Local.hpp +++ b/src/dsl/word/emit/Local.hpp @@ -35,20 +35,18 @@ namespace dsl { namespace emit { /** - * @brief - * When emitting data under this scope, tasks are distributed via the thread pool for execution. + *When emitting data under this scope, tasks are distributed via the thread pool for execution. * - * @details - * @code emit(data, dataType); @endcode + * + * @code emit(data, dataType); @endcode * * @attention * Note that this type of emission is the default behaviour when emitting without a specified scope. * @code emit(data, dataType); @endcode * - * @param data - * the data to emit - * @tparam DataType - * the datatype of the object to emit + * @tparam DataType The datatype of the object to emit + * + * @param data The data to emit */ template struct Local { @@ -72,7 +70,7 @@ namespace dsl { }; } // namespace emit - } // namespace word + } // namespace word } // namespace dsl } // namespace NUClear diff --git a/src/dsl/word/emit/Network.hpp b/src/dsl/word/emit/Network.hpp index 458c71bf2..88803df7a 100644 --- a/src/dsl/word/emit/Network.hpp +++ b/src/dsl/word/emit/Network.hpp @@ -45,17 +45,17 @@ namespace dsl { }; /** - * @brief - * Emits data over the network to other NUClear environments. + * Emits data over the network to other NUClear environments. * - * @details - * @code emit(data, target, reliable, dataType); @endcode - * Data emitted under this scope can be sent by name to other NUClear systems or to all NUClear systems - * connected to the NUClear network. When sent the data is serialized; the associated serialization - * and deserialization of the object is handled by NUClear. * - * These messages can be sent using either an unreliable protocol that does not guarantee delivery, or - * using a reliable protocol that does. + * @code emit(data, target, reliable, dataType); @endcode + * Data emitted under this scope can be sent by name to other NUClear systems or to all NUClear systems + * connected to the NUClear network. + * When sent the data is serialized; the associated serialization and deserialization of the object is + * handled by NUClear. + * + * These messages can be sent using either an unreliable protocol that does not guarantee delivery, or + * using a reliable protocol that does. * * @attention * Note that if the target system is not connected to the network, the emit will be ignored even if @@ -63,15 +63,17 @@ namespace dsl { * * @attention * Data sent under this scope will only trigger reactions (create tasks) for any associated network - * requests of this datatype. For example: + * requests of this datatype. + * For example: * @code on> @endcode * Tasks generated by this emission are assigned to the threadpool on the target environment. * + * @tparam DataType the type of the data to send + * * @param data the data to emit * @param target Optional. The name of the system to send to, or empty for all systems. Defaults to all. * (an empty string). * @param reliable Optional. True if the delivery of the message should be guaranteed. Defaults to false. - * @tparam DataType the type of the data to send */ template struct Network { @@ -97,7 +99,7 @@ namespace dsl { }; } // namespace emit - } // namespace word + } // namespace word } // namespace dsl } // namespace NUClear diff --git a/src/dsl/word/emit/UDP.hpp b/src/dsl/word/emit/UDP.hpp index 286bbf878..768e2ceb1 100644 --- a/src/dsl/word/emit/UDP.hpp +++ b/src/dsl/word/emit/UDP.hpp @@ -39,15 +39,13 @@ namespace dsl { namespace emit { /** - * @brief - * Emits data as a UDP packet over the network. + * Emits data as a UDP packet over the network. * - * @details - * @code emit(data, to_addr, to_port); @endcode - * Emissions under this scope are useful for communicating with third parties. The target of the packet - * can be can be a unicast, broadcast or multicast address, specified as either a host endian int, or as a - * string. Additionally the address and port on the local machine can be specified using a string or host - * endian int. + * + * @code emit(data, to_addr, to_port); @endcode + * Emissions under this scope are useful for communicating with other systems using UDP. + * The target of the packet can be can be a unicast, broadcast or multicast address, specified as a string. + * Additionally the address and port on the local machine can be specified using a string and port. * * @attention * Anything emitted over the UDP network must be serialisable. @@ -175,7 +173,7 @@ namespace dsl { }; } // namespace emit - } // namespace word + } // namespace word } // namespace dsl } // namespace NUClear diff --git a/src/dsl/word/emit/Watchdog.hpp b/src/dsl/word/emit/Watchdog.hpp index e94dad020..726c04d60 100644 --- a/src/dsl/word/emit/Watchdog.hpp +++ b/src/dsl/word/emit/Watchdog.hpp @@ -35,16 +35,14 @@ namespace dsl { namespace emit { /** - * @brief - * Handles the data store for the case when runtime arguments specified - * @code on>(data) @endcode - * @code emit(data) @endcode + * Handles the data store for the case when runtime arguments specified. * - * @tparam WatchdogGroup - * the type/group of tasks the watchdog will track. This needs to be a declared type within the system - * (be it a reactor, reaction, or other type). - * @tparam RuntimeType - * the type of the runtime argument. const/volatile specifiers are stripped from this type + * @code on>(data) @endcode + * @code emit(data) @endcode + * + * @tparam WatchdogGroup The type/group of tasks the watchdog will track. + * @tparam RuntimeType The type of the runtime argument. + * const/volatile specifiers are stripped from this type. */ template struct WatchdogServicer { @@ -53,23 +51,22 @@ namespace dsl { util::TypeMap>; /** - * @brief Construct a new Watchdog Servicer object + * Construct a new Watchdog Servicer object */ WatchdogServicer() = default; /** - * @brief Construct a new Watchdog Servicer object + * Construct a new Watchdog Servicer object * * @param data The runtime argument that was passed to on>() */ explicit WatchdogServicer(const RuntimeType& data) : data(data) {} /** - * @brief Services the watchdog + * Services the watchdog * - * @details - * The watchdog timer that is specified by the WatchdogGroup/RuntimeType/data - * combination will have its service time updated to whatever is stored in when + * The watchdog timer that is specified by the WatchdogGroup/RuntimeType/data combination will have its + * service time updated to whatever is stored in when. */ void service() { if (WatchdogStore::get() == nullptr || WatchdogStore::get()->count(data) == 0) { @@ -81,32 +78,27 @@ namespace dsl { } private: - /// @brief The time when the watchdog was serviced + /// The time when the watchdog was serviced NUClear::clock::time_point when{NUClear::clock::now()}; - /// @brief The runtime argument that was passed to on>() + /// The runtime argument that was passed to on>() RuntimeType data{}; }; /** - * @brief - * Handles the data store for the case when no runtime arguments are specified - * @code on>() @endcode - * @code emit() @endcode + * Handles the data store for the case when no runtime arguments are specified + * @code on>() @endcode + * @code emit() @endcode * - * @tparam WatchdogGroup - * the type/group of tasks the watchdog will track. This needs to be a declared type within the system - * (be it a reactor, reaction, or other type). + * @tparam WatchdogGroup The type/group of tasks the watchdog will track. */ template struct WatchdogServicer { using WatchdogStore = util::TypeMap; /** - * @brief * Services the watchdog + * Services the watchdog * - * @details - * The watchdog timer for WatchdogGroup will have its service time updated to whatever is stored in - * when + * The watchdog timer for WatchdogGroup will have its service time updated to whatever is stored in when */ void service() { if (WatchdogStore::get() == nullptr) { @@ -121,17 +113,15 @@ namespace dsl { }; /** - * @brief - * Convenience function to instantiate a WatchdogServicer for a watchdog with a runtime argument + * Convenience function to instantiate a WatchdogServicer for a watchdog with a runtime argument. * - * @tparam WatchdogGroup - * the type/group of tasks the watchdog will track. This needs to be a declared type within the system - * (be it a reactor, reaction, or other type). - * @tparam RuntimeType - * the type of the runtime argument. const/volatile specifiers are stripped from this type - * @param data The runtime argument that was passed to - * @code on>(data) @endcode - * @return WatchdogServicer + * @tparam WatchdogGroup The type/group of tasks the watchdog will track. + * @tparam RuntimeType The type of the runtime argument. + * const/volatile specifiers are stripped from this type. + * + * @param data The runtime argument that was passed to @code on>(data) @endcode + * + * @return A WatchdogServicer object which will update the service time of the specified watchdog */ template WatchdogServicer ServiceWatchdog(RuntimeType&& data) { @@ -139,10 +129,9 @@ namespace dsl { } /** - * @brief Convenience function to instantiate a WatchdogServicer for a watchdog with no runtime argument + * Convenience function to instantiate a WatchdogServicer for a watchdog with no runtime argument. * - * @tparam WatchdogGroup - * the type/group of tasks the watchdog will track. This needs to be a declared type within the system + * @tparam WatchdogGroup The type/group of tasks the watchdog will track. * (be it a reactor, reaction, or other type). * @return WatchdogServicer */ @@ -152,12 +141,12 @@ namespace dsl { } /** - * @brief When emitting data under this scope, the service time for the watchdog is updated + * When emitting data under this scope, the service time for the watchdog is updated. + * - * @details - * @code emit(ServiceWatchdog(data)); @endcode + * @code emit(ServiceWatchdog(data)); @endcode * or - * @code emit(ServiceWatchdog()); @endcode + * @code emit(ServiceWatchdog()); @endcode * * The RuntimeType template parameter need not be specified for ServiceWatchdog as it will be inferred from * the data argument, if it is specified @@ -176,7 +165,7 @@ namespace dsl { }; } // namespace emit - } // namespace word + } // namespace word } // namespace dsl } // namespace NUClear diff --git a/src/extension/ChronoController.hpp b/src/extension/ChronoController.hpp index 28ee8e908..7f643e8b8 100644 --- a/src/extension/ChronoController.hpp +++ b/src/extension/ChronoController.hpp @@ -203,18 +203,18 @@ namespace extension { } private: - /// @brief The list of tasks we need to process + /// The list of tasks we need to process std::vector tasks; - /// @brief The mutex we use to lock the task list + /// The mutex we use to lock the task list std::mutex mutex; - /// @brief The condition variable we use to wait on + /// The condition variable we use to wait on std::condition_variable wait; - /// @brief If we are running or not + /// If we are running or not std::atomic running{true}; - /// @brief The temporal accuracy when waiting on a condition variable + /// The temporal accuracy when waiting on a condition variable NUClear::clock::duration cv_accuracy{0}; - /// @brief The temporal accuracy when waiting on nanosleep + /// The temporal accuracy when waiting on nanosleep NUClear::clock::duration ns_accuracy{0}; }; diff --git a/src/extension/IOController_Posix.hpp b/src/extension/IOController_Posix.hpp index ac41ec444..8361e4290 100644 --- a/src/extension/IOController_Posix.hpp +++ b/src/extension/IOController_Posix.hpp @@ -39,11 +39,11 @@ namespace extension { class IOController : public Reactor { private: - /// @brief The type that poll uses for events + /// The type that poll uses for events using event_t = decltype(pollfd::events); /** - * @brief A task that is waiting for an IO event + * A task that is waiting for an IO event. */ struct Task { Task() = default; @@ -51,28 +51,27 @@ namespace extension { Task(const fd_t& fd, event_t listening_events, std::shared_ptr reaction) : fd(fd), listening_events(listening_events), reaction(std::move(reaction)) {} - /// @brief The file descriptor we are waiting on + /// The file descriptor we are waiting on fd_t fd{-1}; - /// @brief The events that the task is interested in + /// The events that the task is interested in event_t listening_events{0}; - /// @brief The events that are waiting to be fired + /// The events that are waiting to be fired event_t waiting_events{0}; - /// @brief The events that are currently being processed + /// The events that are currently being processed event_t processing_events{0}; - /// @brief The reaction that is waiting for this event + /// The reaction that is waiting for this event std::shared_ptr reaction{nullptr}; /** - * @brief Sorts the tasks by their file descriptor + * Sorts the tasks by their file descriptor. * * The tasks are sorted by file descriptor so that when we rebuild the list of file descriptors to poll we - * can assume that if the same file descriptor shows up multiple times it will be next to each other. This - * allows the events that are being watched to be or'ed together. + * can assume that if the same file descriptor shows up multiple times it will be next to each other. + * This allows the events that are being watched to be or'ed together. * * @param other the other task to compare to * - * @return true if this task is less than the other - * @return false if this task is greater than or equal to the other + * @return `true` if this task is less than the other */ bool operator<(const Task& other) const { return fd == other.fd ? listening_events < other.listening_events : fd < other.fd; @@ -80,10 +79,10 @@ namespace extension { }; /** - * @brief Rebuilds the list of file descriptors to poll + * Rebuilds the list of file descriptors to poll. * - * This function is called when the list of file descriptors to poll changes. It will rebuild the list of file - * descriptors used by poll + * This function is called when the list of file descriptors to poll changes. + * It will rebuild the list of file descriptors used by poll. */ void rebuild_list() { // Get the lock so we don't concurrently modify the list @@ -113,9 +112,9 @@ namespace extension { } /** - * @brief Fires the event for the task if it is ready + * Fires the event for the task if it is ready. * - * @param task the task to try to fire the event for + * @param task The task to try to fire the event for */ void fire_event(Task& task) { if (task.processing_events == 0 && task.waiting_events != 0) { @@ -154,7 +153,7 @@ namespace extension { } /** - * @brief Collects the events that have happened and sets them up to fire + * Collects the events that have happened and sets them up to fire. */ void process_events() { @@ -224,7 +223,7 @@ namespace extension { } /** - * @brief Bumps the notification pipe to wake up the poll command + * Bumps the notification pipe to wake up the poll command * * If the poll command is waiting it will wait forever if something doesn't happen. * When trying to update what to poll or shut down we need to wake it up so it can. @@ -367,23 +366,23 @@ namespace extension { } private: - /// @brief The receive file descriptor for our notification pipe + /// The receive file descriptor for our notification pipe fd_t notify_recv{-1}; - /// @brief The send file descriptor for our notification pipe + /// The send file descriptor for our notification pipe fd_t notify_send{-1}; - /// @brief The mutex to wait on when bumping to ensure poll has returned + /// The mutex to wait on when bumping to ensure poll has returned std::mutex poll_mutex; - /// @brief Whether or not we are shutting down + /// Whether or not we are shutting down std::atomic shutdown{false}; - /// @brief The mutex that protects the tasks list + /// The mutex that protects the tasks list std::mutex tasks_mutex; - /// @brief Whether or not the list of file descriptors is dirty compared to tasks + /// Whether or not the list of file descriptors is dirty compared to tasks bool dirty = true; - /// @brief The list of file descriptors to poll + /// The list of file descriptors to poll std::vector watches{}; - /// @brief The list of tasks that are waiting for IO events + /// The list of tasks that are waiting for IO events std::vector tasks{}; }; diff --git a/src/extension/IOController_Windows.hpp b/src/extension/IOController_Windows.hpp index 78a7a90e1..ac1196158 100644 --- a/src/extension/IOController_Windows.hpp +++ b/src/extension/IOController_Windows.hpp @@ -33,34 +33,34 @@ namespace extension { class IOController : public Reactor { private: - /// @brief The type that poll uses for events + /// The type that poll uses for events using event_t = long; // NOLINT(google-runtime-int) /** - * @brief A task that is waiting for an IO event + * A task that is waiting for an IO event. */ struct Task { Task() = default; Task(const fd_t& fd, event_t listening_events, std::shared_ptr reaction) : fd(fd), listening_events(listening_events), reaction(std::move(reaction)) {} - /// @brief The socket we are waiting on + /// The socket we are waiting on fd_t fd; - /// @brief The events that the task is interested in + /// The events that the task is interested in event_t listening_events{0}; - /// @brief The events that are waiting to be fired + /// The events that are waiting to be fired event_t waiting_events{0}; - /// @brief The events that are currently being processed + /// The events that are currently being processed event_t processing_events{0}; - /// @brief The reaction that is waiting for this event + /// The reaction that is waiting for this event std::shared_ptr reaction{nullptr}; }; /** - * @brief Rebuilds the list of file descriptors to poll + * Rebuilds the list of file descriptors to poll. * - * This function is called when the list of file descriptors to poll changes. It will rebuild the list of file - * descriptors used by poll + * This function is called when the list of file descriptors to poll changes. + * It will rebuild the list of file descriptors used by poll. */ void rebuild_list() { // Get the lock so we don't concurrently modify the list @@ -81,9 +81,9 @@ namespace extension { } /** - * @brief Fires the event for the task if it is ready + * Fires the event for the task if it is ready. * - * @param task the task to try to fire the event for + * @param task The task to try to fire the event for */ void fire_event(Task& task) { if (task.processing_events == 0 && task.waiting_events != 0) { @@ -114,7 +114,7 @@ namespace extension { } /** - * @brief Collects the events that have happened and sets them up to fire + * Collects the events that have happened and sets them up to fire. */ void process_event(const WSAEVENT& event) { @@ -154,7 +154,7 @@ namespace extension { } /** - * @brief Bumps the notification pipe to wake up the poll command + * Bumps the notification pipe to wake up the poll command. * * If the poll command is waiting it will wait forever if something doesn't happen. * When trying to update what to poll or shut down we need to wake it up so it can. @@ -169,11 +169,11 @@ namespace extension { } /** - * @brief Removes a task from the list and closes the event + * Removes a task from the list and closes the event. * - * @param it the iterator to the task to remove + * @param it The iterator to the task to remove * - * @return the iterator to the next task + * @return The iterator to the next task */ std::map::iterator remove_task(std::map::iterator it) { // Close the event @@ -314,19 +314,19 @@ namespace extension { } private: - /// @brief The event that is used to wake up the WaitForMultipleEvents call + /// The event that is used to wake up the WaitForMultipleEvents call WSAEVENT notifier; - /// @brief Whether or not we are shutting down + /// Whether or not we are shutting down std::atomic shutdown{false}; - /// @brief The mutex that protects the tasks list + /// The mutex that protects the tasks list std::mutex tasks_mutex; - /// @brief Whether or not the list of file descriptors is dirty compared to tasks + /// Whether or not the list of file descriptors is dirty compared to tasks bool dirty = true; - /// @brief The list of tasks that are currently being processed + /// The list of tasks that are currently being processed std::vector watches; - /// @brief The list of tasks that are waiting for IO events + /// The list of tasks that are waiting for IO events std::map tasks; }; diff --git a/src/extension/network/NUClearNetwork.cpp b/src/extension/network/NUClearNetwork.cpp index 4a49886a1..b89defc09 100644 --- a/src/extension/network/NUClearNetwork.cpp +++ b/src/extension/network/NUClearNetwork.cpp @@ -40,11 +40,11 @@ namespace extension { namespace network { /** - * @brief Read a single packet from the given udp file descriptor + * Read a single packet from the given udp file descriptor. * - * @param fd the file descriptor to read from + * @param fd The file descriptor to read from * - * @return the data and who it was sent from + * @return The data and who it was sent from */ std::pair> read_socket(fd_t fd) { diff --git a/src/extension/network/NUClearNetwork.hpp b/src/extension/network/NUClearNetwork.hpp index e7ee03407..210e80ee4 100644 --- a/src/extension/network/NUClearNetwork.hpp +++ b/src/extension/network/NUClearNetwork.hpp @@ -123,12 +123,12 @@ namespace extension { NUClearNetwork& operator=(NUClearNetwork&& /*rhs*/) noexcept = delete; /** - * @brief Send data using the NUClear network + * Send data using the NUClear network. * - * @param hash the identifying hash for the data - * @param data the bytes that are to be sent - * @param target who we are sending to (blank means everyone) - * @param reliable if the delivery of the data should be ensured + * @param hash The identifying hash for the data + * @param data The bytes that are to be sent + * @param target Who we are sending to (blank means everyone) + * @param reliable If the delivery of the data should be ensured */ void send(const uint64_t& hash, const std::vector& payload, @@ -136,53 +136,53 @@ namespace extension { bool reliable); /** - * @brief Set the callback to use when a data packet is completed + * Set the callback to use when a data packet is completed. * - * @param f the callback function + * @param f The callback function */ void set_packet_callback( std::function&&)> f); /** - * @brief Set the callback to use when a node joins the network + * Set the callback to use when a node joins the network. * - * @param f the callback function + * @param f The callback function */ void set_join_callback(std::function f); /** - * @brief Set the callback to use when a node leaves the network + * Set the callback to use when a node leaves the network. * - * @param f the callback function + * @param f The callback function */ void set_leave_callback(std::function f); /** - * @brief Set the callback to use when the system want's to notify when it next needs attention + * Set the callback to use when the system want's to notify when it next needs attention. * - * @param f the callback function + * @param f The callback function */ void set_next_event_callback(std::function f); /** - * @brief Leave the NUClear network + * Leave the NUClear network. */ void shutdown(); /** - * @brief Reset our network to use the new settings + * Reset our network to use the new settings. * - * @details - * Resets the networking system to use the new announce information and name. - * If the network was already joined, it will first leave and then rejoin the new network. - * If the provided address is multicast it will join a multicast network. If it is broadcast - * it will use IPv4 broadcast traffic to announce, unicast addresses will only announce to a single target. + * Resets the networking system to use the new announce information and name. + * If the network was already joined, it will first leave and then rejoin the new network. + * If the provided address is multicast it will join a multicast network. + * If it is broadcast it will use IPv4 broadcast traffic to announce, unicast addresses will only announce + * to a single target. * - * @param name the name of this node in the network - * @param address the address to announce on - * @param port the port to use for announcement - * @param bind_address the address to bind to (if unset will bind to all interfaces) - * @param network_mtu the mtu of the network we operate on + * @param name The name of this node in the network + * @param address The address to announce on + * @param port The port to use for announcement + * @param bind_address The address to bind to (if unset will bind to all interfaces) + * @param network_mtu The mtu of the network we operate on */ void reset(const std::string& name, const std::string& address, @@ -195,14 +195,14 @@ namespace extension { uint16_t network_mtu = 1500); /** - * @brief Process waiting data in the UDP sockets and send them to the callback if they are relevant. + * Process waiting data in the UDP sockets and send them to the callback if they are relevant. */ void process(); /** - * @brief Get the file descriptors that the network listens on + * Get the file descriptors that the network listens on. * - * @return a list of file descriptors that the system listens on + * @return A list of file descriptors that the system listens on */ std::vector listen_fds(); @@ -238,46 +238,46 @@ namespace extension { }; /** - * @brief Open our data udp socket + * Open our data udp socket. * - * @param bind_address the address to bind to or any to bind to all interfaces + * @param bind_address The address to bind to or any to bind to all interfaces */ void open_data(const sock_t& bind_address); /** - * @brief Open our announce udp socket + * Open our announce udp socket. * - * @param announce_target the target to announce to - * @param bind_address the address to bind to or any to bind to all interfaces + * @param announce_target The target to announce to + * @param bind_address The address to bind to or any to bind to all interfaces */ void open_announce(const sock_t& announce_target, const sock_t& bind_address); /** - * @brief Processes the given packet and calls the callback if a packet was completed + * Processes the given packet and calls the callback if a packet was completed. * - * @param address who the packet came from - * @param data the data that was sent in this packet + * @param address Who the packet came from + * @param data The data that was sent in this packet */ void process_packet(const sock_t& address, std::vector&& payload); /** - * @brief Send an announce packet to our announce address + * Send an announce packet to our announce address. */ void announce(); /** - * @brief Retransmit waiting packets that failed to send + * Retransmit waiting packets that failed to send. */ void retransmit(); /** - * @brief Send an individual packet to an individual target + * Send an individual packet to an individual target. * - * @param target the target to send the packet to - * @param header the header for this packet - * @param packet_no the packet number we are sending - * @param payload the data bytes for the entire packet - * @param reliable if the packet is reliable (don't drop) + * @param target The target to send the packet to + * @param header The header for this packet + * @param packet_no The packet number we are sending + * @param payload The data bytes for the entire packet + * @param reliable If the packet is reliable (don't drop) */ void send_packet(const sock_t& target, DataPacket header, @@ -286,18 +286,18 @@ namespace extension { const bool& reliable); /** - * @brief Get the map key for this socket address + * Get the map key for this socket address. * - * @param address who the packet came from + * @param address Who the packet came from * - * @return the map key for this socket + * @return The map key for this socket */ static std::array udp_key(const sock_t& address); /** - * @brief Remove a target from our list of targets + * Remove a target from our list of targets. * - * @param t the target to remove + * @param t The target to remove */ void remove_target(const std::shared_ptr& target); diff --git a/src/extension/network/wire_protocol.hpp b/src/extension/network/wire_protocol.hpp index f9832de62..a9d25eb86 100644 --- a/src/extension/network/wire_protocol.hpp +++ b/src/extension/network/wire_protocol.hpp @@ -39,12 +39,12 @@ namespace extension { namespace network { /** - * @brief A number that is used to represent the type of packet that is being sent/received + * A number that is used to represent the type of packet that is being sent/received */ enum Type : uint8_t { ANNOUNCE = 1, LEAVE = 2, DATA = 3, DATA_RETRANSMISSION = 4, ACK = 5, NACK = 6 }; /** - * @brief The header that is sent with every packet + * The header that is sent with every packet. */ PACK(struct PacketHeader { explicit PacketHeader(const Type& t) : type(t) {} diff --git a/src/id.hpp b/src/id.hpp index 318f4d896..b59535246 100644 --- a/src/id.hpp +++ b/src/id.hpp @@ -27,7 +27,7 @@ namespace NUClear { -/// @brief This type is used when NUClear requires a unique identifier +/// This type is used when NUClear requires a unique identifier using id_t = std::size_t; } // namespace NUClear diff --git a/src/message/CommandLineArguments.hpp b/src/message/CommandLineArguments.hpp index 3341a9d9d..cf6aad8b9 100644 --- a/src/message/CommandLineArguments.hpp +++ b/src/message/CommandLineArguments.hpp @@ -27,7 +27,7 @@ namespace NUClear { namespace message { /** - * @brief This type is a NUClear message type that holds command line arguments + * This type is a NUClear message type that holds command line arguments. */ struct CommandLineArguments : public std::vector { // Inherit constructors diff --git a/src/message/LogMessage.hpp b/src/message/LogMessage.hpp index 342880019..6b961f67a 100644 --- a/src/message/LogMessage.hpp +++ b/src/message/LogMessage.hpp @@ -32,17 +32,17 @@ namespace NUClear { namespace message { /** - * @brief This type is a NUClear message type that holds a log message. + * This type is a NUClear message type that holds a log message. */ struct LogMessage { /** - * @brief Construct a new Log Message object + * Construct a new Log Message object. * - * @param level the logging level of the log - * @param display_level the logging level of the reactor that made this log - * @param message the string contents of the message - * @param task the currently executing task that made this message or nullptr if not in a task + * @param level The logging level of the log + * @param display_level The logging level of the reactor that made this log + * @param message The string contents of the message + * @param task The currently executing task that made this message or nullptr if not in a task */ LogMessage(const LogLevel& level, const LogLevel& display_level, @@ -50,16 +50,16 @@ namespace message { std::shared_ptr task) : level(level), display_level(display_level), message(std::move(message)), task(std::move(task)) {} - /// @brief The logging level of the log. + /// The logging level of the log LogLevel level{}; - /// @brief The logging level of the reactor that made the log (the level to display at). + /// The logging level of the reactor that made the log (the level to display at) LogLevel display_level{}; - /// @brief The string contents of the message. + /// The string contents of the message std::string message{}; - /// @brief The currently executing task that made this message + /// The currently executing task that made this message const std::shared_ptr task{nullptr}; }; diff --git a/src/message/NetworkConfiguration.hpp b/src/message/NetworkConfiguration.hpp index 440b3f773..d4ef89b64 100644 --- a/src/message/NetworkConfiguration.hpp +++ b/src/message/NetworkConfiguration.hpp @@ -43,15 +43,15 @@ namespace message { , bind_address(std::move(bind_address)) , mtu(mtu) {} - /// @brief The name of this node when connecting to the NUClear network + /// The name of this node when connecting to the NUClear network std::string name{}; - /// @brief The address to announce to the NUClear network + /// The address to announce to the NUClear network std::string announce_address{}; - /// @brief The port to announce to the NUClear network + /// The port to announce to the NUClear network uint16_t announce_port{0}; - /// @brief The address of the interface to bind to when connecting to the NUClear network + /// The address of the interface to bind to when connecting to the NUClear network std::string bind_address{}; - /// @brief The maximum transmission unit for this node + /// The maximum transmission unit for this node uint16_t mtu{1500}; }; diff --git a/src/message/ReactionStatistics.hpp b/src/message/ReactionStatistics.hpp index b3e953cc4..40155157a 100644 --- a/src/message/ReactionStatistics.hpp +++ b/src/message/ReactionStatistics.hpp @@ -26,16 +26,16 @@ #include #include #include -#include "../id.hpp" #include "../clock.hpp" +#include "../id.hpp" #include "../threading/ReactionIdentifiers.hpp" namespace NUClear { namespace message { /** - * @brief Holds details about reactions that are executed. + * Holds details about reactions that are executed. */ struct ReactionStatistics { @@ -58,23 +58,23 @@ namespace message { , finished(finish) , exception(std::move(exception)) {} - /// @brief A string containing the username/on arguments/and callback name of the reaction. + /// A string containing the username/on arguments/and callback name of the reaction threading::ReactionIdentifiers identifiers; - /// @brief The id of this reaction. + /// The id of this reaction NUClear::id_t reaction_id{0}; - /// @brief The task id of this reaction. + /// The task id of this reaction NUClear::id_t task_id{0}; - /// @brief The reaction id of the reaction that caused this one or 0 if there was not one + /// The reaction id of the reaction that caused this one or 0 if there was not one NUClear::id_t cause_reaction_id{0}; - /// @brief The reaction id of the task that caused this task or 0 if there was not one + /// The reaction id of the task that caused this task or 0 if there was not one NUClear::id_t cause_task_id{0}; - /// @brief The time that this reaction was emitted to the thread pool + /// The time that this reaction was emitted to the thread pool clock::time_point emitted{}; - /// @brief The time that execution started on this reaction + /// The time that execution started on this reaction clock::time_point started{}; - /// @brief The time that execution finished on this reaction + /// The time that execution finished on this reaction clock::time_point finished{}; - /// @brief An exception pointer that can be rethrown (if the reaction threw an exception) + /// An exception pointer that can be rethrown (if the reaction threw an exception) std::exception_ptr exception{nullptr}; }; diff --git a/src/message/TimeTravel.hpp b/src/message/TimeTravel.hpp index c2010b8ec..9a32ed881 100644 --- a/src/message/TimeTravel.hpp +++ b/src/message/TimeTravel.hpp @@ -28,28 +28,28 @@ namespace NUClear { namespace message { /** - * @brief This message is used to adjust the time of the system clock and the rate at which time passes. + * This message is used to adjust the time of the system clock and the rate at which time passes. * * Using this message allows the NUClear system to adapt to the change by adjusting any time based operations * to the new time and rate. */ struct TimeTravel { enum class Action { - /// @brief Adjust clock and move all chrono tasks with it + /// Adjust clock and move all chrono tasks with it RELATIVE, - /// @brief Adjust clock to target time and leave chrono tasks where they are + /// Adjust clock to target time and leave chrono tasks where they are ABSOLUTE, - /// @brief Adjust clock to as close to target as possible without skipping any chrono tasks + /// Adjust clock to as close to target as possible without skipping any chrono tasks NEAREST, }; - /// @brief The target time to set the clock to + /// The target time to set the clock to clock::time_point target = clock::now(); - /// @brief The rate at which time should pass + /// The rate at which time should pass double rtf = 1.0; - /// @brief The type of time travel to perform + /// The type of time travel to perform Action type = Action::RELATIVE; TimeTravel() = default; diff --git a/src/threading/Reaction.hpp b/src/threading/Reaction.hpp index 2d48b6c4d..9dd0774f0 100644 --- a/src/threading/Reaction.hpp +++ b/src/threading/Reaction.hpp @@ -27,9 +27,9 @@ #include #include #include -#include "../id.hpp" #include +#include "../id.hpp" #include "../util/GeneratedCallback.hpp" #include "ReactionIdentifiers.hpp" #include "ReactionTask.hpp" @@ -42,13 +42,12 @@ class Reactor; namespace threading { /** - * @brief This class holds the definition of a Reaction (call signature). + * This class holds the definition of a Reaction. * - * @details - * A reaction holds the information about a callback. It holds the options as to how to process it in the - * scheduler. - * It also holds a function which is used to generate databound Task objects (callback with the function arguments - * already loaded and ready to run). + * A reaction holds the information about a callback. + * It holds the options as to how to process it in the scheduler. + * It also holds a function which is used to generate databound Task objects. + * i.e. callback with the function arguments already loaded and ready to run. */ class Reaction { // Reaction handles are given to user code to enable and disable the reaction @@ -60,16 +59,16 @@ namespace threading { using TaskGenerator = std::function; /** - * @brief Constructs a new Reaction with the passed callback generator and options + * Constructs a new Reaction with the passed callback generator and options. * - * @param reactor the reactor this belongs to - * @param identifiers string identification information for the reaction - * @param callback the callback generator function (creates databound callbacks) + * @param reactor The reactor this belongs to + * @param identifiers String identification information for the reaction + * @param callback The callback generator function (creates databound callbacks) */ Reaction(Reactor& reactor, ReactionIdentifiers&& identifiers, TaskGenerator&& generator); /** - * @brief creates a new databound callback task that can be executed. + * Creates a new databound callback task that can be executed. * * @return a unique_ptr to a Task which has the data for it's call bound into it */ @@ -97,41 +96,41 @@ namespace threading { } /** - * @brief returns true if this reaction is currently enabled + * @return `true` if this reaction is currently enabled */ bool is_enabled() const; - /// @brief the reactor this belongs to + /// the reactor this belongs to Reactor& reactor; - /// @brief This holds the identifying strings for this reaction + /// This holds the identifying strings for this reaction ReactionIdentifiers identifiers; - /// @brief the unique identifier for this Reaction object + /// the unique identifier for this Reaction object const NUClear::id_t id{++reaction_id_source}; - /// @brief if this is false, we cannot emit ReactionStatistics from any reaction triggered by this one + /// if this is false, we cannot emit ReactionStatistics from any reaction triggered by this one bool emit_stats{true}; - /// @brief the number of currently active tasks (existing reaction tasks) + /// the number of currently active tasks (existing reaction tasks) std::atomic active_tasks{0}; - /// @brief if this reaction object is currently enabled + /// if this reaction object is currently enabled std::atomic enabled{true}; - /// @brief list of functions to use to unbind the reaction and clean + /// list of functions to use to unbind the reaction and clean std::vector> unbinders; /** - * @brief Unbinds this reaction from it's context + * Unbinds this reaction from it's context */ void unbind(); private: - /// @brief a source for reaction_ids, atomically creates longs + /// a source for reaction_ids, atomically creates longs static std::atomic reaction_id_source; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) - /// @brief the callback generator function (creates databound callbacks) + /// the callback generator function (creates databound callbacks) TaskGenerator generator; }; diff --git a/src/threading/ReactionHandle.hpp b/src/threading/ReactionHandle.hpp index fd3f7d6f9..abbab9550 100644 --- a/src/threading/ReactionHandle.hpp +++ b/src/threading/ReactionHandle.hpp @@ -36,29 +36,26 @@ namespace NUClear { namespace threading { /** - * @brief Gives user code access to control the reaction object. + * Gives user code access to control the reaction object. * - * @details - * This object is given to user code when they create a reaction. It contains functions which allow changing of - * the reaction after it has been created such as enabling and disabling its execution. + * This object is given to user code when they create a reaction. + * It contains functions which allow changing of the reaction after it has been created such as enabling and + * disabling its execution. */ class ReactionHandle { public: - /// @brief the reaction that we are managing + /// The reaction that we are managing std::weak_ptr context; /** - * @brief - * Creates a new ReactionHandle for the reaction that is passed in. + * Creates a new ReactionHandle for the reaction that is passed in. * - * @param - * context the reaction that we are interacting with. + * @param context The reaction that we are interacting with */ explicit ReactionHandle(const std::shared_ptr& context = nullptr) : context(context) {} /** - * @brief - * Enables the reaction so that associated tasks will be scheduled and queued when the reaction is triggered. + * Enables the reaction so that associated tasks will be scheduled and queued when the reaction is triggered. */ inline ReactionHandle& enable() { auto c = context.lock(); @@ -69,11 +66,12 @@ namespace threading { } /** - * @brief - * Disables the reaction. - * When disabled, any associated tasks will not be created if triggered. All reaction configuration is still - * available, so that the reaction can be enabled when required. - * Note that a reaction which has been bound by an on request should not be disabled. + * Disables the reaction. + * + * When disabled, any associated tasks will not be created if triggered. + * All reaction configuration is still available, so that the reaction can be enabled when required. + * Note that a reaction which has been bound by an on request should not be disabled as it will + * continuously spin checking for new tasks. */ inline ReactionHandle& disable() { auto c = context.lock(); @@ -84,10 +82,9 @@ namespace threading { } /** - * @brief - * Sets the run status of the reaction handle. - * @param set - * true for enable, false for disable + * Sets the run status of the reaction handle. + * + * @param set true for enable, false for disable */ inline ReactionHandle& enable(const bool& set) { auto c = context.lock(); @@ -98,11 +95,11 @@ namespace threading { } /** - * @brief - * Informs if the reaction is currently enabled. + * Checks if the reaction is currently enabled. * - * @return - * true if enabled, false if disabled + * Will return false if the reaction has been unbound or for an unbound reaction handle. + * + * @return true if enabled, false if disabled */ inline bool enabled() const { auto c = context.lock(); @@ -110,11 +107,12 @@ namespace threading { } /** - * @brief - * Removes a reaction request from the runtime environment. This action is not reversible, once a reaction has - * been unbound, it is no longer available for further use during the instance of runtime. - * This is most commonly used for the unbinding of network configuration before attempting to re-set - * configuration details during runtime. + * Removes a reaction request from the runtime environment. + * + * This action is not reversible, once a reaction has been unbound, it is no longer available for further use + * during the instance of runtime. + * This is most commonly used for the unbinding of network configuration before attempting to re-set + * configuration details during runtime. */ // NOLINTNEXTLINE(readability-make-member-function-const) unbinding modifies the reaction inline void unbind() { @@ -125,11 +123,9 @@ namespace threading { } /** - * @brief - * Returns if this reaction handle holds a valid pointer (may be already unbound) + * Returns if this reaction handle holds a valid pointer (may be already unbound) * - * @return - * true if the reaction held in this is not a nullptr + * @return true if the reaction is still valid */ inline operator bool() const { return bool(context.lock()); diff --git a/src/threading/ReactionIdentifiers.hpp b/src/threading/ReactionIdentifiers.hpp index f12c7010a..2f33e5bbf 100644 --- a/src/threading/ReactionIdentifiers.hpp +++ b/src/threading/ReactionIdentifiers.hpp @@ -29,28 +29,28 @@ namespace NUClear { namespace threading { /** - * @brief This struct holds string fields that can be used to identify a reaction. + * This struct holds string fields that can be used to identify a reaction. */ struct ReactionIdentifiers { /** - * @brief Construct a new Identifiers object + * Construct a new Identifiers object. * - * @param name the name of the reaction provided by the user - * @param reactor the name of the reactor that this reaction belongs to - * @param dsl the DSL that this reaction was created from - * @param function the callback function that this reaction is bound to + * @param name The name of the reaction provided by the user + * @param reactor The name of the reactor that this reaction belongs to + * @param dsl The DSL that this reaction was created from + * @param function The callback function that this reaction is bound to */ ReactionIdentifiers(std::string name, std::string reactor, std::string dsl, std::string function) : name(std::move(name)), reactor(std::move(reactor)), dsl(std::move(dsl)), function(std::move(function)) {} - /// @brief The name of the reaction provided by the user + /// The name of the reaction provided by the user std::string name; - /// @brief The name of the reactor that this reaction belongs to + /// The name of the reactor that this reaction belongs to std::string reactor; - /// @brief The DSL that this reaction was created from + /// The DSL that this reaction was created from std::string dsl; - /// @brief The callback function that this reaction is bound to + /// The callback function that this reaction is bound to std::string function; }; diff --git a/src/threading/ReactionTask.hpp b/src/threading/ReactionTask.hpp index 765c58cb7..ea074f0ce 100644 --- a/src/threading/ReactionTask.hpp +++ b/src/threading/ReactionTask.hpp @@ -39,21 +39,21 @@ namespace NUClear { namespace threading { /** - * @brief This is a databound call of a Reaction ready to be executed. + * This is a databound call of a Reaction ready to be executed. * * @tparam ReactionType the type of the reaction * - * @details - * This class holds a reaction that is ready to be executed. It is a Reaction object which has had it's callback - * parameters bound with data. This can then be executed as a function to run the call inside it. + * This class holds a reaction that is ready to be executed. + * It is a Reaction object which has had it's callback parameters bound with data. + * This can then be executed as a function to run the call inside it. */ template class Task { private: - /// @brief a source for task ids, atomically creates longs + /// A source for task ids, atomically creates longs static std::atomic task_id_source; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) - /// @brief the current task that is being executed by this thread (or nullptr if none is) + /// The current task that is being executed by this thread (or nullptr if none is) static ATTRIBUTE_TLS Task* current_task; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) public: @@ -61,22 +61,22 @@ namespace threading { using TaskFunction = std::function&)>; /** - * @brief Gets the current executing task, or nullptr if there isn't one. + * Gets the current executing task, or nullptr if there isn't one. * - * @return the current executing task or nullptr if there isn't one + * @return The current executing task or nullptr if there isn't one */ static const Task* get_current_task() { return current_task; } /** - * @brief Creates a new ReactionTask object bound with the parent Reaction object (that created it) and task. + * Creates a new ReactionTask object bound with the parent Reaction object (that created it) and task. * - * @param parent the Reaction object that spawned this ReactionTask. - * @param priority the priority to use when executing this task. - * @param group_descriptor the descriptor for the group that this task should run in - * @param thread_pool_descriptor the descriptor for the thread pool that this task should be queued in - * @param callback the data bound callback to be executed in the thread pool. + * @param parent The Reaction object that spawned this ReactionTask + * @param priority The priority to use when executing this task + * @param group_descriptor The descriptor for the group that this task should run in + * @param thread_pool_descriptor The descriptor for the thread pool that this task should be queued in + * @param callback The data bound callback to be executed in the thread pool */ Task(ReactionType& parent, const int& priority, @@ -101,11 +101,10 @@ namespace threading { /** - * @brief Runs the internal data bound task and times it. + * Runs the internal data bound task and times it. * - * @details - * This runs the internal data bound task and times how long the execution takes. These figures can then be - * used in a debugging context to calculate how long callbacks are taking to run. + * This runs the internal data bound task and times how long the execution takes. + * These figures can then be used in a debugging context to calculate how long callbacks are taking to run. */ inline void run() { @@ -118,34 +117,35 @@ namespace threading { } /** - * @brief Generate a new unique task id + * Generate a new unique task id. * - * @return a new unique task id + * @return A new unique task id */ static inline NUClear::id_t new_task_id() { return ++task_id_source; } - /// @brief the parent Reaction object which spawned this + /// The parent Reaction object which spawned this ReactionType& parent; - /// @brief the task id of this task (the sequence number of this particular task) + /// The task id of this task (the sequence number of this particular task) NUClear::id_t id{new_task_id()}; - /// @brief the priority to run this task at + /// The priority to run this task at int priority; - /// @brief the statistics object that persists after this for information and debugging + /// The statistics object that persists after this for information and debugging std::shared_ptr stats; - /// @brief if these stats are safe to emit. It should start true, and as soon as we are a reaction based on - /// reaction statistics becomes false for all created tasks. This is to stop infinite loops of death. + /// If these stats are safe to emit. It should start true, and as soon as we are a reaction based on + /// reaction statistics becomes false for all created tasks. + /// This is to stop infinite loops tasks triggering tasks. bool emit_stats; - /// @brief details about the group that this task will run in + /// Details about the group that this task will run in util::GroupDescriptor group_descriptor; - /// @brief details about the thread pool that this task will run from, this will also influence what task queue - /// the tasks will be queued on + /// Details about the thread pool that this task will run from, this will also influence what task queue the + /// tasks will be queued on util::ThreadPoolDescriptor thread_pool_descriptor; - /// @brief the data bound callback to be executed + /// The data bound callback to be executed /// @attention note this must be last in the list as the this pointer is passed to the callback generator TaskFunction callback; }; diff --git a/src/threading/TaskScheduler.hpp b/src/threading/TaskScheduler.hpp index 937d855ad..585ac0f67 100644 --- a/src/threading/TaskScheduler.hpp +++ b/src/threading/TaskScheduler.hpp @@ -41,9 +41,8 @@ namespace NUClear { namespace threading { /** - * @brief This class is responsible for scheduling tasks and distributing them amongst threads. + * This class is responsible for scheduling tasks and distributing them amongst threads. * - * @details * PRIORITY * what priority this task should run with * tasks are ordered by priority -> creation order @@ -58,59 +57,61 @@ namespace threading { * if the submitter of this task should wait until this task is finished before returning (for DIRECT * emits) * - * @em Priority - * @code Priority

@endcode - * When a priority is encountered, the task will be scheduled to execute based on this. If one of the three - * normal options are specified (HIGH, DEFAULT and LOW), then within the specified Sync group, it will run - * before, normally or after other reactions. + * @em Priority + * @code Priority

@endcode + * When a priority is encountered, the task will be scheduled to execute based on this. + * If one of the three normal options are specified (HIGH, DEFAULT and LOW), then within the specified Sync group, + * it will run before, normally or after other reactions. * - * @em Sync - * @code Sync @endcode - * When a Sync type is encountered, the system uses this as a compile time mutex flag. It will not allow two - * callbacks with the same Sync type to execute at the same time. It will effectively ensure that all of the - * callbacks with this type run in sequence with each other, rather then in parallel. + * @em Sync + * @code Sync @endcode + * When a Sync type is encountered, the system uses this as a compile time mutex flag. + * It will not allow two callbacks with the same Sync type to execute at the same time. + * It will effectively ensure that all of the callbacks with this type run in sequence with each other, rather then + * in parallel. * - * @em Group - * @code Group @endcode - * When a Group type is encountered, the system uses this as a compile time semaphore flag. It will not allow - * (GroupConcurrency + 1) callbacks with the same Group type to execute at the same time. It will effectively - * ensure that the first GroupConcurrency callbacks with this type run in parallel and all subsequent callbacks - * will be queued to run when one of the first GroupConcurrency callbacks have returned + * @em Group + * @code Group @endcode + * When a Group type is encountered, the system uses this as a compile time semaphore flag. + * It will not allow (GroupConcurrency + 1) callbacks with the same Group type to execute at the same time. + * It will effectively ensure that the first GroupConcurrency callbacks with this type run in parallel and all + * subsequent callbacks will be queued to run when one of the first GroupConcurrency callbacks have returned * - * @em Single - * @code Single @endcode - * If single is encountered while processing the function, and a Task object for this Reaction is already + * @em Single + * @code Single @endcode + * If single is encountered while processing the function, and a Task object for this Reaction is already * running in a thread, or waiting in the Queue, then this task is ignored and dropped from the system. */ class TaskScheduler { private: /** - * @brief Exception thrown when a thread in the pool should shut down. + * Exception thrown when a thread in the pool should shut down. */ class ShutdownThreadException : public std::exception {}; /** - * @brief A struct which contains all the information about an individual task + * A struct which contains all the information about an individual task. */ struct Task { - /// @brief The id of this task used for ordering + /// The id of this task used for ordering NUClear::id_t id; - /// @brief The priority of this task + /// The priority of this task int priority; - /// @brief The group descriptor for this task + /// The group descriptor for this task util::GroupDescriptor group_descriptor; - /// @brief The thread pool descriptor for this task + /// The thread pool descriptor for this task util::ThreadPoolDescriptor thread_pool_descriptor; - /// @brief The callback to be executed + /// The callback to be executed std::function run; - /// @brief If task has been checked for runnable + /// If task has been checked for runnable bool checked_runnable{false}; /** - * @brief Compare tasks based on their priority + * Compare tasks based on their priority. * * @param other the other task to compare to - * @return true if this task has a higher priority than the other task + * + * @return `true` if this task has a higher priority than the other task */ bool operator<(const Task& other) const { return priority == other.priority ? id < other.id : priority > other.priority; @@ -118,69 +119,68 @@ namespace threading { }; /** - * @brief A struct which contains all the information about an individual thread pool + * A struct which contains all the information about an individual thread pool. */ struct PoolQueue { explicit PoolQueue(const util::ThreadPoolDescriptor& pool_descriptor) : pool_descriptor(pool_descriptor) {} - /// @brief The descriptor for this thread pool + /// The descriptor for this thread pool const util::ThreadPoolDescriptor pool_descriptor; - /// @brief The threads which are running in this thread pool + /// The threads which are running in this thread pool std::vector> threads; - /// @brief The number of runnable tasks in this thread pool + /// The number of runnable tasks in this thread pool size_t runnable_tasks{0}; - /// @brief The queue of tasks for this specific thread pool + /// The queue of tasks for this specific thread pool std::vector queue; - /// @brief The mutex which protects the queue + /// The mutex which protects the queue std::recursive_mutex mutex; - /// @brief The condition variable which threads wait on if they can't get a task + /// The condition variable which threads wait on if they can't get a task std::condition_variable_any condition; - /// @brief The map of idle tasks for this thread pool + /// The map of idle tasks for this thread pool std::map> idle_tasks; /** - * @brief Submit a new task to this thread pool + * Submit a new task to this thread pool. * - * @param task the task to submit + * @param task The task to submit */ void submit(Task&& task); }; public: /** - * @brief Constructs a new TaskScheduler instance, and builds the nullptr sync queue. + * Constructs a new TaskScheduler instance, and builds the nullptr sync queue. */ explicit TaskScheduler(const size_t& default_thread_count); /** - * @brief Starts the scheduler, and begins executing tasks. + * Starts the scheduler, and begins executing tasks. * * The main thread will stay in this function executing tasks until the scheduler is shutdown. */ void start(); /** - * @brief + * * Shuts down the scheduler, all waiting threads are woken, and any attempt to get a task results in an * exception */ void shutdown(); /** - * @brief Submit a new task to be executed to the Scheduler. + * Submit a new task to be executed to the Scheduler. + * * - * @details - * This method submits a new task to the scheduler. This task will then be sorted into the appropriate - * queue based on it's sync type and priority. It will then wait there until it is removed by a thread to - * be processed. + * This method submits a new task to the scheduler. + * This task will then be sorted into the appropriate queue based on it's sync type and priority. + * It will then wait there until it is removed by a thread to be processed. * - * @param id the id of this task used for ordering tasks of the same priority - * @param priority the priority of this task - * @param group the group descriptor for this task - * @param pool the thread pool descriptor for this task - * @param immediate if this task should run immediately in the current thread. If immediate execution of this - * task is not possible (e.g. due to group concurrency restrictions) this task will be queued - * as normal - * @param func the function to execute + * @param id The id of this task used for ordering tasks of the same priority + * @param priority The priority of this task + * @param group The group descriptor for this task + * @param pool The thread pool descriptor for this task + * @param immediate If this task should run immediately in the current thread. + * If immediate execution of this task is not possible this task will be queued as normal + * @param func The function to execute */ void submit(const NUClear::id_t& id, const int& priority, @@ -190,25 +190,25 @@ namespace threading { std::function&& func); /** - * @brief Adds an idle task to the task scheduler. + * Adds an idle task to the task scheduler. * * This function adds an idle task to the task scheduler, which will be executed when the thread pool associated - * with the given `pool_id` has no other tasks to execute. The `task` parameter is a callable object that - * represents the idle task to be executed. + * with the given `pool_id` has no other tasks to execute. + * The `task` parameter is a callable object that represents the idle task to be executed. * - * @param id The ID of the task. + * @param id The ID of the task. * @param pool_descriptor The descriptor for the thread pool to test for idle - * @param task The idle task to be executed. + * @param task The idle task to be executed. */ void add_idle_task(const NUClear::id_t& id, const util::ThreadPoolDescriptor& pool_descriptor, std::function&& task); /** - * @brief Removes an idle task from the task scheduler. + * Removes an idle task from the task scheduler. * - * This function removes an idle task from the task scheduler. The `id` and `pool_id` parameters are used to - * identify the idle task to be removed. + * This function removes an idle task from the task scheduler. + * The `id` and `pool_id` parameters are used to identify the idle task to be removed. * * @param id The ID of the task * @param pool_descriptor The descriptor for the thread pool to test for idle @@ -217,55 +217,53 @@ namespace threading { private: /** - * @brief Get a task object to be executed by a thread. + * Get a task object to be executed by a thread. * - * @details - * This method will get a task object to be executed from the queue. It will block until such a time as a - * task is available to be executed. For example, if a task with a particular sync type was out, then this - * thread would block until that sync type was no longer out, and then it would take a task. + * This method will get a task object to be executed from the queue. + * It will block until such a time as a task is available to be executed. + * For example, if a task with a particular sync type was out, then this thread would block until that sync type + * was no longer out, and then it would take a task. * - * @return the task which has been given to be executed + * @return The task which has been given to be executed */ Task get_task(); /** - * @brief Gets a pool queue for the given thread pool descriptor or creates one if it does not exist + * Gets a pool queue for the given thread pool descriptor or creates one if it does not exist. * - * @param pool the descriptor for the thread pool to get or create + * @param pool The descriptor for the thread pool to get or create * - * @return a shared pointer to the pool queue for the given thread pool descriptor + * @return A shared pointer to the pool queue for the given thread pool descriptor */ std::shared_ptr get_pool_queue(const util::ThreadPoolDescriptor& pool); /** - * @brief The function that each thread runs + * The function that each thread runs. * - * @details This function will repeatedly query the task queue for new a task to run and then execute that task + * This function will repeatedly query the task queue for new a task to run and then execute that task. * - * @param pool the thread pool to run from and the task queue to get tasks from + * @param pool The thread pool to run from and the task queue to get tasks from */ void pool_func(std::shared_ptr pool); /** - * @brief Start all threads for the given thread pool + * Start all threads for the given thread pool */ void start_threads(const std::shared_ptr& pool); /** - * @brief Execute the given task + * Execute the given task. * - * @details After execution of the task has completed the number of active tasks in the tasks' group is - * decremented + * After execution of the task has completed the number of active tasks in the tasks' group is decremented * * @param task the task to execute */ void run_task(Task&& task); /** - * @brief Determines if the given task is able to be executed + * Determines if the given task is able to be executed. * - * @details If the current thread is able to be executed the number of active tasks in the tasks' groups is - * incremented + * If the current thread is able to be executed the number of active tasks in the tasks' groups is incremented * * @param group the group descriptor for the task * @@ -274,30 +272,30 @@ namespace threading { */ bool is_runnable(const util::GroupDescriptor& group); - /// @brief if the scheduler is running, and accepting new tasks. If this is false and a new, non-immediate, task - /// is submitted it will be ignored + /// If the scheduler is running, and accepting new tasks. + /// If this is false and a new, non-immediate, task is submitted it will be ignored. std::atomic running{true}; - /// @brief if the scheduler has been started. This is set to true after a call to start is made. Once this is - /// set to true all threads will begin executing tasks from the tasks queue + /// If the scheduler has been started. This is set to true after a call to start is made. + /// Once this is set to true all threads will begin executing tasks from the tasks queue. std::atomic started{false}; - /// @brief A map of group ids to the number of active tasks currently running in that group + /// A map of group ids to the number of active tasks currently running in that group std::map groups{}; - /// @brief mutex for the group map + /// Mutex for the group map std::mutex group_mutex; - /// @brief mutex for the idle tasks + /// Mutex for the idle tasks std::mutex idle_mutex; - /// @brief global idle tasks to be executed when no other tasks are running + /// Global idle tasks to be executed when no other tasks are running std::map> idle_tasks{}; - /// @brief the total number of threads that have runnable tasks + /// The total number of threads that have runnable tasks std::atomic global_runnable_tasks{0}; - /// @brief A map of pool descriptor ids to pool descriptors + /// A map of pool descriptor ids to pool descriptors std::map> pool_queues{}; - /// @brief a mutex for when we are modifying the pool_queues map + /// A mutex for when we are modifying the pool_queues map std::mutex pool_mutex; - /// @brief a pointer to the pool_queue for the current thread so it does not have to access via the map + /// A pointer to the pool_queue for the current thread so it does not have to access via the map // NOLINTNEXTLINE(cppcoreguidelines-avoid-non-const-global-variables) static ATTRIBUTE_TLS std::shared_ptr* current_queue; }; diff --git a/src/util/FileDescriptor.hpp b/src/util/FileDescriptor.hpp index 5b3e218b9..dce267e17 100644 --- a/src/util/FileDescriptor.hpp +++ b/src/util/FileDescriptor.hpp @@ -31,20 +31,20 @@ namespace NUClear { namespace util { /** - * @brief An RAII file descriptor. + * An RAII file descriptor. * - * @details This class represents an RAII file descriptor. - * It will close the file descriptor it holds on destruction. + * This class represents an RAII file descriptor. + * It will close the file descriptor it holds on destruction. */ class FileDescriptor { public: /** - * @brief Construct a File Descriptor with an invalid file descriptor. + * Construct a File Descriptor with an invalid file descriptor. */ FileDescriptor(); /** - * @brief Constructs a new RAII file descriptor. + * Constructs a new RAII file descriptor. * * @param fd the file descriptor to hold * @param cleanup an optional cleanup function to call on close @@ -60,12 +60,12 @@ namespace util { FileDescriptor& operator=(FileDescriptor&& rhs) noexcept; /** - * @brief Destruct the file descriptor, closes the held fd + * Destruct the file descriptor, closes the held fd. */ ~FileDescriptor(); /** - * @brief Get the currently held file descriptor + * Get the currently held file descriptor. * * @return the file descriptor */ @@ -74,36 +74,35 @@ namespace util { fd_t get(); /** - * @brief Returns if the currently held file descriptor is valid + * Returns if the currently held file descriptor is valid. * - * @return true if the file descriptor is valid - * @return false if the file descriptor is invalid + * @return `true` if the file descriptor is valid */ bool valid() const; /** - * @brief Close the currently held file descriptor + * Close the currently held file descriptor. */ void close(); /** - * @brief Release the currently held file descriptor + * Release the currently held file descriptor. * - * @return the file descriptor + * @return The file descriptor */ fd_t release(); /** - * @brief Implicitly convert this class to a file descriptor + * Implicitly convert this class to a file descriptor. * - * @return the file descriptor + * @return The file descriptor */ operator fd_t(); private: - /// @brief The held file descriptor + /// The held file descriptor fd_t fd{INVALID_SOCKET}; - /// @brief An optional cleanup function to call on close + /// An optional cleanup function to call on close std::function cleanup; }; diff --git a/src/util/FunctionFusion.hpp b/src/util/FunctionFusion.hpp index caf7aa570..6198ee0c5 100644 --- a/src/util/FunctionFusion.hpp +++ b/src/util/FunctionFusion.hpp @@ -30,22 +30,22 @@ namespace NUClear { namespace util { /** - * @brief Applies a single set of function fusion with expanded arguments - * @details Calls the function held in the template type Function. - * for the arguments it uses the parameter packs Shared and Selected - * to expand the passed tuple args and forward those selected - * arguments to the function. This function is normally called by - * the other overload of apply_function_fusion_call to get the expanded - * parameter packs. + * Applies a single set of function fusion with expanded arguments. * - * @param args the arguments that were passed to the superfunction + * Calls the function held in the template type Function. + * For the arguments it uses the parameter packs Shared and Selected to expand the passed tuple args and forward + * those selected arguments to the function. + * This function is normally called by the other overload of apply_function_fusion_call to get the expanded + * parameter packs. * - * @tparam Function the struct that holds the call function wrapper to be called - * @tparam Shared the index list of shared arguments at the start of the argument pack to use - * @tparam Selected the index list of selected arguments in the argument pack to use - * @tparam Arguments the types of the arguments passed into the function + * @tparam Function The struct that holds the call function wrapper to be called + * @tparam Shared The index list of shared arguments at the start of the argument pack to use + * @tparam Selected The index list of selected arguments in the argument pack to use + * @tparam Arguments The types of the arguments passed into the function * - * @return the object returned by the called subfunction + * @param args The arguments that were passed to the superfunction + * + * @return The object returned by the called subfunction */ template auto apply_function_fusion_call(std::tuple&& args, @@ -56,8 +56,8 @@ namespace util { } /** - * @brief Applies a single set of function fusion with argument ranges - * @details Calls the function held in the template type Function. + * Applies a single set of function fusion with argument ranges + * Calls the function held in the template type Function. * for the arguments it uses the parameter packs Shared and Selected * to expand the passed tuple args and forward those selected * arguments to the function. @@ -86,12 +86,12 @@ namespace util { struct FunctionFusionCaller; /** - * @brief Termination case for calling a function fusion. + * Termination case for calling a function fusion. * - * @details terminates by just returning an empty tuple + * Terminates by just returning an empty tuple. * - * @tparam Shared the number of arguments (from 0) to use in all of the calls - * @tparam Arguments the type of the provided arguments + * @tparam Shared The number of arguments (from 0) to use in all of the calls + * @tparam Arguments The type of the provided arguments */ template struct FunctionFusionCaller, Shared, std::tuple<>, std::tuple> { @@ -101,17 +101,17 @@ namespace util { }; /** - * @brief Used to call the result of the function fusion with the given arguments - * @details Provides a call function that will split the given arguments amongst the functions - * according to the provided ranges. + * Used to call the result of the function fusion with the given arguments. + * + * Provides a call function that will split the given arguments amongst the functions according to the provided + * ranges. * - * @tparam CurrentFunction the current function we are calling in this class - * @tparam Functions the remaining functions we are going to call - * @tparam Shared the number of arguments (from 0) to use in all of the calls - * @tparam CurrentRange the range of arguments to use in the current call - * @tparam Ranges a set of pairs of integers that describe the first and last - * argument provided to each respective function - * @tparam Arguments the type of the provided arguments + * @tparam CurrentFunction The current function we are calling in this class + * @tparam Functions The remaining functions we are going to call + * @tparam Shared The number of arguments (from 0) to use in all of the calls + * @tparam CurrentRange The range of arguments to use in the current call + * @tparam Ranges Pairs of integers that describe the first and last argument provided to each function + * @tparam Arguments The type of the provided arguments */ template > : public std::true_type { private: /** - * @brief Calls a single function in the function set. + * Calls a single function in the function set. * - * @param e the range sequence providing the start and end of the relevant arguments - * @param args the arguments to be used to call + * @tparam Function The function that we are going to call + * @tparam Start The index of the first argument to pass to the function + * @tparam End The index of the element after the last argument to pass to the function * - * @tparam Function the function that we are going to call - * @tparam Start the index of the first argument to pass to the function - * @tparam End the index of the element after the last argument to pass to the function + * @param e The range sequence providing the start and end of the relevant arguments + * @param args The arguments to be used to call * * @return the result of calling this specific function */ @@ -144,12 +144,12 @@ namespace util { } /** - * @brief This function exists unimplemented to absorb incorrect template instantiations. - * - * @param swallows arguments + * This function exists unimplemented to absorb incorrect template instantiations. * * @tparam typename swallows the template parameter * + * @param '' swallows arguments + * * @return ignore */ template @@ -161,7 +161,7 @@ namespace util { public: /** - * @brief Calls the collection of functions with the given arguments. + * Calls the collection of functions with the given arguments. * * @param args The arguments to be used to call * @@ -181,13 +181,13 @@ namespace util { }; /** - * @brief SFINAE test struct to see if a function is callable with the provided arguments. + * SFINAE test struct to see if a function is callable with the provided arguments. * - * @tparam Function the function to be tested - * @tparam Shared the number of parameters (from 0) to use in the call - * @tparam Start the index of the first argument to pass to the function - * @tparam End the index of the element after the last argument to pass to the function - * @tparam Arguments the types of the arguments passed into the function + * @tparam Function The function to be tested + * @tparam Shared The number of parameters (from 0) to use in the call + * @tparam Start The index of the first argument to pass to the function + * @tparam End The index of the element after the last argument to pass to the function + * @tparam Arguments The types of the arguments passed into the function */ template struct is_callable { @@ -196,8 +196,8 @@ namespace util { using no = std::false_type; template - static auto test(int) - -> decltype(apply_function_fusion_call(std::declval()), yes()); + static auto test(int) -> decltype(apply_function_fusion_call(std::declval()), + yes()); template static no test(...); @@ -218,31 +218,28 @@ namespace util { struct FunctionFusion; /** - * @brief Splits arguments amongst a series of functions. - * @details This is the main loop for the function fusion metafunction. - * It will do a greedy matching of arguments with function overloads - * to try and make all functions callable with the given arguments. - * It will share the first arguments (up to but not including Shared) - * across all functions. + * Splits arguments amongst a series of functions. + * + * This is the main loop for the function fusion metafunction. + * It will do a greedy matching of arguments with function overloads to try and make all functions callable with the + * given arguments. + * It will share the first arguments (up to but not including Shared) across all functions. * - * These functions are provided with a wrapper FunctionWrapper which is - * a template that takes their type and uses its ::call function to call - * the original functions function. - * This allows fusion of functions without knowing the name of the function - * that is being fused. + * These functions are provided with a wrapper FunctionWrapper which is a template that takes their type and uses + * its ::call function to call the original functions function. + * This allows fusion of functions without knowing the name of the function that is being fused. * - * @tparam CurrentFunction the current function we are inspecting - * @tparam Functions the remaining functions we are going to call - * @tparam Arguments the arguments we are calling the function with - * @tparam FunctionWrapper the template that is used to wrap the Function objects to be called - * @tparam WrapperArgs template types to be used on the FunctionWrapper in addition to the Fuctions type. - * May be empty. - * @tparam Shared the number of parameters (from 0) to use in all of the calls - * @tparam Start the current attempted index of the first argument to pass to the function - * @tparam End the current attempted index of the element after the last argument to pass to the - * function - * @tparam ProcessedFunctions the list of functions that have had found argument sets - * @tparam ArgumentRanges the respective argument ranges for the processed functions + * @tparam CurrentFunction The current function we are inspecting + * @tparam Functions The remaining functions we are going to call + * @tparam Arguments The arguments we are calling the function with + * @tparam FunctionWrapper The template that is used to wrap the Function objects to be called + * @tparam WrapperArgs Template types to be used on the FunctionWrapper in addition to the Fuctions type. + * May be empty. + * @tparam Shared The number of parameters (from 0) to use in all of the calls + * @tparam Start The current attempted index of the first argument to pass + * @tparam End The current attempted index of the element after the last argument to pass + * @tparam ProcessedFunctions The list of functions that have had found argument sets + * @tparam ArgumentRanges The respective argument ranges for the processed functions */ template >>> {}; /** - * @brief The termination case for the FunctionFusion metafunction. + * The termination case for the FunctionFusion metafunction. * - * @details This is the termination case for the FunctionFusion metafunction. - * if it reaches this point with a successful combination it will - * extend from the FunctionFusionCaller, otherwise it will be a - * false_type to indicate its failure. + * This is the termination case for the FunctionFusion metafunction. + * If it reaches this point with a successful combination it will extend from the FunctionFusionCaller. + * Otherwise it will be a false_type to indicate its failure. */ template diff --git a/src/util/GeneratedCallback.hpp b/src/util/GeneratedCallback.hpp index ef2bb58ab..5a5040300 100644 --- a/src/util/GeneratedCallback.hpp +++ b/src/util/GeneratedCallback.hpp @@ -33,7 +33,7 @@ namespace NUClear { namespace util { /** - * @brief Generated callback for a task + * Generated callback for a task */ struct GeneratedCallback { GeneratedCallback() = default; @@ -42,17 +42,17 @@ namespace util { const ThreadPoolDescriptor& pool, threading::ReactionTask::TaskFunction callback) : priority(priority), group(group), pool(pool), callback(std::move(callback)) {} - /// @brief the priority this task should run with + /// The priority this task should run with int priority{0}; - /// @brief the descriptor for the group the task should run in + /// The descriptor for the group the task should run in GroupDescriptor group{0, std::numeric_limits::max()}; - /// @brief the descriptor the thread pool and task queue that the should run in + /// The descriptor the thread pool and task queue that the should run in ThreadPoolDescriptor pool{util::ThreadPoolDescriptor::DEFAULT_THREAD_POOL_ID, 0, true}; - /// @brief the function that should be executed in order to run the task + /// The function that should be executed in order to run the task threading::ReactionTask::TaskFunction callback{}; /** - * @return true if this represents a valid callback object + * @return `true` if this represents a valid callback object */ operator bool() const { return bool(callback); diff --git a/src/util/GroupDescriptor.hpp b/src/util/GroupDescriptor.hpp index 3561b94ea..bc3ca8ded 100644 --- a/src/util/GroupDescriptor.hpp +++ b/src/util/GroupDescriptor.hpp @@ -34,17 +34,17 @@ namespace NUClear { namespace util { /** - * @brief A description of a group + * A description of a group. */ struct GroupDescriptor { - /// @brief a unique identifier for this pool + /// A unique identifier for this group NUClear::id_t group_id{0}; - /// @brief the maximum number of threads that can run concurrently in this group + /// The maximum number of threads that can run concurrently in this group size_t thread_count{std::numeric_limits::max()}; /** - * @brief Return the next unique ID for a new group + * @return The next unique ID for a new group */ static NUClear::id_t get_unique_group_id() noexcept { // Make group 0 the default group diff --git a/src/util/MetaProgramming.hpp b/src/util/MetaProgramming.hpp index 6affd2eef..da81cfdd6 100644 --- a/src/util/MetaProgramming.hpp +++ b/src/util/MetaProgramming.hpp @@ -33,7 +33,7 @@ namespace NUClear { /** - * @brief Becomes true_type if all of the predicates pass, and false_type if any fail. + * Becomes true_type if all of the predicates pass, and false_type if any fail. * * @tparam T the set of condtions to check. * @@ -45,7 +45,7 @@ template struct All : std::conditional_t, std::false_type> {}; /** - * @brief Becomes true_type if any of the predicates pass, and false_type they all fail. + * Becomes true_type if any of the predicates pass, and false_type they all fail. * * @tparam T the set of condtions to check. * @@ -57,7 +57,7 @@ template struct Any : std::conditional_t> {}; /** - * @brief Becomes the inverse to the boolean type passed. + * Becomes the inverse to the boolean type passed. * * @tparam Condition the type to attempt to inverse. * diff --git a/src/util/Sequence.hpp b/src/util/Sequence.hpp index 070e1948d..35071e877 100644 --- a/src/util/Sequence.hpp +++ b/src/util/Sequence.hpp @@ -27,7 +27,7 @@ namespace NUClear { namespace util { /** - * @brief This class is used to hold a sequence of integers as a variadic pack + * This class is used to hold a sequence of integers as a variadic pack. * * @tparam S the variadic pack containing the sequence */ @@ -37,7 +37,7 @@ namespace util { }; /** - * @brief Generate a sequence of numbers between a start and an end, this is the entry case + * Generate a sequence of numbers between a start and an end, this is the entry case. */ template > struct GenSequence; @@ -62,16 +62,14 @@ namespace util { }; /** - * @brief Holds a generated integer sequence of numbers as a variadic pack. + * Holds a generated integer sequence of numbers as a variadic pack. * - * @details - * This class is used to generate a variadic template pack which contains all of the integers from Start to End - * (non inclusive). - * This can then be used in other templates or tempalate expansions as needed (for instance it is useful for + * This class is used to generate a variadic template pack which contains all of the integers from [Start->End). + * This can then be used in other templates or template expansions as needed (for instance it is useful for * expanding tuples). * - * @tparam Start the number to start counting from - * @tparam End the number to finish counting at (non inclusive) + * @tparam Start The number to start counting from + * @tparam End The number to finish counting at (non inclusive) */ template using GenerateSequence = typename GenSequence::type; diff --git a/src/util/ThreadPoolDescriptor.hpp b/src/util/ThreadPoolDescriptor.hpp index 1c868a479..5d1cd38fa 100644 --- a/src/util/ThreadPoolDescriptor.hpp +++ b/src/util/ThreadPoolDescriptor.hpp @@ -33,7 +33,7 @@ namespace NUClear { namespace util { /** - * @brief A description of a thread pool + * A description of a thread pool */ struct ThreadPoolDescriptor { ThreadPoolDescriptor() = default; @@ -44,21 +44,21 @@ namespace util { return ThreadPoolDescriptor{NUClear::id_t(-1), size_t(-1), false}; } - /// @brief a unique identifier for this pool + /// A unique identifier for this pool NUClear::id_t pool_id{ThreadPoolDescriptor::DEFAULT_THREAD_POOL_ID}; - /// @brief the number of threads this thread pool will use + /// The number of threads this thread pool will use size_t thread_count{0}; - /// @brief if these threads count towards system idle + /// If these threads count towards system idle bool counts_for_idle{true}; - /// @brief the ID of the main thread pool (not to be confused with the ID of the main thread) + /// The ID of the main thread pool (not to be confused with the ID of the main thread) static const NUClear::id_t MAIN_THREAD_POOL_ID; - /// @brief the ID of the default thread pool + /// The ID of the default thread pool static const NUClear::id_t DEFAULT_THREAD_POOL_ID; /** - * @brief Return the next unique ID for a new thread pool + * @return The next unique ID for a new thread pool */ static NUClear::id_t get_unique_pool_id() noexcept { static std::atomic source{2}; diff --git a/src/util/TypeList.hpp b/src/util/TypeList.hpp index c1f59246a..8473c551e 100644 --- a/src/util/TypeList.hpp +++ b/src/util/TypeList.hpp @@ -33,7 +33,7 @@ namespace util { template class TypeList { public: - /// @brief Deleted rule-of-five as this class is a static class. + /// Deleted rule-of-five as this class is a static class TypeList() = delete; virtual ~TypeList() = delete; TypeList(const TypeList& /*other*/) = delete; @@ -42,12 +42,12 @@ namespace util { TypeList operator=(TypeList&& /*other*/) noexcept = delete; private: - /// @brief the data variable where the data is stored for this map key. + /// The data variable where the data is stored for this map key static std::vector data; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) public: /** - * @brief Gets the list that is stored in this type location + * Gets the list that is stored in this type location. * * @return A reference to the vector stored in this location */ diff --git a/src/util/TypeMap.hpp b/src/util/TypeMap.hpp index 3ad43c23c..e63ff9df5 100644 --- a/src/util/TypeMap.hpp +++ b/src/util/TypeMap.hpp @@ -31,15 +31,15 @@ namespace NUClear { namespace util { /** - * @brief The simplest and fastest map format, It stores a single value and returns it when requested later. + * The simplest and fastest map format, It stores a single value and returns it when requested later. * - * @details - * This map stores a single value in it's store when the set function is called, and when get is later called - * this object will be returned. This map is accessed by template parameters, because of this when the compiler - * compiles this map. It can resolve each of the map accesses into a direct function call. This allows the map to - * be looked up at compile time and optimized to very efficient code. There are several variations of the Map - * provided through the MapType parameter the operation of each of these is described in their individual - * documentation. + * This map stores a single value in it's store when the set function is called, and when get is later called this + * object will be returned. + * This map is accessed by template parameters, because of this when the compiler compiles this map. + * It can resolve each of the map accesses into a direct function call. + * This allows the map to be looked up at compile time and optimized to very efficient code. + * There are several variations of the Map provided through the MapType parameter the operation of each of these is + * described in their individual documentation. * * @attention * Note that because this is an entirely static class, if two maps with the same MapID are used, they access the @@ -48,7 +48,7 @@ namespace util { template class TypeMap { public: - /// @brief Deleted rule-of-five as this class is a static class. + /// Deleted rule-of-five as this class is a static class. TypeMap() = delete; virtual ~TypeMap() = delete; TypeMap(const TypeMap& /*other*/) = delete; @@ -57,15 +57,15 @@ namespace util { TypeMap operator=(TypeMap&& /*other*/) noexcept = delete; private: - /// @brief the data variable where the data is stored for this map key. + /// The data variable where the data is stored for this map key. static std::shared_ptr data; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) static std::mutex mutex; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) public: /** - * @brief Stores the passed value in this map. + * Stores the passed value in this map. * - * @param d a pointer to the data to be stored (the map takes ownership) + * @param d A pointer to the data to be stored (the map takes ownership) */ static void set(std::shared_ptr d) { @@ -78,9 +78,9 @@ namespace util { } /** - * @brief Gets the value that was previously stored. + * Gets the value that was previously stored. * - * @return a shared_ptr to the data that was previously stored + * @return A shared_ptr to the data that was previously stored */ static std::shared_ptr get() { diff --git a/src/util/apply.hpp b/src/util/apply.hpp index b62fb3446..1b7d8ac1a 100644 --- a/src/util/apply.hpp +++ b/src/util/apply.hpp @@ -33,16 +33,16 @@ namespace NUClear { namespace util { /** - * @brief Dereferences and uses the values from the tuple as the arguments for the function call. + * Dereferences and uses the values from the tuple as the arguments for the function call. * - * @details - * This function uses the values which are stored in the tuple and dereferences them as parameters in - * the callback function. It does this using the generated sequence of integers for this tuple. These - * values are then used to extract the function parameters in order. - * - * @param s the Sequence object which is passed in holding the int template pack + * This function uses the values which are stored in the tuple and dereferences them as parameters in + * the callback function. + * It does this using the generated sequence of integers for this tuple. + * These values are then used to extract the function parameters in order. * * @tparam S the integer pack giving the ordinal position of the tuple value to get + * + * @param s the Sequence object which is passed in holding the int template pack */ template void apply(Function&& function, const std::tuple&& args, const Sequence& /*s*/) { diff --git a/src/util/demangle.cpp b/src/util/demangle.cpp index 1e9dbd235..01ea83ecf 100644 --- a/src/util/demangle.cpp +++ b/src/util/demangle.cpp @@ -104,11 +104,11 @@ namespace NUClear { namespace util { /** - * @brief Demangles the passed symbol to a string, or returns it if it cannot demangle it + * Demangles the passed symbol to a string, or returns it if it cannot demangle it. * * @param symbol the symbol to demangle * - * @return the demangled symbol, or the original string if it could not be demangeld + * @return the demangled symbol, or the original string if it could not be demangled */ std::string demangle(const char* symbol) { diff --git a/src/util/main_thread_id.hpp b/src/util/main_thread_id.hpp index beb541035..87a0046b5 100644 --- a/src/util/main_thread_id.hpp +++ b/src/util/main_thread_id.hpp @@ -29,10 +29,10 @@ namespace NUClear { namespace util { /** - * @brief The thread id of the main execution thread for this process + * The thread id of the main execution thread for this process. - * @details In order to get the main threads id, we set it as a global static variable. - * This should result in the static setup code executing on startup (in the main thread). + * In order to get the main threads id, we set it as a global static variable. + * This should result in the static setup code executing on startup (in the main thread). */ extern const std::thread::id main_thread_id; diff --git a/src/util/network/get_interfaces.hpp b/src/util/network/get_interfaces.hpp index 6287810ff..e03f42b43 100644 --- a/src/util/network/get_interfaces.hpp +++ b/src/util/network/get_interfaces.hpp @@ -33,37 +33,37 @@ namespace util { namespace network { /** - * @brief A structure that contains information about a network interface + * A structure that contains information about a network interface. */ struct Interface { - /// @brief The name of the interface + /// The name of the interface std::string name{}; - /// @brief The address that is bound to the interface + /// The address that is bound to the interface sock_t ip{}; - /// @brief The netmask of the interface + /// The netmask of the interface sock_t netmask{}; - /// @brief The broadcast address of the interface or point to point address + /// The broadcast address of the interface or point to point address sock_t broadcast{}; struct Flags { - /// @brief True if the interface is a broadcast interface + /// True if the interface is a broadcast interface bool broadcast{false}; - /// @brief True if the interface is a loopback interface + /// True if the interface is a loopback interface bool loopback{false}; - /// @brief True if the interface is a point to point interface + /// True if the interface is a point to point interface bool pointtopoint{false}; - /// @brief True if the interface is a multicast interface + /// True if the interface is a multicast interface bool multicast{false}; }; - /// @brief The flags that are set on the interface + /// The flags that are set on the interface Flags flags; }; /** - * @brief Gets a list of all the network interfaces on the system with the addresses they are bound to + * Gets a list of all the network interfaces on the system with the addresses they are bound to. * - * @return a list of all the interfaces on the system + * @return A list of all the interfaces on the system */ std::vector get_interfaces(); diff --git a/src/util/network/if_number_from_address.hpp b/src/util/network/if_number_from_address.hpp index c088e342f..d1b3fc4b2 100644 --- a/src/util/network/if_number_from_address.hpp +++ b/src/util/network/if_number_from_address.hpp @@ -33,11 +33,11 @@ namespace util { namespace network { /** - * @brief Gets the index of the interface that the given ipv6 address is on + * Gets the index of the interface that the given ipv6 address is on. * - * @param ipv6 the ipv6 address to check + * @param ipv6 The ipv6 address to check * - * @return int the index of the interface that the address is on or 0 if the ipv6 address is the any address + * @return The index of the interface that the address is on or 0 if the ipv6 address is the any address */ unsigned int if_number_from_address(const sockaddr_in6& ipv6); diff --git a/src/util/network/resolve.hpp b/src/util/network/resolve.hpp index 1f2c0ce0c..388517eb8 100644 --- a/src/util/network/resolve.hpp +++ b/src/util/network/resolve.hpp @@ -32,16 +32,15 @@ namespace util { namespace network { /** - * @brief Resolves a hostname and port into a socket address + * Resolves a hostname and port into a socket address. * - * @details - * This function will resolve a hostname and port into a socket address. - * It will return a socket address that can be used to connect to the specified host and port. + * This function will resolve a hostname and port into a socket address. + * It will return a socket address that can be used to connect to the specified host and port. * - * @param address the hostname or IP address to resolve - * @param port the port to connect to + * @param address The hostname or IP address to resolve + * @param port The port to connect to * - * @return a socket address that can be used to connect to the specified host and port + * @return A socket address that can be used to connect to the specified host and port */ sock_t resolve(const std::string& address, const uint16_t& port); diff --git a/src/util/platform.hpp b/src/util/platform.hpp index 6cc6d9abd..5cc57dcec 100644 --- a/src/util/platform.hpp +++ b/src/util/platform.hpp @@ -161,7 +161,7 @@ int recvmsg(fd_t fd, msghdr* msg, int flags); int sendmsg(fd_t fd, msghdr* msg, int flags); /** - * @brief This struct is used to setup WSA on windows in a single place so we don't have to worry about it + * This struct is used to setup WSA on windows in a single place so we don't have to worry about it. * * A single instance of this struct will be created statically at startup which will ensure that WSA is setup for the * lifetime of the program and torn down as it exits. diff --git a/src/util/serialise/xxhash.cpp b/src/util/serialise/xxhash.cpp index 9aefbc949..98253177f 100644 --- a/src/util/serialise/xxhash.cpp +++ b/src/util/serialise/xxhash.cpp @@ -48,7 +48,7 @@ namespace util { } /** - * @brief Reads a 32-bit integer from a character array in either little-endian or big-endian byte order. + * Reads a 32-bit integer from a character array in either little-endian or big-endian byte order. * * @param v The character array to read from. * @@ -62,7 +62,7 @@ namespace util { } /** - * @brief Reads a 64-bit integer from a character array in either little-endian or big-endian byte order. + * Reads a 64-bit integer from a character array in either little-endian or big-endian byte order. * * @param v The character array to read from. * @@ -80,7 +80,8 @@ namespace util { } /** - * @brief Rotates the bits of an integral type to the left by a given amount. + * Rotates the bits of an integral type to the left by a given amount. + * * @note This function is only enabled for integral types. * * @tparam T The integral type to rotate. diff --git a/src/util/serialise/xxhash.hpp b/src/util/serialise/xxhash.hpp index b2ab085a3..fc065c6a7 100644 --- a/src/util/serialise/xxhash.hpp +++ b/src/util/serialise/xxhash.hpp @@ -31,7 +31,7 @@ namespace util { namespace serialise { /** - * @brief Calculates the 32-bit xxHash of the input data. + * Calculates the 32-bit xxHash of the input data. * * This function calculates the 32-bit xxHash of the input data using the specified seed value. * @@ -44,13 +44,13 @@ namespace util { uint32_t xxhash32(const void* input, const size_t& length, const uint32_t& seed = 0); /** - * @brief Calculates the 64-bit xxHash of the input data. + * Calculates the 64-bit xxHash of the input data. * * This function calculates the 64-bit xxHash of the input data using the specified seed value. * - * @param input Pointer to the input data. + * @param input Pointer to the input data. * @param length Length of the input data in bytes. - * @param seed Seed value to use for the hash calculation. Default value is 0. + * @param seed Seed value to use for the hash calculation. Default value is 0. * * @return The 64-bit xxHash of the input data. */ diff --git a/src/util/unpack.hpp b/src/util/unpack.hpp index 182079738..3cb9675ca 100644 --- a/src/util/unpack.hpp +++ b/src/util/unpack.hpp @@ -27,25 +27,27 @@ namespace NUClear { namespace util { /** - * @brief Executes a series of function calls from a variadic template pack. + * Executes a series of function calls from a variadic template pack. * - * @details - * This function is to be used as a helper to expand a variadic template pack into a series of function calls. - * As the variadic function pack can only be expanded in the situation where they are comma separated (and the - * comma is a syntactic separator not the comma operator) the only place this can expand is within a function call, - * or an initializer list (which can only accept a single type). - * This function serves that purpose by allowing a series of function calls to be expanded as its parameters. This - * will execute each of them without having to recursivly evaluate the pack. e.g. - * @code unpack(function(T)...); @endcode + * This function can be replaced with c++17 fold expressions. * - * In the case where the return type of the functions is void, then using the comma operator will allow the - * functions - * to be run because it changes the return type of the expansion (function(T), 0) to int rather then void e.g. - * @code unpack((function(T), 0)...); @endcode + * This function is to be used as a helper to expand a variadic template pack into a series of function calls. + * As the variadic function pack can only be expanded in the situation where they are comma separated (and the + * comma is a syntactic separator not the comma operator) the only place this can expand is within a function call, + * or an initializer list (which can only accept a single type). + * This function serves that purpose by allowing a series of function calls to be expanded as its parameters. This + * will execute each of them without having to recursively evaluate the pack. e.g. * - * @param t The resulting objects from executing the functions, these are ignored + * @code unpack(function(T)...); @endcode + * + * In the case where the return type of the functions is void, then using the comma operator will allow the + * functions to be run because it changes the return type of the expansion (function(T), 0) to int rather then void + * + * e.g. @code unpack((function(T), 0)...); @endcode * * @tparam Ts the types of the resulting objects from executing the functions, these are ignored + * + * @param t The resulting objects from executing the functions, these are ignored */ template void unpack(Ts... /*t*/) { diff --git a/tests/test_util/TestBase.hpp b/tests/test_util/TestBase.hpp index e9e368cc4..1cdf14b0c 100644 --- a/tests/test_util/TestBase.hpp +++ b/tests/test_util/TestBase.hpp @@ -36,8 +36,10 @@ template class TestBase : public NUClear::Reactor { public: /** - * @brief Struct to use to emit each step of the test, by doing each step in a separate reaction with low priority, - * it will ensure that everything has finished changing before the next step is run + * Struct to use to emit each step of the test. + * + * By doing each step in a separate reaction with low priority it will ensure that everything has finished changing + * before the next step is run * * @tparam i the number of the step */ @@ -45,7 +47,7 @@ class TestBase : public NUClear::Reactor { struct Step {}; /** - * @brief Struct to handle shutting down the powerplant when the system is idle (i.e. the unit test(s) are finished) + * Struct to handle shutting down the PowerPlant when the system is idle (i.e. the unit test(s) are finished) */ struct ShutdownOnIdle {}; diff --git a/tests/tests/api/ReactionHandle.cpp b/tests/tests/api/ReactionHandle.cpp index fe474cd5d..9f64e345a 100644 --- a/tests/tests/api/ReactionHandle.cpp +++ b/tests/tests/api/ReactionHandle.cpp @@ -28,7 +28,7 @@ // Anonymous namespace to keep everything file local namespace { -/// @brief Events that occur during the test +/// Events that occur during the test std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) struct Message { diff --git a/tests/tests/api/ReactionStatistics.cpp b/tests/tests/api/ReactionStatistics.cpp index 35e0d2138..f852f1a00 100644 --- a/tests/tests/api/ReactionStatistics.cpp +++ b/tests/tests/api/ReactionStatistics.cpp @@ -28,7 +28,7 @@ // This namespace is named to make things consistent with the reaction statistics test namespace stats_test { -/// @brief Events that occur during the test +/// Events that occur during the test std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) template diff --git a/tests/tests/dsl/Always.cpp b/tests/tests/dsl/Always.cpp index dc0c668de..0b78407ca 100644 --- a/tests/tests/dsl/Always.cpp +++ b/tests/tests/dsl/Always.cpp @@ -27,7 +27,7 @@ namespace { -/// @brief Events that occur during the test +/// Events that occur during the test std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) struct SimpleMessage {}; diff --git a/tests/tests/dsl/ArgumentFission.cpp b/tests/tests/dsl/ArgumentFission.cpp index 8f8ef98d1..bb09557a7 100644 --- a/tests/tests/dsl/ArgumentFission.cpp +++ b/tests/tests/dsl/ArgumentFission.cpp @@ -28,7 +28,7 @@ namespace { -/// @brief Events that occur during the test +/// Events that occur during the test std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) struct BindExtensionTest1 { diff --git a/tests/tests/dsl/BlockNoData.cpp b/tests/tests/dsl/BlockNoData.cpp index 005afb40e..3f01537ba 100644 --- a/tests/tests/dsl/BlockNoData.cpp +++ b/tests/tests/dsl/BlockNoData.cpp @@ -27,7 +27,7 @@ namespace { -/// @brief Events that occur during the test +/// Events that occur during the test std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) struct MessageA {}; diff --git a/tests/tests/dsl/Buffer.cpp b/tests/tests/dsl/Buffer.cpp index 30b7a9658..8e323c856 100644 --- a/tests/tests/dsl/Buffer.cpp +++ b/tests/tests/dsl/Buffer.cpp @@ -27,7 +27,7 @@ namespace { -/// @brief Events that occur during the test +/// Events that occur during the test std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) struct Message { diff --git a/tests/tests/dsl/CustomGet.cpp b/tests/tests/dsl/CustomGet.cpp index b785f0852..a9e2323d4 100644 --- a/tests/tests/dsl/CustomGet.cpp +++ b/tests/tests/dsl/CustomGet.cpp @@ -27,7 +27,7 @@ namespace { -/// @brief Events that occur during the test +/// Events that occur during the test std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) struct CustomGet : public NUClear::dsl::operation::TypeBind { diff --git a/tests/tests/dsl/DSLOrdering.cpp b/tests/tests/dsl/DSLOrdering.cpp index 8629632d5..17237cdd1 100644 --- a/tests/tests/dsl/DSLOrdering.cpp +++ b/tests/tests/dsl/DSLOrdering.cpp @@ -27,7 +27,7 @@ namespace { -/// @brief Events that occur during the test +/// Events that occur during the test std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) template diff --git a/tests/tests/dsl/DSLProxy.cpp b/tests/tests/dsl/DSLProxy.cpp index 4677f474c..2987d2630 100644 --- a/tests/tests/dsl/DSLProxy.cpp +++ b/tests/tests/dsl/DSLProxy.cpp @@ -47,7 +47,7 @@ namespace dsl { namespace { -/// @brief Events that occur during the test +/// Events that occur during the test std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) class TestReactor : public test_util::TestBase { diff --git a/tests/tests/dsl/FlagMessage.cpp b/tests/tests/dsl/FlagMessage.cpp index 5fa24868e..df301d2c7 100644 --- a/tests/tests/dsl/FlagMessage.cpp +++ b/tests/tests/dsl/FlagMessage.cpp @@ -27,7 +27,7 @@ namespace { -/// @brief Events that occur during the test +/// Events that occur during the test std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) struct SimpleMessage {}; diff --git a/tests/tests/dsl/IO.cpp b/tests/tests/dsl/IO.cpp index 871e3064f..7c9d57495 100644 --- a/tests/tests/dsl/IO.cpp +++ b/tests/tests/dsl/IO.cpp @@ -34,9 +34,9 @@ namespace { -/// @brief Events that occur during the test reading +/// Events that occur during the test reading std::vector read_events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) -/// @brief Events that occur during the test writing +/// Events that occur during the test writing std::vector write_events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) class TestReactor : public test_util::TestBase { diff --git a/tests/tests/dsl/Idle.cpp b/tests/tests/dsl/Idle.cpp index f75974e9e..e2a86a2b2 100644 --- a/tests/tests/dsl/Idle.cpp +++ b/tests/tests/dsl/Idle.cpp @@ -27,7 +27,7 @@ namespace { -/// @brief A vector of events that have happened +/// A vector of events that have happened std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) struct SimpleMessage { diff --git a/tests/tests/dsl/IdleSync.cpp b/tests/tests/dsl/IdleSync.cpp index f6008b661..4a5c860ad 100644 --- a/tests/tests/dsl/IdleSync.cpp +++ b/tests/tests/dsl/IdleSync.cpp @@ -27,7 +27,7 @@ namespace { -/// @brief A vector of events that have happened +/// A vector of events that have happened std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) class TestReactor : public test_util::TestBase { diff --git a/tests/tests/dsl/Last.cpp b/tests/tests/dsl/Last.cpp index 6a214913d..2568ce472 100644 --- a/tests/tests/dsl/Last.cpp +++ b/tests/tests/dsl/Last.cpp @@ -27,7 +27,7 @@ namespace { -/// @brief Events that occur during the test +/// Events that occur during the test std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) struct TestMessage { diff --git a/tests/tests/dsl/MainThread.cpp b/tests/tests/dsl/MainThread.cpp index 87ac4e1be..4a8f3d0af 100644 --- a/tests/tests/dsl/MainThread.cpp +++ b/tests/tests/dsl/MainThread.cpp @@ -27,7 +27,7 @@ namespace { -/// @brief Events that occur during the test +/// Events that occur during the test std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) struct MessageA {}; diff --git a/tests/tests/dsl/MissingArguments.cpp b/tests/tests/dsl/MissingArguments.cpp index 9d6c43608..3986dd848 100644 --- a/tests/tests/dsl/MissingArguments.cpp +++ b/tests/tests/dsl/MissingArguments.cpp @@ -27,7 +27,7 @@ namespace { -/// @brief Events that occur during the test +/// Events that occur during the test std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) template diff --git a/tests/tests/dsl/Optional.cpp b/tests/tests/dsl/Optional.cpp index ac2000b45..52839f653 100644 --- a/tests/tests/dsl/Optional.cpp +++ b/tests/tests/dsl/Optional.cpp @@ -27,7 +27,7 @@ namespace { -/// @brief Events that occur during the test +/// Events that occur during the test std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) struct MessageA {}; diff --git a/tests/tests/dsl/Priority.cpp b/tests/tests/dsl/Priority.cpp index 5343f49e3..4b760bc76 100644 --- a/tests/tests/dsl/Priority.cpp +++ b/tests/tests/dsl/Priority.cpp @@ -28,7 +28,7 @@ namespace { -/// @brief Events that occur during the test +/// Events that occur during the test std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) template diff --git a/tests/tests/dsl/RawFunction.cpp b/tests/tests/dsl/RawFunction.cpp index e27a4ec1c..4ab7e6365 100644 --- a/tests/tests/dsl/RawFunction.cpp +++ b/tests/tests/dsl/RawFunction.cpp @@ -27,7 +27,7 @@ namespace { -/// @brief Events that occur during the test +/// Events that occur during the test std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) struct Message { @@ -41,10 +41,11 @@ struct Data { }; /** - * @brief Test a raw function that takes no arguments and has a return type. + * Test a raw function that takes no arguments and has a return type. + * * The return type should be ignored and this function should run without issue. * - * @return double + * @return A value */ double raw_function_test_no_args() { events.push_back("Raw function no args"); @@ -52,28 +53,28 @@ double raw_function_test_no_args() { } /** - * @brief Raw function that takes one argument (the left side of the trigger) + * Raw function that takes one argument (the left side of the trigger) * - * @param msg the message + * @param msg The message */ void raw_function_test_left_arg(const Message& msg) { events.push_back("Raw function left arg: " + msg.data); } /** - * @brief Raw function that takes one argument (the right side of the trigger) + * Raw function that takes one argument (the right side of the trigger) * - * @param data the data + * @param data The data */ void raw_function_test_right_arg(const Data& data) { events.push_back("Raw function right arg: " + data.data); } /** - * @brief Raw function that takes both arguments + * Raw function that takes both arguments * - * @param msg the message - * @param data the data + * @param msg The message + * @param data The data */ void raw_function_test_both_args(const Message& msg, const Data& data) { events.push_back("Raw function both args: " + msg.data + " " + data.data); diff --git a/tests/tests/dsl/Shutdown.cpp b/tests/tests/dsl/Shutdown.cpp index c3a64e800..8535ecfef 100644 --- a/tests/tests/dsl/Shutdown.cpp +++ b/tests/tests/dsl/Shutdown.cpp @@ -28,7 +28,7 @@ // Anonymous namespace to keep everything file local namespace { -/// @brief Events that occur during the test +/// Events that occur during the test std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) class TestReactor : public test_util::TestBase { diff --git a/tests/tests/dsl/Startup.cpp b/tests/tests/dsl/Startup.cpp index 9d4b66690..1b8eed64f 100644 --- a/tests/tests/dsl/Startup.cpp +++ b/tests/tests/dsl/Startup.cpp @@ -27,7 +27,7 @@ namespace { -/// @brief Events that occur during the test +/// Events that occur during the test std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) struct SimpleMessage { diff --git a/tests/tests/dsl/Sync.cpp b/tests/tests/dsl/Sync.cpp index dde12865b..e1851b3b1 100644 --- a/tests/tests/dsl/Sync.cpp +++ b/tests/tests/dsl/Sync.cpp @@ -27,7 +27,7 @@ namespace { -/// @brief Events that occur during the test +/// Events that occur during the test std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) template diff --git a/tests/tests/dsl/SyncOrder.cpp b/tests/tests/dsl/SyncOrder.cpp index f17cec16f..db744e15e 100644 --- a/tests/tests/dsl/SyncOrder.cpp +++ b/tests/tests/dsl/SyncOrder.cpp @@ -39,7 +39,7 @@ struct Message { struct ShutdownOnIdle {}; -/// @brief Events that occur during the test +/// Events that occur during the test std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) class TestReactor : public test_util::TestBase { diff --git a/tests/tests/dsl/TCP.cpp b/tests/tests/dsl/TCP.cpp index 99eae482a..584eff92a 100644 --- a/tests/tests/dsl/TCP.cpp +++ b/tests/tests/dsl/TCP.cpp @@ -28,7 +28,7 @@ namespace { -/// @brief Events that occur during the test +/// Events that occur during the test std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) enum TestPorts { diff --git a/tests/tests/dsl/Transient.cpp b/tests/tests/dsl/Transient.cpp index 069d6684f..89a417e8d 100644 --- a/tests/tests/dsl/Transient.cpp +++ b/tests/tests/dsl/Transient.cpp @@ -54,7 +54,7 @@ namespace dsl { namespace { -/// @brief Events that occur during the test +/// Events that occur during the test std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) struct TransientGetter : public NUClear::dsl::operation::TypeBind { diff --git a/tests/tests/dsl/Trigger.cpp b/tests/tests/dsl/Trigger.cpp index be7e79530..a8ee8dc42 100644 --- a/tests/tests/dsl/Trigger.cpp +++ b/tests/tests/dsl/Trigger.cpp @@ -27,7 +27,7 @@ namespace { -/// @brief A vector of events that have happened +/// A vector of events that have happened std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) struct SimpleMessage { diff --git a/tests/tests/dsl/UDP.cpp b/tests/tests/dsl/UDP.cpp index 035738a51..b77163cd8 100644 --- a/tests/tests/dsl/UDP.cpp +++ b/tests/tests/dsl/UDP.cpp @@ -28,7 +28,7 @@ namespace { -/// @brief Events that occur during the test +/// Events that occur during the test std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) enum TestPorts { diff --git a/tests/tests/dsl/Watchdog.cpp b/tests/tests/dsl/Watchdog.cpp index f99d9c133..6669bf8a6 100644 --- a/tests/tests/dsl/Watchdog.cpp +++ b/tests/tests/dsl/Watchdog.cpp @@ -29,7 +29,7 @@ namespace { -/// @brief Events that occur during the test +/// Events that occur during the test std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) template diff --git a/tests/tests/dsl/With.cpp b/tests/tests/dsl/With.cpp index 7646ae272..07fab6b72 100644 --- a/tests/tests/dsl/With.cpp +++ b/tests/tests/dsl/With.cpp @@ -27,7 +27,7 @@ namespace { -/// @brief Events that occur during the test +/// Events that occur during the test std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) struct Message { diff --git a/tests/tests/dsl/emit/Delay.cpp b/tests/tests/dsl/emit/Delay.cpp index 1b568b201..a20e1aade 100644 --- a/tests/tests/dsl/emit/Delay.cpp +++ b/tests/tests/dsl/emit/Delay.cpp @@ -31,10 +31,10 @@ namespace { using TimeUnit = test_util::TimeUnit; -/// @brief Events that occur during the test +/// Events that occur during the test std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) -/// @brief Perform this many different time points for the test +/// Perform this many different time points for the test constexpr int test_loops = 5; struct DelayedMessage { diff --git a/tests/tests/dsl/emit/EmitFusion.cpp b/tests/tests/dsl/emit/EmitFusion.cpp index 8b3e7a21d..610a5343a 100644 --- a/tests/tests/dsl/emit/EmitFusion.cpp +++ b/tests/tests/dsl/emit/EmitFusion.cpp @@ -29,7 +29,7 @@ // Anonymous namespace to keep everything file local namespace { -/// @brief Events that occur during the test +/// Events that occur during the test std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) template diff --git a/tests/tests/dsl/emit/Initialise.cpp b/tests/tests/dsl/emit/Initialise.cpp index 3308707b2..a0854c197 100644 --- a/tests/tests/dsl/emit/Initialise.cpp +++ b/tests/tests/dsl/emit/Initialise.cpp @@ -28,7 +28,7 @@ // Anonymous namespace to keep everything file local namespace { -/// @brief Events that occur during the test +/// Events that occur during the test std::vector events; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables) struct TestMessage {