From f22f804e8d2341ee40cd6ec5d1bbb937851dbf2e Mon Sep 17 00:00:00 2001
From: kongr45gpen <electrovesta@gmail.com>
Date: Tue, 13 Aug 2019 02:45:56 +0300
Subject: [PATCH] Fix some doxygen warnings
---
inc/ECSS_Definitions.hpp | 6 ++++++
inc/ErrorHandler.hpp | 17 +++++++++++++++--
inc/Helpers/TimeHelper.hpp | 8 ++++----
inc/Message.hpp | 2 +-
inc/MessageParser.hpp | 8 +++-----
inc/Service.hpp | 1 -
inc/Services/EventReportService.hpp | 15 +++++----------
inc/Services/FunctionManagementService.hpp | 5 ++---
inc/Services/LargePacketTransferService.hpp | 2 +-
inc/Services/MemoryManagementService.hpp | 2 +-
inc/Services/TimeBasedSchedulingService.hpp | 20 +++++++-------------
inc/Services/TimeManagementService.hpp | 2 +-
inc/etl/String.hpp | 2 +-
src/Services/EventReportService.cpp | 11 +++++++----
14 files changed, 54 insertions(+), 47 deletions(-)
diff --git a/inc/ECSS_Definitions.hpp b/inc/ECSS_Definitions.hpp
index 90eec544..eb2f737d 100644
--- a/inc/ECSS_Definitions.hpp
+++ b/inc/ECSS_Definitions.hpp
@@ -94,6 +94,12 @@
*/
#define ECSS_TIME_MARGIN_FOR_ACTIVATION 60
+/**
+ * @brief Maximum size of an event's auxiliary data
+ * @see EventReportService
+ */
+#define ECSS_EVENT_DATA_AUXILIARY_MAX_SIZE 64
+
/**
* @brief Size of the multimap that holds every event-action definition
* @see EventActionService
diff --git a/inc/ErrorHandler.hpp b/inc/ErrorHandler.hpp
index 238d685d..caeae9c8 100644
--- a/inc/ErrorHandler.hpp
+++ b/inc/ErrorHandler.hpp
@@ -229,11 +229,17 @@ public:
* Reports a failure that occurred internally, not due to a failure of a received packet.
*
* Creates an error if \p condition is false. The created error is Internal.
+ *
+ * @param condition The condition to check. Throws an error if false.
+ * @param errorCode The error code that is assigned to this error. One of the \ref ErrorHandler enum values.
+ * @return Returns \p condition, i.e. true if the assertion is successful, false if not.
*/
- static void assertInternal(bool condition, InternalErrorType errorCode) {
+ static bool assertInternal(bool condition, InternalErrorType errorCode) {
if (not condition) {
reportInternalError(errorCode);
}
+
+ return condition;
}
/**
@@ -242,12 +248,19 @@ public:
* Reports a failure that occurred while processing a request, in any of the process phases.
*
* Creates an error if \p condition is false. The created error corresponds to a \p message.
+ *
+ * @param condition The condition to check. Throws an error if false.
+ * @param message The message to associate with this error
+ * @param errorCode The error code that is assigned to this error. One of the \ref ErrorHandler enum values.
+ * @return Returns \p condition, i.e. true if the assertion is successful, false if not.
*/
template <typename ErrorType>
- static void assertRequest(bool condition, const Message& message, ErrorType errorCode) {
+ static bool assertRequest(bool condition, const Message& message, ErrorType errorCode) {
if (not condition) {
reportError(message, errorCode);
}
+
+ return condition;
}
/**
diff --git a/inc/Helpers/TimeHelper.hpp b/inc/Helpers/TimeHelper.hpp
index 526b8033..027e078e 100644
--- a/inc/Helpers/TimeHelper.hpp
+++ b/inc/Helpers/TimeHelper.hpp
@@ -33,7 +33,7 @@
* decides what the time unit will be, so this is a subject for discussion. The recommended time unit from the
* standard is the second and it is probably the best solution for accuracy.
*
- * @notes
+ * @note
* The defined epoch for both time formats is 1 January 1958 00:00:00
*
* Since CDS format is UTC-based, the leap second correction must be made. The leap seconds that
@@ -56,7 +56,7 @@ public:
/**
* Convert UTC date to elapsed seconds since Unix epoch (1/1/1970 00:00:00).
*
- * This is a reimplemented mktime() of <ctime> library in an embedded systems way
+ * This is a reimplemented `mktime()` of the `<ctime>` library in an embedded compatible way
*
* @note
* This function can convert UTC dates after 1 January 2019 to elapsed seconds since Unix epoch
@@ -71,7 +71,7 @@ public:
/**
* Convert elapsed seconds since Unix epoch to UTC date.
*
- * This is a reimplemented gmtime() of <ctime> library in an embedded systems way
+ * This is a reimplemented `gmtime()` of the `<ctime>` library in an embedded compatible way
*
* @note
* This function can convert elapsed seconds since Unix epoch to UTC dates after 1 January 2019
@@ -110,7 +110,7 @@ public:
*
* Converts a UTC date to CUC time format.
*
- * @notes
+ * @note
* The T-field is specified for the seconds passed from the defined epoch 1 January 1958. We use 4 octets(32
* bits) for the time unit (seconds) because 32 bits for the seconds are enough to count 136 years! But if we use 24
* bits for the seconds then it will count 0,5 years and this isn't enough. Remember we can use only integers
diff --git a/inc/Message.hpp b/inc/Message.hpp
index b59938dd..f94c31be 100644
--- a/inc/Message.hpp
+++ b/inc/Message.hpp
@@ -33,7 +33,7 @@ public:
/**
* @brief Overload the equality operator to compare messages
* @details Compare two @ref ::Message objects, based on their contents and type
- * @param The message content to compare against
+ * @param msg The message content to compare against
* @return The result of comparison
*/
bool operator==(const Message& msg) const {
diff --git a/inc/MessageParser.hpp b/inc/MessageParser.hpp
index 7bc486ef..82517e82 100644
--- a/inc/MessageParser.hpp
+++ b/inc/MessageParser.hpp
@@ -36,9 +36,7 @@ public:
* This function takes as input TC packets and calls the proper services' functions that have been
* implemented to handle TC packets.
*
- * @param Message Contains the necessary parameters to call the suitable subservice
- * @todo Implement the execute() in the upcoming services or generally in the upcoming
- * activities
+ * @param message Contains the necessary parameters to call the suitable subservice
*/
static void execute(Message& message);
@@ -73,8 +71,8 @@ public:
* @brief Converts a TC or TM message to a message string, appending just the ECSS header
* @todo Add time reference, as soon as it is available and the format has been specified
* @param message The Message object to be parsed to a String
- * @param size The wanted size of the message (including the headers). Messages larger than \ref size display an
- * error. Messages smaller than \ref size are padded with zeros. When `size = 0`, there is no size limit.
+ * @param size The wanted size of the message (including the headers). Messages larger than \p size display an
+ * error. Messages smaller than \p size are padded with zeros. When `size = 0`, there is no size limit.
* @return A String class containing the parsed Message
*/
static String<CCSDS_MAX_MESSAGE_SIZE> composeECSS(const Message& message, uint16_t size = 0u); // Ignore-MISRA
diff --git a/inc/Service.hpp b/inc/Service.hpp
index e28620ff..53bf0bae 100644
--- a/inc/Service.hpp
+++ b/inc/Service.hpp
@@ -36,7 +36,6 @@ protected:
* the TC[17,3] message has `messageType = 3`.
* @todo See if the Message must be returned by reference
* @todo Set the application ID to the current application
- * @todo Use the messageTypeCounter
*/
Message createTM(uint8_t messageType) {
return Message(serviceType, messageType, Message::TM, 0);
diff --git a/inc/Services/EventReportService.hpp b/inc/Services/EventReportService.hpp
index f9b01634..69b80e80 100644
--- a/inc/Services/EventReportService.hpp
+++ b/inc/Services/EventReportService.hpp
@@ -102,9 +102,8 @@ public:
*
* @param eventID event definition ID
* @param data the data of the report
- * @param length the length of the data
*/
- void informativeEventReport(Event eventID, const String<64>& data);
+ void informativeEventReport(Event eventID, const String<ECSS_EVENT_DATA_AUXILIARY_MAX_SIZE>& data);
/**
* TM[5,2] low severiity anomaly report
@@ -114,9 +113,8 @@ public:
*
* @param eventID event definition ID
* @param data the data of the report
- * @param length the length of the data
*/
- void lowSeverityAnomalyReport(Event eventID, const String<64>& data);
+ void lowSeverityAnomalyReport(Event eventID, const String<ECSS_EVENT_DATA_AUXILIARY_MAX_SIZE>& data);
/**
* TM[5,3] medium severity anomaly report
@@ -126,9 +124,8 @@ public:
*
* @param eventID event definition ID
* @param data the data of the report
- * @param length the length of the data
*/
- void mediumSeverityAnomalyReport(Event eventID, const String<64>& data);
+ void mediumSeverityAnomalyReport(Event eventID, const String<ECSS_EVENT_DATA_AUXILIARY_MAX_SIZE>& data);
/**
* TM[5,4] high severity anomaly report
@@ -138,9 +135,8 @@ public:
*
* @param eventID event definition ID
* @param data the data of the report
- * @param length the length of the data
*/
- void highSeverityAnomalyReport(Event eventID, const String<64>& data);
+ void highSeverityAnomalyReport(Event eventID, const String<ECSS_EVENT_DATA_AUXILIARY_MAX_SIZE>& data);
/**
* TC[5,5] request to enable report generation
@@ -165,7 +161,6 @@ public:
/**
* TM[5,8] disabled event definitions report
* Telemetry package of a report of the disabled event definitions
- * @param message
*/
void listOfDisabledEventsReport();
@@ -182,7 +177,7 @@ public:
* is the ground station.
*
* @note This function is called from the main execute() that is defined in the file MessageParser.hpp
- * @param param Contains the necessary parameters to call the suitable subservice
+ * @param message Contains the necessary parameters to call the suitable subservice
*/
void execute(Message& message);
};
diff --git a/inc/Services/FunctionManagementService.hpp b/inc/Services/FunctionManagementService.hpp
index 401591ef..36f68d84 100644
--- a/inc/Services/FunctionManagementService.hpp
+++ b/inc/Services/FunctionManagementService.hpp
@@ -46,6 +46,7 @@
* include(String<FUNC_NAME_LENGTH>("bar"), &bar);
* include(String<FUNC_NAME_LENGTH>("baz"), &baz);
* }
+ * @endcode
*/
typedef String<ECSS_FUNCTION_NAME_LENGTH> functionName;
@@ -61,8 +62,6 @@ public:
/**
* Constructs the function pointer index with all the necessary functions at initialization time
* These functions need to be in scope. Un-default when needed.
- *
- * @param None
*/
FunctionManagementService() = default;
@@ -93,7 +92,7 @@ public:
* is the ground station.
*
* @note This function is called from the main execute() that is defined in the file MessageParser.hpp
- * @param param Contains the necessary parameters to call the suitable subservice
+ * @param message Contains the necessary parameters to call the suitable subservice
*/
void execute(Message& message);
};
diff --git a/inc/Services/LargePacketTransferService.hpp b/inc/Services/LargePacketTransferService.hpp
index 5b3b276c..fe91522b 100644
--- a/inc/Services/LargePacketTransferService.hpp
+++ b/inc/Services/LargePacketTransferService.hpp
@@ -74,7 +74,7 @@ public:
/**
* Function that splits large messages
- * @param Message that is exceeds the standards and has to be split down
+ * @param message that is exceeds the standards and has to be split down
* @param largeMessageTransactionIdentifier that is a value we assign to this splitting of the large message
*/
void split(Message& message, uint16_t largeMessageTransactionIdentifier);
diff --git a/inc/Services/MemoryManagementService.hpp b/inc/Services/MemoryManagementService.hpp
index f5c1770e..9ae1de6e 100644
--- a/inc/Services/MemoryManagementService.hpp
+++ b/inc/Services/MemoryManagementService.hpp
@@ -80,7 +80,7 @@ public:
* is the ground station.
*
* @note This function is called from the main execute() that is defined in the file MessageParser.hpp
- * @param param Contains the necessary parameters to call the suitable subservice
+ * @param message Contains the necessary parameters to call the suitable subservice
*/
void execute(Message& message);
diff --git a/inc/Services/TimeBasedSchedulingService.hpp b/inc/Services/TimeBasedSchedulingService.hpp
index e3a6b772..e748b25f 100644
--- a/inc/Services/TimeBasedSchedulingService.hpp
+++ b/inc/Services/TimeBasedSchedulingService.hpp
@@ -59,14 +59,11 @@ private:
*
* @details The request identifier consists of the application process ID, the packet
* sequence count and the source ID, all defined in the ECSS standard.
- * @var applicationID Application process ID
- * @var sequenceCount Packet sequence count
- * @var sourceID Packet source ID
*/
struct RequestID {
- uint16_t applicationID = 0;
- uint16_t sequenceCount = 0;
- uint8_t sourceID = 0;
+ uint16_t applicationID = 0; ///< Application process ID
+ uint16_t sequenceCount = 0; ///< Packet sequence count
+ uint8_t sourceID = 0; ///< Packet source ID
bool operator!=(const RequestID& rightSide) const {
return (sequenceCount != rightSide.sequenceCount) or (applicationID != rightSide.applicationID) or
@@ -79,14 +76,11 @@ private:
*
* @details All scheduled activities must contain the request they exist for, their release
* time and the corresponding request identifier.
- * @var request Contains the received TC request
- * @var requestID Contains the unique request identifier for that activity
- * @var requestReleaseTime The absolute time is seconds of the request release
*/
struct ScheduledActivity {
- Message request; // Hold the received command request
- RequestID requestID; // Request ID, characteristic of the definition
- uint32_t requestReleaseTime = 0; // Keep the command release time
+ Message request; ///< Hold the received command request
+ RequestID requestID; ///< Request ID, characteristic of the definition
+ uint32_t requestReleaseTime = 0; ///< Keep the command release time
// todo: If we decide to use sub-schedules, the ID of that has to be defined
// todo: If groups are used, then the group ID has to be defined here
};
@@ -138,7 +132,7 @@ public:
void enableScheduleExecution(Message& request);
/**
- * @breif TC[11,2] disable the time-based schedule execution function
+ * @brief TC[11,2] disable the time-based schedule execution function
*
* @details Disables the time-based command execution scheduling
* @param request Provide the received message as a parameter
diff --git a/inc/Services/TimeManagementService.hpp b/inc/Services/TimeManagementService.hpp
index 22e2aefb..54617aaf 100644
--- a/inc/Services/TimeManagementService.hpp
+++ b/inc/Services/TimeManagementService.hpp
@@ -8,7 +8,7 @@
* Implementation of the ST[09] time management.
*
* @ingroup Services
- * @notes
+ * @note
* There is a noticeable difference between setting the time using GPS and setting the time
* using space packets from the ground segment. The GPS module sends the actual time of UTC (123519
* is 12:35:19 UTC), while space packets, for time configuration, sends the elapsed time units
diff --git a/inc/etl/String.hpp b/inc/etl/String.hpp
index 04112ef9..7691f783 100644
--- a/inc/etl/String.hpp
+++ b/inc/etl/String.hpp
@@ -63,7 +63,7 @@ public:
* Append a specified number of bytes from a uint8_t array to the String
* @details The array does NOT need to be null-terminated
* @param data The characters to append
- * @param n The number of characters that \ref data contains
+ * @param n The number of characters that \p data contains
* @return This string
*/
String& append(const uint8_t* data, size_t n) {
diff --git a/src/Services/EventReportService.cpp b/src/Services/EventReportService.cpp
index baf2ba48..c805a5fc 100644
--- a/src/Services/EventReportService.cpp
+++ b/src/Services/EventReportService.cpp
@@ -6,7 +6,7 @@
* @todo: Add message type in TCs
* @todo: this code is error prone, depending on parameters given, add fail safes (probably?)
*/
-void EventReportService::informativeEventReport(Event eventID, const String<64>& data) {
+void EventReportService::informativeEventReport(Event eventID, const String<ECSS_EVENT_DATA_AUXILIARY_MAX_SIZE>& data) {
// TM[5,1]
if (stateOfEvents[static_cast<uint16_t>(eventID)]) {
Message report = createTM(1);
@@ -19,7 +19,8 @@ void EventReportService::informativeEventReport(Event eventID, const String<64>&
}
}
-void EventReportService::lowSeverityAnomalyReport(Event eventID, const String<64>& data) {
+void
+EventReportService::lowSeverityAnomalyReport(Event eventID, const String<ECSS_EVENT_DATA_AUXILIARY_MAX_SIZE>& data) {
lowSeverityEventCount++;
// TM[5,2]
if (stateOfEvents[static_cast<uint16_t>(eventID)]) {
@@ -35,7 +36,8 @@ void EventReportService::lowSeverityAnomalyReport(Event eventID, const String<64
}
}
-void EventReportService::mediumSeverityAnomalyReport(Event eventID, const String<64>& data) {
+void
+EventReportService::mediumSeverityAnomalyReport(Event eventID, const String<ECSS_EVENT_DATA_AUXILIARY_MAX_SIZE>& data) {
mediumSeverityEventCount++;
// TM[5,3]
if (stateOfEvents[static_cast<uint16_t>(eventID)]) {
@@ -51,7 +53,8 @@ void EventReportService::mediumSeverityAnomalyReport(Event eventID, const String
}
}
-void EventReportService::highSeverityAnomalyReport(Event eventID, const String<64>& data) {
+void
+EventReportService::highSeverityAnomalyReport(Event eventID, const String<ECSS_EVENT_DATA_AUXILIARY_MAX_SIZE>& data) {
highSeverityEventCount++;
// TM[5,4]
if (stateOfEvents[static_cast<uint16_t>(eventID)]) {
--
GitLab