Serialization documentation update

serialize/EndianSwapper.h

@@ -5,6 +5,10 @@
 #include <cstring>
 #include <iostream>
 
+/**
+ * @brief Can be used to swap endianness of data
+ *        into big endian
+ */
 class EndianSwapper {
 private:
 	EndianSwapper() {

serialize/SerialFixedArrayListAdapter.h

@@ -5,18 +5,18 @@
 #include <framework/serialize/SerialArrayListAdapter.h>
 
 /**
- * This adapter provides an interface for SerializeIF to serialize and deserialize
+ * @brief This adapter provides an interface for SerializeIF to serialize and deserialize
  *        buffers with a header containing the buffer length.
- *
+ * @details
- * Can be used by SerialLinkedListAdapter.
+ * Can be used by SerialLinkedListAdapter by using this type in
- *
+ * SerializeElement<>
  * Buffers with a size header inside that class can be declared with
- * SerialFixedArrayListAdapter<uint8_t,MAX_BUFFER_LENGTH,typeOfMaxData>.
+ * SerialFixedArrayListAdapter<bufferType,MAX_BUFFER_LENGTH,typeOfMaxData>.
  * typeOfMaxData specifies the data type of the buffer header containing the buffer size that follows
  * and MAX_BUFFER_LENGTH specifies the maximum allowed value for the buffer size.
  * The sequence of objects is defined in the constructor by using the setStart and setNext functions.
  *
- * \ingroup serialize
+ * @ingroup serialize
  */
 template<typename T, uint32_t MAX_SIZE, typename count_t = uint8_t>
 class SerialFixedArrayListAdapter : public FixedArrayList<T, MAX_SIZE, count_t>, public SerializeIF {

serialize/SerialLinkedListAdapter.h

@@ -14,29 +14,30 @@
 //This is where we need the SerializeAdapter!
 
  /**
- * An alternative to the AutoSerializeAdapter functions to implement the conversion
+ * @brief  	Implement the conversion of object data to data streams
- * of object data to data streams or vice-versa, using linked lists.
+ * 		   	or vice-versa, using linked lists.
+ * @details
+ * An alternative to the AutoSerializeAdapter functions
+ *   - All object members with a datatype are declared as SerializeElement<element_type>
+ * 	   inside the class implementing this adapter.
+ *   - The element type can also be a SerialBufferAdapter to de-/serialize buffers,
+ *     with a known size, where the size can also be serialized
+ *   - The element type can also be a SerialFixedArrayListAdapter to de-/serialize buffers
+ *     with a size header, which is scanned automatically
  *
- * All object members with a datatype are declared as SerializeElement<element_type> inside the class
+ * The sequence of objects is defined in the constructor by using
- * implementing this adapter.
+ * the setStart and setNext functions.
  *
- * Buffers with a size header inside that class can be declared with
+ * - The serialization process is done by instantiating the class and
- * SerialFixedArrayListAdapter<uint8_t,MAX_BUFFER_LENGTH,typeOfMaxData>.
+ *   calling the serialize after all SerializeElement entries have been set by
- * typeOfMaxData specifies the data type of the buffer header containing the buffer size that follows
+ *   using a constructor or setter functions. An additional size variable can be supplied
- * and MAX_BUFFER_LENGTH specifies the maximum allowed value for the buffer size.
+ *   which is calculated/incremented automatically
- * Please note that a direct link from a linked element to a SerialFixedArrayListAdapter element is not possible and a
+ * - The deserialization process is done by instantiating the class and supplying
- * helper needs to be used by calling <LinkedElement>.setNext(&linkHelper)
+ *   a buffer with the data which is converted into an object. The size of
- * and initialising the link helper as linkHelper(&SerialFixedArrayListAdapterElement).
+ *   data to serialize can be supplied and is decremented in the function
  *
- * For buffers with no size header, declare
- * SerializeElement<SerializeBufferAdapter<T>> and initialise the buffer adapter in the constructor.
  *
- * The sequence of objects is defined in the constructor by using the setStart and setNext functions.
+ * @ingroup serialize
- *
- * The serialization and deserialization process is done by instantiating the class and
- * calling the serialize or deserialize function.
- *
- * \ingroup serialize
  */
 template<typename T, typename count_t = uint8_t>
 class SerialLinkedListAdapter: public SinglyLinkedList<T>, public SerializeIF {
@@ -53,6 +54,16 @@ public:
 			SinglyLinkedList<T>(), printCount(printCount) {
 	}
 
+	/**
+	 * Serialize object implementing this adapter into the supplied buffer
+	 * and calculate the serialized size
+	 * @param buffer [out] Object is serialized into this buffer. Note that the buffer pointer
+	 *               *buffer is incremented automatically inside the respective serialize functions
+	 * @param size [out] Calculated serialized size. Don't forget to set to 0.
+	 * @param max_size
+	 * @param bigEndian Specify endianness
+	 * @return
+	 */
 	virtual ReturnValue_t serialize(uint8_t** buffer, uint32_t* size,
 			const uint32_t max_size, bool bigEndian) const {
 		if (printCount) {
@@ -95,6 +106,13 @@ public:
 		return size;
 	}
 
+	/**
+	 * Deserialize supplied buffer with supplied size into object implementing this adapter
+	 * @param buffer
+	 * @param size Decremented in respective deSerialize functions automatically
+	 * @param bigEndian Specify endianness
+	 * @return
+	 */
 	virtual ReturnValue_t deSerialize(const uint8_t** buffer, int32_t* size,
 			bool bigEndian) {
 		return deSerialize(SinglyLinkedList<T>::start, buffer, size, bigEndian);

serialize/SerializeAdapter.h

@@ -8,10 +8,10 @@
 #include <string.h>
 
  /**
- * This adapter provides an interface to use the SerializeIF functions
+ * @brief This adapter provides an interface to use the SerializeIF functions
  * 		  with arbitrary template objects to facilitate and simplify the serialization of classes
  * 		  with different multiple different data types into buffers vice-versa.
- *
+ * @details
  * Examples:
  * A report class is converted into a TM buffer. The report class implements a serialize functions and calls
  * the AutoSerializeAdapter::serialize function repeatedly on all object data fields.
@@ -49,7 +49,7 @@
  * When serializing for downlink, the packets are generally serialized assuming big endian data format
  * like seen in TmPacketStored.cpp for example.
  *
- * \ingroup serialize
+ * @ingroup serialize
  */
 template<typename T, int>
 class SerializeAdapter_ {
@@ -141,7 +141,7 @@ public:
 	}
 };
 
-
+// No type specification necessary here.
 class AutoSerializeAdapter {
 public:
 	template<typename T>

serialize/SerializeElement.h

@@ -6,7 +6,15 @@
 #include <utility>
 
 /**
- * \ingroup serialize
+ * @brief This class is used to mark datatypes for serialization with the
+ *        SerialLinkedListAdapter
+ * @details
+ * Used by declaring any arbitrary datatype with SerializeElement<T> myVariable,
+ * inside a SerialLinkedListAdapter implementation and setting the sequence
+ * of objects with setNext() and setStart().
+ * Serilization and Deserialization is then performed automatically in
+ * specified sequence order.
+ * @ingroup serialize
  */
 template<typename T>
 class SerializeElement : public SerializeIF, public LinkedElement<SerializeIF> {

serialize/SerializeIF.h

@@ -4,17 +4,18 @@
 #include <framework/returnvalues/HasReturnvaluesIF.h>
 
 /**
- * \defgroup serialize Serialization
+ * @defgroup serialize Serialization
  * Contains serialisation services.
  */
 
 /**
- * An interface for alle classes which require translation of objects data into data streams and vice-versa.
+ * @brief An interface for alle classes which require
- *
+ *        translation of objects data into data streams and vice-versa.
+ * @details
  * If the target architecture is little endian (e.g. ARM), any data types created might
  * have the wrong endiness if they are to be used for the FSFW.
- * There are three ways to retrieve data out of a buffer to be used in the FSFW to use regular aligned (big endian) data.
+ * There are three ways to retrieve data out of a buffer to be used in the FSFW to use
- * This can also be applied to uint32_t and uint64_t:
+ * regular aligned (big endian) data. This can also be applied to uint32_t and uint64_t:
  *
  *   1. Use the @c AutoSerializeAdapter::deSerialize function with @c bigEndian = true
  *   2. Perform a bitshift operation
@@ -23,7 +24,7 @@
  * When serializing for downlink, the packets are generally serialized assuming big endian data format
  * like seen in TmPacketStored.cpp for example.
  *
- * \ingroup serialize
+ * @ingroup serialize
  */
 class SerializeIF {
 public: