typedef address_t moved to deviceComIF

devicehandlers/Cookie.h

@@ -2,7 +2,13 @@
 #define COOKIE_H_
 
 /**
- * This datatype is used to identify different connection over a single interface (like RMAP or I2C)
+ * @brief This datatype is used to identify different connection over a single interface
+ *        (like RMAP or I2C)
+ * @details
+ * To use this class, implement a communication specific child cookie. This cookie
+ * can be used in the device communication interface by performing
+ * a C++ dynamic cast. The cookie can be used to store all kinds of information
+ * about the communication between read and send calls.
  */
 class Cookie{
 public:

devicehandlers/DeviceCommunicationIF.h

@@ -8,6 +8,11 @@
  * @brief Communication interfaces for flight software objects
  */
 
+/**
+ * Physical address type
+ */
+typedef uint32_t address_t;
+
 /**
  * @brief This is an interface to decouple device communication from
  * the device handler to allow reuse of these components.
@@ -39,23 +44,36 @@ public:
 
 	virtual ~DeviceCommunicationIF() {}
 
-	virtual ReturnValue_t open(Cookie **cookie, uint32_t address,
+	/**
+	 * Open a connection. Define a communication specific cookie which can
+	 * be used to store information about the communication.
+	 *
+	 * @param cookie [in/out] This data class stores information about the communication.
+	 * @param address Logical device address
+	 * @param maxReplyLen Maximum length of expected reply
+	 * @return
+	 */
+	virtual ReturnValue_t open(Cookie **cookie, address_t address,
 			uint32_t maxReplyLen) = 0;
 
 	/**
 	 * Use an existing cookie to open a connection to a new DeviceCommunication.
 	 * The previous connection must not be closed.
-	 * If the returnvalue is not RETURN_OK, the cookie is unchanged and
-	 * can be used with the previous connection.
 	 *
 	 * @param cookie
 	 * @param address
 	 * @param maxReplyLen
-	 * @return
+	 * @return -@c RETURN_OK New communication set up successfully
+	 *         - Everything else: Cookie is unchanged and can be used with
+	 *           previous connection
 	 */
-	virtual ReturnValue_t reOpen(Cookie *cookie, uint32_t address,
+	virtual ReturnValue_t reOpen(Cookie *cookie, address_t address,
 			uint32_t maxReplyLen) = 0;
 
+	/**
+	 * Closing call of connection. Don't forget to free memory of cookie.
+	 * @param cookie
+	 */
 	virtual void close(Cookie *cookie) = 0;
 
 	/**
@@ -65,16 +83,18 @@ public:
 	 * @param cookie
 	 * @param data
 	 * @param len
-	 * @return @c RETURN_OK for successfull send
+	 * @return -@c RETURN_OK for successfull send
-	 *         Everything else triggers sending failed event with returnvalue as parameter 1
+	 *         -Everything else triggers sending failed event with
+	 *          returnvalue as parameter 1
 	 */
-	virtual ReturnValue_t sendMessage(Cookie *cookie,const uint8_t *data,
+	virtual ReturnValue_t sendMessage(Cookie *cookie, const uint8_t *data,
 			uint32_t len) = 0;
 
 	virtual ReturnValue_t getSendSuccess(Cookie *cookie) = 0;
 
 	/**
 	 * Called by DHB in the SEND_WRITE doSendRead().
+	 * Instructs the Communication Interface to prepare
 	 * @param cookie
 	 * @return
 	 */
@@ -93,9 +113,9 @@ public:
 	virtual ReturnValue_t readReceivedMessage(Cookie *cookie, uint8_t **buffer,
 			uint32_t *size) = 0;
 
-	virtual ReturnValue_t setAddress(Cookie *cookie, uint32_t address) = 0;
+	virtual ReturnValue_t setAddress(Cookie *cookie, address_t address) = 0;
 
-	virtual uint32_t getAddress(Cookie *cookie) = 0;
+	virtual address_t getAddress(Cookie *cookie) = 0;
 
 	/**
 	 * Can be used by DeviceHandlerBase getParameter() call to set DeviceComIF parameters
@@ -112,7 +132,6 @@ public:
 	 * @return
 	 */
 	virtual uint32_t getParameter(Cookie *cookie) = 0;
-
 };
 
 #endif /* DEVICECOMMUNICATIONIF_H_ */

devicehandlers/DeviceHandlerBase.h

@@ -33,28 +33,25 @@ class StorageManagerIF;
  * Contains all devices and the DeviceHandlerBase class.
  */
 
-/**
- * Physical address type
- */
-typedef uint32_t address_t;
-
 /**
  * @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
+ * It features handling of @link DeviceHandlerIF::Mode_t Modes @endlink,
- * physical devices, using the @link DeviceCommunicationIF @endlink, and communication with commanding objects.
+ * communication with physical devices, using the @link DeviceCommunicationIF @endlink,
+ * and communication with commanding objects.
  * It inherits SystemObject and thus can be created by the ObjectManagerIF.
  *
  * This class uses the opcode of ExecutableObjectIF to perform a step-wise execution.
  * For each step an RMAP action is selected and executed.
  * If data has been received (GET_READ), the data will be interpreted.
- * The action for each step can be defined by the child class but as most device handlers share a 4-call
+ * The action for each step can be defined by the child class but as most
- * (sendRead-getRead-sendWrite-getWrite) structure, a default implementation is provided.
+ * device handlers share a 4-call (sendRead-getRead-sendWrite-getWrite) structure,
- * NOTE: RMAP is a standard which is used for FLP.
+ * a default implementation is provided. 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.
+ * However, the communication principles are similar to RMAP as there are
+ * two write and two send calls involved.
  *
  * Device handler instances should extend this class and implement the abstract functions.
  * Components and drivers can send so called cookies which are used for communication
@@ -495,7 +492,8 @@ protected:
 	DeviceCommunicationIF *communicationInterface;
 
 	/**
-	 * Cookie used for communication
+	 * Cookie used for communication. This is passed to the communication
+	 * interface.
 	 */
 	Cookie *cookie;
 
@@ -910,7 +908,7 @@ private:
 	/**
 	 * State a cookie is in.
 	 *
-	 * Used to keep track of the state of the RMAP communication.
+	 * Used to keep track of the state of the communication.
 	 */
 	enum CookieState_t {
 		COOKIE_UNUSED,    //!< The Cookie is unused

rmap/RmapDeviceCommunicationIF.h

@@ -4,7 +4,8 @@
 #include <framework/devicehandlers/DeviceCommunicationIF.h>
 
 /**
- * @brief	This class is a implementation of a DeviceCommunicationIF for RMAP calls. It expects RMAPCookies or a derived class of RMAPCookies
+ * @brief	This class is a implementation of a DeviceCommunicationIF for RMAP calls.
+ *          It expects RMAPCookies or a derived class of RMAPCookies
  *
  * @details	The open, close and reOpen calls are mission specific
  * 			The open call might return any child of RMAPCookies
@@ -44,7 +45,8 @@ public:
 
 
 	/**
-	 * Closing call of connection and memory free of cookie. Mission dependent call
+	 * Closing call of connection and free memory of cookie.
+	 * Mission dependent call
 	 * @param cookie
 	 */
 	virtual void close(Cookie *cookie) = 0;