taken over from upstream with little tweak

serialize/SerializeIF.h

@@ -1,34 +1,19 @@
-#ifndef SERIALIZEIF_H_
+#ifndef FSFW_SERIALIZE_SERIALIZEIF_H_
-#define SERIALIZEIF_H_
+#define FSFW_SERIALIZE_SERIALIZEIF_H_
 
 #include "../returnvalues/HasReturnvaluesIF.h"
 #include <cstddef>
 
 /**
  * @defgroup serialize Serialization
- * Contains serialisation services.
+ * Contains serialization services.
  */
 
 /**
- * @brief An interface for alle classes which require
+ * @brief 	Translation of objects into data streams and from data streams.
- *        translation of objects data into data streams and vice-versa.
  * @details
- * If the target architecture is little endian (e.g. ARM), any data types
+ * Also provides options to convert from/to data with different endianness.
- * created might  have the wrong endianess if they are to be used for the FSFW.
+ * variables.
- * Depending on the system architecture, endian correctness must be assured,
- * This is important for incoming and outgoing data. The internal handling
- * of data should be performed in the native system endianness.
- * There are three ways to copy data (with different options to ensure
- * endian correctness):
- *
- *   1. Use the @c AutoSerializeAdapter::deSerialize function (with
- *      the endian flag)
- *   2. Perform a bitshift operation (with correct order)
- *   3. @c memcpy (with @c EndianSwapper if necessary)
- *
- * When serializing for downlink, the packets are generally serialized
- * assuming big endian data format like seen in TmPacketStored.cpp for example.
- *
  * @ingroup serialize
  */
 class SerializeIF {
@@ -38,21 +23,65 @@ public:
 	};
 
 	static const uint8_t INTERFACE_ID = CLASS_ID::SERIALIZE_IF;
-	static const ReturnValue_t BUFFER_TOO_SHORT = MAKE_RETURN_CODE(1);
+	static const ReturnValue_t BUFFER_TOO_SHORT = MAKE_RETURN_CODE(1); // !< The given buffer in serialize is too short
-	static const ReturnValue_t STREAM_TOO_SHORT = MAKE_RETURN_CODE(2);
+	static const ReturnValue_t STREAM_TOO_SHORT = MAKE_RETURN_CODE(2); // !< The input stream in deserialize is too short
-	static const ReturnValue_t TOO_MANY_ELEMENTS = MAKE_RETURN_CODE(3);
+	static const ReturnValue_t TOO_MANY_ELEMENTS = MAKE_RETURN_CODE(3);// !< There are too many elements to be deserialized
 
 	virtual ~SerializeIF() {
 	}
-
+	/**
+	 * @brief
+	 * Function to serialize the object into a buffer with maxSize. Size represents the written amount.
+	 * If a part of the buffer has been used already, size must be set to the used amount of bytes.
+	 *
+	 * @details
+	 * Implementations of this function must increase the size variable and move the buffer pointer.
+	 * MaxSize must be checked by implementations of this function
+	 * and BUFFER_TOO_SHORT has to be returned if size would be larger than maxSize.
+	 *
+	 * Custom implementations might use additional return values.
+	 *
+	 * @param[in/out] buffer Buffer to serialize into, will be set to the current write location
+	 * @param[in/out] size Size that has been used in the buffer already, will be increased by the function
+	 * @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 RETURN_FAILED Generic error
+	 * 		- @c RETURN_OK Successful serialization
+	 */
 	virtual ReturnValue_t serialize(uint8_t **buffer, size_t *size,
 			size_t maxSize, Endianness streamEndianness) const = 0;
 
+	/**
+	 * Gets the size of a object if it would be serialized in a buffer
+	 * @return Size of serialized object
+	 */
 	virtual size_t getSerializedSize() const = 0;
 
+	/**
+	 * @brief
+	 * Deserializes a object from a given buffer of given size.
+	 *
+	 * @details
+	 * Buffer must be moved to the current read location by the implementation
+	 * of this function. Size must be decreased by the implementation.
+	 * Implementations are not allowed to alter the buffer as indicated by const pointer.
+	 *
+	 * Custom implementations might use additional return values.
+	 *
+	 * @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
+	 */
 	virtual ReturnValue_t deSerialize(const uint8_t **buffer, size_t *size,
 			Endianness streamEndianness) = 0;
 
 };
 
-#endif /* SERIALIZEIF_H_ */
+#endif /* FSFW_SERIALIZE_SERIALIZEIF_H_ */