From 0258ce62f0ccb64be8f87e17321627171601f348 Mon Sep 17 00:00:00 2001
From: Steffen Gaisser <gaisser@irs.uni-stuttgart.de>
Date: Mon, 7 Sep 2020 18:35:25 +0200
Subject: [PATCH] Added documentation

---
 serialize/SerializeAdapter.h | 71 ++++++++++++++++++++++++++++++++----
 serialize/SerializeIF.h      |  2 +-
 2 files changed, 64 insertions(+), 9 deletions(-)

diff --git a/serialize/SerializeAdapter.h b/serialize/SerializeAdapter.h
index cd6b6b06..a05b1791 100644
--- a/serialize/SerializeAdapter.h
+++ b/serialize/SerializeAdapter.h
@@ -1,10 +1,10 @@
-#ifndef SERIALIZEADAPTER_H_
-#define SERIALIZEADAPTER_H_
+#ifndef _FSFW_SERIALIZE_SERIALIZEADAPTER_H_
+#define _FSFW_SERIALIZE_SERIALIZEADAPTER_H_
 
 #include "../returnvalues/HasReturnvaluesIF.h"
 #include "EndianConverter.h"
 #include "SerializeIF.h"
-#include <string.h>
+#include <cstddef>
 #include <type_traits>
 
 /**
@@ -13,6 +13,22 @@
 
 class SerializeAdapter {
 public:
+	/***
+	 * This function can be used to serialize a trivial copy-able type or a child of SerializeIF.
+	 * The right template to be called is determined in the function itself.
+	 * For objects of non trivial copy-able type this function is almost never called by the user directly.
+	 * Instead helpers for specific types like SerialArrayListAdapter or SerialLinkedListAdapter is the right choice here.
+	 *
+	 * @param[in] object Object to serialize, the used type is deduced from this pointer
+	 * @param[in/out] buffer Buffer to serialize into. Will be moved by the function.
+	 * @param[in/out] size Size of current written buffer. Will be incremented by the function.
+	 * @param[in] maxSize Max size of Buffer
+	 * @param[in] streamEndianness Endianness of serialized element as in according to SerializeIF::Endianness
+	 * @return
+	 * 		- @c BUFFER_TOO_SHORT The given buffer in is too short
+	 * 		- @c RETURN_FAILED Generic Error
+	 * 		- @c RETURN_OK Successful serialization
+	 */
 	template<typename T>
 	static ReturnValue_t serialize(const T *object, uint8_t **buffer,
 			size_t *size, size_t maxSize,
@@ -21,11 +37,35 @@ public:
 		return adapter.serialize(object, buffer, size, maxSize,
 				streamEndianness);
 	}
+	/**
+	 * Function to return the serialized size of the object in the pointer.
+	 * May be a trivially copy-able object or a Child of SerializeIF
+	 *
+	 * @param object Pointer to Object
+	 * @return Serialized size of object
+	 */
 	template<typename T>
-	static uint32_t getSerializedSize(const T *object) {
+	static size_t getSerializedSize(const T *object){
 		InternalSerializeAdapter<T, std::is_base_of<SerializeIF, T>::value> adapter;
 		return adapter.getSerializedSize(object);
 	}
+	/**
+	 * @brief
+	 * Deserializes a object from a given buffer of given size.
+	 * Object Must be trivially copy-able or a child of SerializeIF.
+	 *
+	 * @details
+	 * Buffer will be moved to the current read location. Size will be decreased by the function.
+	 *
+	 * @param[in/out] buffer Buffer to deSerialize from. Will be moved by the function.
+	 * @param[in/out] size Remaining size of the buffer to read from. Will be decreased by function.
+	 * @param[in] streamEndianness Endianness as in according to SerializeIF::Endianness
+	 * @return
+	 * 	- @c STREAM_TOO_SHORT The input stream is too short to deSerialize the object
+	 * 	- @c TOO_MANY_ELEMENTS The buffer has more inputs than expected
+	 * 	- @c RETURN_FAILED Generic Error
+	 * 	- @c RETURN_OK Successful deserialization
+	 */
 	template<typename T>
 	static ReturnValue_t deSerialize(T *object, const uint8_t **buffer,
 			size_t *size, SerializeIF::Endianness streamEndianness) {
@@ -33,16 +73,26 @@ public:
 		return adapter.deSerialize(object, buffer, size, streamEndianness);
 	}
 private:
+	/**
+	 * Internal template to deduce the right function calls at compile time
+	 */
 	template<typename T, bool> class InternalSerializeAdapter;
 
+	/**
+	 * Template to be used if T is not a child of SerializeIF
+	 *
+	 * @tparam T T must be trivially_copyable
+	 */
 	template<typename T>
 	class InternalSerializeAdapter<T, false> {
+		static_assert (std::is_trivially_copyable<T>::value,
+				"If a type needs to be serialized it must be a child of SerializeIF or trivially copy-able");
 	public:
 		static ReturnValue_t serialize(const T *object, uint8_t **buffer,
 				size_t *size, size_t max_size,
 				SerializeIF::Endianness streamEndianness) {
 			size_t ignoredSize = 0;
-			if (size == NULL) {
+			if (size == nullptr) {
 				size = &ignoredSize;
 			}
 			//Check remaining size is large enough and check integer overflow of *size
@@ -101,6 +151,11 @@ private:
 		}
 	};
 
+	/**
+	 * Template for objects that inherit from SerializeIF
+	 *
+	 * @tparam T A child of SerializeIF
+	 */
 	template<typename T>
 	class InternalSerializeAdapter<T, true> {
 	public:
@@ -108,12 +163,12 @@ private:
 				size_t max_size,
 				SerializeIF::Endianness streamEndianness) const {
 			size_t ignoredSize = 0;
-			if (size == NULL) {
+			if (size == nullptr) {
 				size = &ignoredSize;
 			}
 			return object->serialize(buffer, size, max_size, streamEndianness);
 		}
-		uint32_t getSerializedSize(const T *object) const {
+		size_t getSerializedSize(const T *object) const {
 			return object->getSerializedSize();
 		}
 
@@ -124,4 +179,4 @@ private:
 	};
 };
 
-#endif /* SERIALIZEADAPTER_H_ */
+#endif /* _FSFW_SERIALIZE_SERIALIZEADAPTER_H_ */
diff --git a/serialize/SerializeIF.h b/serialize/SerializeIF.h
index 7f9ea9df..a701fe53 100644
--- a/serialize/SerializeIF.h
+++ b/serialize/SerializeIF.h
@@ -43,7 +43,7 @@ public:
 	 * @param[in] maxSize The size of the buffer that is allowed to be used for serialize.
 	 * @param[in] streamEndianness Endianness of the serialized data according to SerializeIF::Endianness
 	 * @return
-	 * 		- @¢ BUFFER_TOO_SHORT The given buffer in is too short
+	 * 		- @c BUFFER_TOO_SHORT The given buffer in is too short
 	 * 		- @c RETURN_FAILED Generic error
 	 * 		- @c RETURN_OK Successful serialization
 	 */