From 743d8abeaffe55cefbddbd2b264be4adcac4d19c Mon Sep 17 00:00:00 2001
From: "Robin.Mueller" <robin.mueller.m@gmail.com>
Date: Thu, 17 Oct 2019 00:23:46 +0200
Subject: [PATCH] first attempt to document and explain serialization tools for
 application developers

---
 serialize/SerialLinkedListAdapter.h | 16 +++++++++++++++-
 serialize/SerializeAdapter.h        | 14 +++++++++++++-
 serialize/SerializeIF.h             |  2 +-
 3 files changed, 29 insertions(+), 3 deletions(-)

diff --git a/serialize/SerialLinkedListAdapter.h b/serialize/SerialLinkedListAdapter.h
index 29952c4a..44d9e15b 100644
--- a/serialize/SerialLinkedListAdapter.h
+++ b/serialize/SerialLinkedListAdapter.h
@@ -13,7 +13,21 @@
 #include <framework/serialize/SerializeIF.h>
 //This is where we need the SerializeAdapter!
 
-/**
+ /**
+ * An alternative to the AutoSerializeAdapter functions to implement the conversion
+ * of object data to data streams or vice-versa, using linked lists.
+ *
+ * All object members with a datatype are declared as SerializeElement<element_type> inside the class.
+ *
+ * Buffers with a size header inside that class can be declared with
+ * SerialFixedArrayListAdapter<uint8_t,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.
+ *
+ * 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>
diff --git a/serialize/SerializeAdapter.h b/serialize/SerializeAdapter.h
index fd9e1b6a..67c37493 100644
--- a/serialize/SerializeAdapter.h
+++ b/serialize/SerializeAdapter.h
@@ -7,7 +7,19 @@
 #include <framework/serialize/SerializeIF.h>
 #include <string.h>
 
-/**
+ /**
+ * 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.
+ *
+ * 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.
+ * The getSerializedSize function is implemented by calling the
+ * AutoSerializeAdapter::getSerializedSize function repeatedly on all data fields.
+ *
+ * The AutoSerializeAdapter functions can also be used as an alternative to memcpy
+ * to retrieve data out of a buffer directly into a class variable with data type T while being able to specify endianness.
  * \ingroup serialize
  */
 template<typename T, int>
diff --git a/serialize/SerializeIF.h b/serialize/SerializeIF.h
index 701fbf56..50555d37 100644
--- a/serialize/SerializeIF.h
+++ b/serialize/SerializeIF.h
@@ -9,7 +9,7 @@
  */
 
 /**
- * Translation of objects into data streams.
+ * An interface for alle classes which require translation of objects data into data streams and vice-versa.
  * \ingroup serialize
  */
 class SerializeIF {