fix: cleanup code documentation for issue #578

score/launch_manager/src/control_client/src/details/control_client_impl.hpp

@@ -34,18 +34,21 @@ namespace score::mw::lifecycle
 /// arrives later, so ControlClientImpl needs a storage where those active requests can wait for completion.
 struct ControlClientRequestInfo
 {
-    score::concurrency::InterruptiblePromise<void>
-        promise_;  ///< promise that should be fulfilled, i.e. set_value(), when answer from LCM is available.
-                   ///< SetState() and GetInitialMachineStateTransitionResult() use this type.
-    std::atomic_bool in_use_;  ///< information whether this slot in the array is used or not. We are using atomic flag
-                               ///< as only the code that reserves the slot will use synchronization primitive. There is
-                               ///< no reason to protect release code, thanks to the std::atomic_flag
-    bool initial_machine_state_transition_request_;  ///< is this a request that originated from
-                                                     ///< GetInitialMachineStateTransitionResult? Due to the design of
-                                                     ///< LCM, there is no place to cache those request on LCM side. As
-                                                     ///< there is no limit on how many times ControlClient instance can
-                                                     ///< call GetInitialMachineStateTransitionResult method, we will
-                                                     ///< cache them on ControlClientImpl side.
+    /// @brief Promise that should be fulfilled, i.e. set_value(), when answer from LCM is available.
+    /// SetState() and GetInitialMachineStateTransitionResult() use this type.
+    score::concurrency::InterruptiblePromise<void> promise_;
+
+    /// @brief Information whether this slot in the array is used or not. We are using atomic flag
+    /// as only the code that reserves the slot will use synchronization primitive. There is
+    /// no reason to protect release code, thanks to the std::atomic_flag.
+    std::atomic_bool in_use_;
+
+    /// @brief Is this a request that originated from GetInitialMachineStateTransitionResult? Due to the design of
+    /// LCM, there is no place to cache those request on LCM side. As there is no limit on how many times
+    /// ControlClient instance can call GetInitialMachineStateTransitionResult method, we will cache them on
+    /// ControlClientImpl side.
+    bool initial_machine_state_transition_request_;
+
     // Constructor to initialize all members
     ControlClientRequestInfo() : promise_(), in_use_(false), initial_machine_state_transition_request_(false)
     {

score/launch_manager/src/daemon/src/alive_monitor/details/daemon/PhmDaemon.hpp

@@ -33,11 +33,16 @@ namespace score::mw::lifecycle::internal::saf::daemon
 /// @brief Return codes for PhmDaemon Initialization
 enum class EInitCode : std::int8_t
 {
-    kNoError,                        ///< Init Successful (no error occurred)
-    kNotInitialized,                 ///< Init was not performed
-    kCycleTimeInitFailed,            ///< Cyclic Timer initialization failed
-    kConstructFlatCfgFactoryFailed,  ///< FlatCfgFactory failed loading SWCL configurations
-    kGeneralError                    ///< General error
+    /// @brief Init Successful (no error occurred)
+    kNoError,
+    /// @brief Init was not performed
+    kNotInitialized,
+    /// @brief Cyclic Timer initialization failed
+    kCycleTimeInitFailed,
+    /// @brief FlatCfgFactory failed loading SWCL configurations
+    kConstructFlatCfgFactoryFailed,
+    /// @brief General error
+    kGeneralError
 };
 
 /// @brief PHM daemon main class wraps the functionality for initialization and cyclic execution.

score/launch_manager/src/daemon/src/alive_monitor/details/ifappl/MonitorIfDaemon.hpp

@@ -122,15 +122,18 @@ class MonitorIfDaemon : public common::Observer<ifexm::ObservableEvent>
     /// @param[in] f_elem_r The checkpoint to push to observers
     void pushCheckpointToObservers(const CheckpointBufferElement& f_elem_r);
 
-    /// Internal states for instances of this class
+    /// @brief Internal states for instances of this class
     enum class EInternalState : std::uint8_t
     {
-        kActive,           ///< Interface active
-        kInactive,         ///< Interface inactive
-        kInactiveOverflow  ///< Interface inactive due to overflow
+        /// @brief Interface active
+        kActive,
+        /// @brief Interface inactive
+        kInactive,
+        /// @brief Interface inactive due to overflow
+        kInactiveOverflow
     };
 
-    /// Current internal state
+    /// @brief Current internal state
     EInternalState status{EInternalState::kInactive};
 
     /// @brief Current Activation request

score/launch_manager/src/daemon/src/alive_monitor/details/ipc/IpcBase.hpp

@@ -46,9 +46,12 @@ class IpcBase
     /// @brief Common ipc initialization return type.
     enum class EIpcInitResult : std::uint8_t
     {
-        kOk = 0U,               ///< Connection successful
-        kFailed = 1U,           ///< Connection failed - Generic
-        kPermissionDenied = 2U  ///< Connection failed - Permission Denied
+        /// @brief Connection successful
+        kOk = 0U,
+        /// @brief Connection failed - Generic
+        kFailed = 1U,
+        /// @brief Connection failed - Permission Denied
+        kPermissionDenied = 2U
     };
 
     /// @brief Return the ipc path (i.e. shared memory path)
@@ -96,9 +99,12 @@ class IpcBase
     /// require an enumeration rather than a simple boolean flag
     enum class EIpcPeekResult : std::uint8_t
     {
-        kOk = 0U,            ///< Data was successfully read
-        kNoDataToRead = 1U,  ///< No data available for reading
-        kIpcError = 2U       ///< Ipc connection is broken
+        /// @brief Data was successfully read
+        kOk = 0U,
+        /// @brief No data available for reading
+        kNoDataToRead = 1U,
+        /// @brief Ipc connection is broken
+        kIpcError = 2U
     };
 
     /// @brief Check if a new element can be read from IPC channel without removing the element

score/launch_manager/src/daemon/src/alive_monitor/details/supervision/Alive.hpp

@@ -165,12 +165,18 @@ class Alive : public ISupervision,
     /// @brief Enumeration of supervision update events
     enum class EUpdateEventType : std::uint8_t
     {
-        kNoChange = 0U,      ///< update event for no change in activation/deactivation
-        kActivation = 1U,    ///< update event for activation of supervision
-        kDeactivation = 2U,  ///< update event for deactivation of supervision
-        kCheckpoint = 3U,    ///< update event for reported checkpoint
-        kEvaluation = 4U,    ///< artificial update event for evaluation of supervision (relevant for Alive only)
-        kSync = 5U           ///< artificial update event for synchronization (relevant for Alive only)
+        /// @brief Update event for no change in activation/deactivation
+        kNoChange = 0U,
+        /// @brief Update event for activation of supervision
+        kActivation = 1U,
+        /// @brief Update event for deactivation of supervision
+        kDeactivation = 2U,
+        /// @brief Update event for reported checkpoint
+        kCheckpoint = 3U,
+        /// @brief Artificial update event for evaluation of supervision (relevant for Alive only)
+        kEvaluation = 4U,
+        /// @brief Artificial update event for synchronization (relevant for Alive only)
+        kSync = 5U
     };
 
     /// @brief Get timestamp of current update event
@@ -249,18 +255,25 @@ class Alive : public ISupervision,
     /// @brief Reasons for Alive state transitions
     enum class EReason : std::uint8_t
     {
-        kDataLoss,                 ///< Checkpoint data was lost, e.g. due to full buffer
-        kFailedToleranceExceeded,  ///< More failed cycles than the configured tolerance
-        kDataCorruption,           ///< Checkpoint data was corrupted
-        kOverflow                  ///< Overflow appeared, e.g. failed cycle counter or timestamp overflowed
+        /// @brief Checkpoint data was lost, e.g. due to full buffer
+        kDataLoss,
+        /// @brief More failed cycles than the configured tolerance
+        kFailedToleranceExceeded,
+        /// @brief Checkpoint data was corrupted
+        kDataCorruption,
+        /// @brief Overflow appeared, e.g. failed cycle counter or timestamp overflowed
+        kOverflow
     };
 
     /// @brief Reasons for Data loss
     enum class EDataLossReason : std::uint8_t
     {
-        kNoDataLoss,   ///< No data loss appeared
-        kBufferFull,   ///< Time sorted buffer is full
-        kSharedMemory  ///< Data loss in shared memory occurred
+        /// @brief No data loss appeared
+        kNoDataLoss,
+        /// @brief Time sorted buffer is full
+        kBufferFull,
+        /// @brief Data loss in shared memory occurred
+        kSharedMemory
     };
 
     /// @brief Switch to state Expired

score/launch_manager/src/daemon/src/common/constants.hpp

@@ -22,54 +22,65 @@ namespace score::mw::lifecycle::internal
 {
 
 // coverity[autosar_cpp14_a0_1_1_violation:INTENTIONAL] These are constants that are used globally.
-constexpr std::size_t kMaxArg = 20U;  ///< Maximum number of arguments
+/// @brief Maximum number of arguments
+constexpr std::size_t kMaxArg = 20U;
 // coverity[autosar_cpp14_a0_1_1_violation:INTENTIONAL] These are constants that are used globally.
-constexpr std::size_t kMaxEnv = 100U;  ///< Maximum number of env variables
+/// @brief Maximum number of env variables
+constexpr std::size_t kMaxEnv = 100U;
 // coverity[autosar_cpp14_a0_1_1_violation:INTENTIONAL] These are constants that are used globally.
-constexpr std::size_t kArgvArraySize =
-    kMaxArg + 2U;  ///< As required by posix we need extra space in argv_ for process name and NULL pointer
+/// @brief As required by posix we need extra space in argv_ for process name and NULL pointer
+constexpr std::size_t kArgvArraySize = kMaxArg + 2U;
 // coverity[autosar_cpp14_a0_1_1_violation:INTENTIONAL] These are constants that are used globally.
-constexpr std::size_t kEnvArraySize =
-    kMaxEnv + 1U;  ///< As required by posix we need extra space in envp_ for NULL pointer
+/// @brief As required by posix we need extra space in envp_ for NULL pointer
+constexpr std::size_t kEnvArraySize = kMaxEnv + 1U;
 
-constexpr std::chrono::milliseconds kMaxQueueDelay{
-    500};  ///< The maximum time to wait trying to add items to, or get items from, a queue
-constexpr std::chrono::milliseconds kGraphTimeout{10000};   ///< Timeout duration for graph operations.
-constexpr std::chrono::milliseconds kMaxSigKillDelay{500};  ///< The maximum time to wait for a process termination
+/// @brief The maximum time to wait trying to add items to, or get items from, a queue
+constexpr std::chrono::milliseconds kMaxQueueDelay{500};
+/// @brief Timeout duration for graph operations.
+constexpr std::chrono::milliseconds kGraphTimeout{10000};
+/// @brief The maximum time to wait for a process termination
+constexpr std::chrono::milliseconds kMaxSigKillDelay{500};
 
-constexpr std::chrono::milliseconds kControlClientPollingDelay{
-    1};  ///< Time Control Client will wait during polling for acknowledgement
+/// @brief Time Control Client will wait during polling for acknowledgement
+constexpr std::chrono::milliseconds kControlClientPollingDelay{1};
 
-constexpr std::chrono::milliseconds kMaxRunningDelay{
-    1000};  ///< report_running() API will wait for Launch Manager to respond
+/// @brief report_running() API will wait for Launch Manager to respond
+constexpr std::chrono::milliseconds kMaxRunningDelay{1000};
 
-constexpr std::chrono::milliseconds kControlClientMaxIpcDelay{
-    500};  ///< The maximum time to wait, when trying to communicate with LCM. When this time is exceeded
-           ///< kCommunicationError will be returned
+/// @brief The maximum time to wait, when trying to communicate with LCM. When this time is exceeded
+/// kCommunicationError will be returned
+constexpr std::chrono::milliseconds kControlClientMaxIpcDelay{500};
 constexpr std::chrono::milliseconds kControlClientBgThreadSleepTime{100};
 
-constexpr std::chrono::milliseconds kDefaultOffStateTransitionTimeout{
-    3000};  ///< Default timeout for Off state transition
+/// @brief Default timeout for Off state transition
+constexpr std::chrono::milliseconds kDefaultOffStateTransitionTimeout{3000};
 
-constexpr std::int64_t kMainLoopCycleTimeMs{50};  ///< The period at which the main loop services the watchdog
+/// @brief The period at which the main loop services the watchdog
+constexpr std::int64_t kMainLoopCycleTimeMs{50};
 constexpr std::int64_t kMainLoopCycleTimeNs{kMainLoopCycleTimeMs * 1'000'000LL};
 
+/// @brief Limits for ControlClient instances and requests
 enum class ControlClientLimits : uint16_t
 {
-    kControlClientMaxInstances = 256U,  ///< Maximum number of ControlClient instances that should be created by state
-                                        ///< manager. If state manager create more instances than kMaxInstances, those
-                                        ///< instances will always return kCommunicationError when used
-    kControlClientMaxRequests =
-        512U  ///< Maximum number of active requests, for example SetState call, that ControlClient instance can send to
-              ///< LCM. If that number is exceeded ControlClient API will return kFailed, until one of the current
-              ///< requests is completed by LCM
+    /// @brief Maximum number of ControlClient instances that should be created by state
+    /// manager. If state manager create more instances than kMaxInstances, those
+    /// instances will always return kCommunicationError when used
+    kControlClientMaxInstances = 256U,
+    /// @brief Maximum number of active requests, for example SetState call, that ControlClient instance can send to
+    /// LCM. If that number is exceeded ControlClient API will return kFailed, until one of the current
+    /// requests is completed by LCM
+    kControlClientMaxRequests = 512U
 };
 
+/// @brief Process and worker thread limit definitions
 enum class ProcessLimits : std::uint32_t
 {
-    kMaxProcesses = 1024U,    ///< Maximum number of processes allowed
-    kNumWorkerThreads = 32U,  ///< Maximum number of worker threads allowed
-    maxLocalBuffSize = 32U    ///< Maximum size for local buffer
+    /// @brief Maximum number of processes allowed
+    kMaxProcesses = 1024U,
+    /// @brief Maximum number of worker threads allowed
+    kNumWorkerThreads = 32U,
+    /// @brief Maximum size for local buffer
+    maxLocalBuffSize = 32U
 };
 
 /// @brief Default size of Alive Supervision checkpoint buffer

score/launch_manager/src/daemon/src/common/process_group_state_id.hpp

@@ -25,8 +25,11 @@ namespace score::mw::lifecycle::internal
 // have user-declared constructor. The rule doesn’t apply.", false)
 struct ProcessGroupStateID final
 {
-    score::mw::lifecycle::IdentifierHash pg_name_;        ///< Name of the process group.
-    score::mw::lifecycle::IdentifierHash pg_state_name_;  ///< Name of the process group state.
+    /// @brief Name of the process group.
+    score::mw::lifecycle::IdentifierHash pg_name_;
+
+    /// @brief Name of the process group state.
+    score::mw::lifecycle::IdentifierHash pg_state_name_;
 };
 
 }  // namespace score::mw::lifecycle::internal