From 9c3a9323b7ee50685fd23b57c9d1b39445c43a18 Mon Sep 17 00:00:00 2001 From: "Robin.Mueller" Date: Tue, 3 Dec 2019 19:30:37 +0100 Subject: [PATCH] some doc change proposals while writing hk service. Added Type.h in PoolRawAccess.h, compiler error when not doing that --- datapool/PoolRawAccess.h | 6 +-- datapool/PoolVariable.h | 3 +- devicehandlers/DeviceHandlerBase.h | 63 ++++++++++++++-------------- objectmanager/ObjectManagerIF.h | 6 +-- tmtcservices/AcceptsTelecommandsIF.h | 2 +- 5 files changed, 38 insertions(+), 42 deletions(-) diff --git a/datapool/PoolRawAccess.h b/datapool/PoolRawAccess.h index 3e2bd7ae..9a3000c0 100644 --- a/datapool/PoolRawAccess.h +++ b/datapool/PoolRawAccess.h @@ -3,6 +3,7 @@ #include #include +#include /** * This class allows accessing Data Pool variables as raw bytes. @@ -79,9 +80,8 @@ public: ~PoolRawAccess(); /** * \brief This operation returns a pointer to the entry fetched. - * \details This means, it does not return a pointer to byte "index", but to the start byte of - * array entry "index". Example: If the original data pool array consists of an double - * array of size four, getEntry(1) returns &(this->value[8]). + * \details Return pointer to the buffer containing the raw data + * Size and number of data can be retrieved by other means. */ uint8_t* getEntry(); /** diff --git a/datapool/PoolVariable.h b/datapool/PoolVariable.h index 25345c0a..2c48ca3e 100644 --- a/datapool/PoolVariable.h +++ b/datapool/PoolVariable.h @@ -112,8 +112,7 @@ public: * corresponds to. * \param dataSet The data set in which the variable shall register itself. If NULL, * the variable is not registered. - * \param setWritable If this flag is set to true, changes in the value attribute can be - * written back to the data pool, otherwise not. + * \param setReadWriteMode */ PoolVariable(uint32_t set_id, DataSetIF* dataSet, ReadWriteMode_t setReadWriteMode) : diff --git a/devicehandlers/DeviceHandlerBase.h b/devicehandlers/DeviceHandlerBase.h index b5ffa2ee..d489ada1 100644 --- a/devicehandlers/DeviceHandlerBase.h +++ b/devicehandlers/DeviceHandlerBase.h @@ -35,14 +35,14 @@ class StorageManagerIF; /** - * \brief This is the abstract base class for device handlers. - * + * @brief This is the abstract base class for device handlers. + * @details * Documentation: Dissertation Baetz p.138,139, p.141-149 * * It features handling of @link DeviceHandlerIF::Mode_t Modes @endlink, communication with * physical devices, using the @link DeviceCommunicationIF, and communication with commanding objects. * - * NOTE: RMAP is a legacy standard which is used for FLP. + * NOTE: RMAP is a standard which is used for FLP. * RMAP communication is not mandatory for projects implementing the FSFW. * However, the communication principles are similar to RMAP as there are two write and two send calls involved. * @@ -57,7 +57,7 @@ class StorageManagerIF; * Components and drivers can send so called cookies which are used for communication * and contain information about the communcation (e.g. slave address for I2C or RMAP structs). * - * \ingroup devices + * @ingroup devices */ class DeviceHandlerBase: public DeviceHandlerIF, public HasReturnvaluesIF, @@ -87,33 +87,34 @@ public: /** - * This function is the device handler base core component and is called periodically. - * General sequence: - * If the State is SEND_WRITE: - * 1. Set the cookie state to COOKIE_UNUSED and read the command queue - * 2. Handles Device State Modes by calling doStateMachine(). - * This function calls callChildStatemachine() which calls the abstract functions - * doStartUp() and doShutDown() - * 3. Check switch states by calling checkSwitchStates() - * 4. Decrements counter for timeout of replies by calling decrementDeviceReplyMap() - * 5. Performs FDIR check for failures - * 6. Calls hkSwitcher.performOperation() - * 7. If the device mode is MODE_OFF, return RETURN_OK. Otherwise, perform the Action property - * and performs depending on value specified - * by input value counter. The child class tells base class what to do by setting this value. - * - SEND_WRITE: Send data or commands to device by calling doSendWrite() which calls - * sendMessage function of #communicationInterface - * and calls buildInternalCommand if the cookie state is COOKIE_UNUSED - * - GET_WRITE: Get ackknowledgement for sending by calling doGetWrite() which calls - * getSendSuccess of #communicationInterface. - * Calls abstract functions scanForReply() and interpretDeviceReply(). - * - SEND_READ: Request reading data from device by calling doSendRead() which calls - * requestReceiveMessage of #communcationInterface - * - GET_READ: Access requested reading data by calling doGetRead() which calls - * readReceivedMessage of #communicationInterface - * @param counter Specifies which Action to perform - * @return RETURN_OK for successful execution - */ + * @brief This function is the device handler base core component and is called periodically. + * @details + * General sequence, showing where abstract virtual functions are called: + * If the State is SEND_WRITE: + * 1. Set the cookie state to COOKIE_UNUSED and read the command queue + * 2. Handles Device State Modes by calling doStateMachine(). + * This function calls callChildStatemachine() which calls the abstract functions + * doStartUp() and doShutDown() + * 3. Check switch states by calling checkSwitchStates() + * 4. Decrements counter for timeout of replies by calling decrementDeviceReplyMap() + * 5. Performs FDIR check for failures + * 6. Calls hkSwitcher.performOperation() + * 7. If the device mode is MODE_OFF, return RETURN_OK. Otherwise, perform the Action property + * and performs depending on value specified + * by input value counter. The child class tells base class what to do by setting this value. + * - SEND_WRITE: Send data or commands to device by calling doSendWrite() which calls + * sendMessage function of #communicationInterface + * and calls buildInternalCommand if the cookie state is COOKIE_UNUSED + * - GET_WRITE: Get ackknowledgement for sending by calling doGetWrite() which calls + * getSendSuccess of #communicationInterface. + * Calls abstract functions scanForReply() and interpretDeviceReply(). + * - SEND_READ: Request reading data from device by calling doSendRead() which calls + * requestReceiveMessage of #communcationInterface + * - GET_READ: Access requested reading data by calling doGetRead() which calls + * readReceivedMessage of #communicationInterface + * @param counter Specifies which Action to perform + * @return RETURN_OK for successful execution + */ virtual ReturnValue_t performOperation(uint8_t counter); virtual ReturnValue_t initialize(); diff --git a/objectmanager/ObjectManagerIF.h b/objectmanager/ObjectManagerIF.h index 9f58f600..5fbce282 100644 --- a/objectmanager/ObjectManagerIF.h +++ b/objectmanager/ObjectManagerIF.h @@ -79,11 +79,7 @@ public: }; /** - * Used to retrieve Target Interface Pointers of objects. - * The object has to implement the SystemObject or SystemObjectIF at the very least, - * otherwise NULL will be returned. - * @param id - * @return NULL or pointer to target interface specified by template object + * @brief Documentation can be found in the class method declration. */ template T* ObjectManagerIF::get( object_id_t id ) { diff --git a/tmtcservices/AcceptsTelecommandsIF.h b/tmtcservices/AcceptsTelecommandsIF.h index 03a57aae..0952d3a6 100644 --- a/tmtcservices/AcceptsTelecommandsIF.h +++ b/tmtcservices/AcceptsTelecommandsIF.h @@ -12,7 +12,7 @@ class AcceptsTelecommandsIF { public: static const uint8_t INTERFACE_ID = CLASS_ID::ACCEPTS_TELECOMMANDS_IF; - static const ReturnValue_t ACTIVITY_STARTED = MAKE_RETURN_CODE(1); + static const ReturnValue_t ACTIVITY_STARTED = MAKE_RETURN_CODE(1); // is this used anywhere or can it be removed? static const ReturnValue_t INVALID_SUBSERVICE = MAKE_RETURN_CODE(2); static const ReturnValue_t ILLEGAL_APPLICATION_DATA = MAKE_RETURN_CODE(3); static const ReturnValue_t SEND_TM_FAILED = MAKE_RETURN_CODE(4);