From 16af33a7bb52e3d9363e1e6f61e16a67783f74df Mon Sep 17 00:00:00 2001
From: "Robin.Mueller" <robin.mueller.m@gmail.com>
Date: Tue, 29 Oct 2019 19:31:18 +0100
Subject: [PATCH] doc for fifo, device com if..

---
 container/FIFO.h                       |  4 +--
 container/SimpleRingBuffer.h           | 28 +++++++++++++++++++++
 devicehandlers/DeviceCommunicationIF.h | 35 +++++++++++++++++++++++++-
 serialize/SerializeAdapter.h           |  2 ++
 4 files changed, 66 insertions(+), 3 deletions(-)

diff --git a/container/FIFO.h b/container/FIFO.h
index 670a50d7..134da9b8 100644
--- a/container/FIFO.h
+++ b/container/FIFO.h
@@ -21,7 +21,7 @@ public:
 			readIndex(0), writeIndex(0), currentSize(0) {
 	}
 
-	bool emtpy() {
+	bool empty() {
 		return (currentSize == 0);
 	}
 
@@ -45,7 +45,7 @@ public:
 	}
 
 	ReturnValue_t retrieve(T *value) {
-		if (emtpy()) {
+		if (empty()) {
 			return EMPTY;
 		} else {
 			*value = data[readIndex];
diff --git a/container/SimpleRingBuffer.h b/container/SimpleRingBuffer.h
index 6d7d67e1..45cb0927 100644
--- a/container/SimpleRingBuffer.h
+++ b/container/SimpleRingBuffer.h
@@ -4,12 +4,40 @@
 #include <framework/container/RingBufferBase.h>
 #include <stddef.h>
 
+/**
+ * Circular buffer implementation, useful for buffering into data streams.
+ * Note that the deleteData() has to be called to increment the read pointer
+ */
 class SimpleRingBuffer: public RingBufferBase<> {
 public:
 	SimpleRingBuffer(uint32_t size, bool overwriteOld);
 	virtual ~SimpleRingBuffer();
+
+	/**
+	 * Write to circular buffer and increment write pointer by amount
+	 * @param data
+	 * @param amount
+	 * @return
+	 */
 	ReturnValue_t writeData(const uint8_t* data, uint32_t amount);
+
+	/**
+	 * Read from circular buffer at read pointer
+	 * @param data
+	 * @param amount
+	 * @param readRemaining
+	 * @param trueAmount
+	 * @return
+	 */
 	ReturnValue_t readData(uint8_t* data, uint32_t amount, bool readRemaining = false, uint32_t* trueAmount = NULL);
+
+	/**
+	 * Delete data starting by incrementing read pointer
+	 * @param amount
+	 * @param deleteRemaining
+	 * @param trueAmount
+	 * @return
+	 */
 	ReturnValue_t deleteData(uint32_t amount, bool deleteRemaining = false, uint32_t* trueAmount = NULL);
 private:
 //	static const uint8_t TEMP_READ_PTR = 1;
diff --git a/devicehandlers/DeviceCommunicationIF.h b/devicehandlers/DeviceCommunicationIF.h
index 88f0d124..59420861 100644
--- a/devicehandlers/DeviceCommunicationIF.h
+++ b/devicehandlers/DeviceCommunicationIF.h
@@ -4,6 +4,22 @@
 #include <framework/devicehandlers/Cookie.h>
 #include <framework/returnvalues/HasReturnvaluesIF.h>
 
+/**
+ * Documentation: Dissertation Baetz p.138
+ *
+ * This is an interface to decouple device communication from
+ * the device handler to allow reuse of these components.
+ * It works with the assumption that received data
+ * is polled by a component. There are four generic steps of device communication:
+ *
+ *   1. Send data to a device
+ *   2. Get acknowledgement for sending
+ *   3. Request reading data from a device
+ *   4. Read received data
+ *
+ *  To identify different connection over a single interface can return so-called cookies to components.
+ *
+ */
 class DeviceCommunicationIF: public HasReturnvaluesIF {
 public:
 	static const uint8_t INTERFACE_ID = CLASS_ID::DEVICE_COMMUNICATION_IF;
@@ -39,7 +55,15 @@ public:
 
 	virtual void close(Cookie *cookie) = 0;
 
-	//SHOULDDO can data be const?
+	/**
+	 * Called by DHB in the SEND_WRITE doSendWrite().
+	 * This function is used to send data to the physical device
+	 * by implementing and calling related drivers or wrapper functions.
+	 * @param cookie
+	 * @param data
+	 * @param len
+	 * @return
+	 */
 	virtual ReturnValue_t sendMessage(Cookie *cookie,const uint8_t *data,
 			uint32_t len) = 0;
 
@@ -47,6 +71,15 @@ public:
 
 	virtual ReturnValue_t requestReceiveMessage(Cookie *cookie) = 0;
 
+	/**
+	 * Called by DHB in the GET_WIRTE doGetRead().
+	 * This function is used to receive data from the physical device
+	 * by implementing and calling related drivers or wrapper functions.
+	 * @param cookie
+	 * @param data
+	 * @param len
+	 * @return
+	 */
 	virtual ReturnValue_t readReceivedMessage(Cookie *cookie, uint8_t **buffer,
 			uint32_t *size) = 0;
 
diff --git a/serialize/SerializeAdapter.h b/serialize/SerializeAdapter.h
index 04216c89..a0aab9e9 100644
--- a/serialize/SerializeAdapter.h
+++ b/serialize/SerializeAdapter.h
@@ -28,6 +28,8 @@
  * This can also be applied to uint32_t and uint64_t:
  *
  *   1. Use the AutoSerializeAdapter::deSerialize function with bool bigEndian = true:
+ *		The pointer *buffer will be incremented automatically by the typeSize of data,
+ *		so this function can be called on &buffer without adjusting pointer position
  *
  *   	uint16_t data;
  *   	int32_t dataLen = sizeof(data);