extended documentation

src/lib/ebus/data.h

@@ -29,7 +29,32 @@
 #include <vector>
 #include <map>
 
-/** \file data.h */
+/** @file data.h
+ * Classes, functions, and constants related to decoding/encoding of symbols
+ * on the eBUS to/from readable values.
+ *
+ * A @a DataField is either a @a SingleDataField or a list of
+ * @a SingleDataField instances in a @a DataFieldSet.
+ *
+ * A @a SingleDataField is either a string based one or a numeric one. Due to
+ * their text nature, date and time fields are also treated as
+ * @a StringDataField.
+ *
+ * The basic field types are just @a StringDataField, @a NumberDataField, and
+ * @a ValueListDataField. The particular eBUS specification types like e.g.
+ * @a D1C are defined by using one of these basic field types (see #BaseType)
+ * with certain flags, such as #BCD, #FIX, #REQ, see #dataType_s.
+ *
+ * The list of available base types is defined an array of #dataType_s
+ * structures and can easily be extended if necessary.
+ *
+ * Each @a DataField can be converted from a @a SymbolString to an
+ * @a ostringstream (see @a DataField#read() methods) or vice versa from an
+ * @a istringstream to a @a SymbolString (see @a DataField#write()).
+ *
+ * The @a DataFieldTemplates allow definition of derived types as well as
+ * combined types based on the list of available base types.
+ */
 
 using namespace std;
 
@@ -79,18 +104,18 @@ static const unsigned int DAY = 0x20; //!< forced value list defaulting to week
 static const unsigned int IGN = 0x40; //!< ignore value during read and write
 static const unsigned int FIX = 0x80; //!< fixed width formatting
 static const unsigned int REQ = 0x100;//!< value may not be NULL
-static const unsigned int HCD = 0x200; //!< binary representation is hex converted to decimal and interpreted as 2 digits (also requires @a BCD)
+static const unsigned int HCD = 0x200; //!< binary representation is hex converted to decimal and interpreted as 2 digits (also requires #BCD)
 
-/** The structure for defining field types with their properties. */
-typedef struct {
-	const char* name;                    //!< field identifier
-	const unsigned char bitCount;        //!< number of bits (maximum length if @a ADJ flag is set, must be multiple of 8 with flag @a BCD)
+/** The structure for defining data types with their properties. */
+typedef struct dataType_s {
+	const char* name;                    //!< data type identifier
+	const unsigned char bitCount;        //!< number of bits (maximum length if #ADJ flag is set, must be multiple of 8 with flag #BCD)
 	const BaseType type;                 //!< base data type
-	const unsigned short flags;          //!< flags (e.g. @a BCD)
-	const unsigned int replacement;      //!< replacement value (fill-up value for @a bt_str / @a bt_hexstr, no replacement if equal to @a minValueOrLength for @a bt_num)
+	const unsigned short flags;          //!< flags (like #BCD)
+	const unsigned int replacement;      //!< replacement value (fill-up value for #bt_str / #bt_hexstr, no replacement if equal to #minValueOrLength for #bt_num)
 	const unsigned int minValueOrLength; //!< minimum binary value (minimum length of string for @a StringDataField)
 	const unsigned int maxValueOrLength; //!< maximum binary value (maximum length of string for @a StringDataField)
-	const short divisorOrFirstBit;       //!< @a bt_number: divisor (negative for reciprocal) or offset to first bit (if (@a bitCount%8)!=0)
+	const short divisorOrFirstBit;       //!< #bt_num: divisor (negative for reciprocal) or offset to first bit (if (#bitCount%8)!=0)
 } dataType_t;
 
 /** the maximum allowed position within master or slave data. */

src/lib/ebus/message.h

@@ -27,7 +27,30 @@
 #include <deque>
 #include <map>
 
-/** \file message.h */
+/** @file message.h
+ * Classes, functions, and constants related to decoding/encoding of complete
+ * messages on the eBUS to/from readable values.
+ *
+ * A @a Message has a unique numeric key (see Message#getKey()) as well as a
+ * unique name and circuit (@see Message#getCircuit() and Message#getName()).
+ * The numeric key is built from the message type (active/passive, read/write),
+ * the source and destination address, the primary and secondary command byte,
+ * as well as additional command ID bytes (see Message#getId()).
+ *
+ * Whenever a @a Message gets decoded from a master and slave @a SymbolString
+ * (see Message#decode()), it stores these strings for later retrieval from
+ * cache (see Message#decodeLastData()).
+ *
+ * In order to make a @a Message available (see Message#isAvailable()) under
+ * certain conditions only, it may have assigned a @a Condition instance.
+ *
+ * A @a Condition is either a @a SimpleCondition referencing another
+ * @a Message, field, and field value, or a @a CombinedCondition referencing
+ * two or more other @a Condition instances.
+ *
+ * The @a MessageMap stores all @a Message and @a Condition instances by their
+ * unique keys, and also keeps track of messages with polling enabled.
+ */
 
 using namespace std;
 

src/lib/ebus/result.h

@@ -19,7 +19,13 @@
 #ifndef LIBEBUS_RESULT_H_
 #define LIBEBUS_RESULT_H_
 
-/** \file result.h */
+/** @file result.h
+ * Functions, and constants related to execution results.
+ *
+ * The #result_t codes defined here are used by many functions to emit the
+ * result of the function call. Zero and positive values indicate success,
+ * whereas negative values indicate failure.
+ */
 
 /** type for result code. */
 enum result_t {

src/lib/ebus/symbol.h

@@ -25,7 +25,41 @@
 #include <sstream>
 #include <queue>
 
-/** \file symbol.h */
+/** @file symbol.h
+ * Classes, functions, and constants related to symbols on the eBUS.
+ *
+ * The @a SymbolString class is used for escaping or unescaping a sequence of
+ * bytes in preparation for sending to the bus or after reception of bytes from
+ * the bus, as well as calculating and verifying the CRC of a message part.
+ *
+ * A message on the bus always consists of a command part, i.e. the data sent
+ * from a master to the bus. The command part starts with the sending master
+ * address followed by the destination address. Both addresses are not allowed
+ * to be escaped and whenever a #SYN symbol appears, the sending has to be
+ * treated as timed out, as only the auto-SYN generator will do so when there
+ * was no symbol on the bus for a certain period of time.
+ *
+ * The remaining bytes of the command part are the primary and secondary
+ * command byte, the number of data bytes, the data bytes themselves, and the
+ * final CRC.
+ *
+ * When the destination is the #BROADCAST address, then the messages consists
+ * of the command part only.
+ *
+ * When the destination address is a master (see @a isMaster()), the receiving
+ * master has to acknowledge the correct reception of the command with either
+ * the #ACK (if the CRC was valid) or the #NAK symbol (if the received CRC did
+ * not match the calculated one). In case of a non-acknowledge #NAK symbol, the
+ * command part has to be repeated once (and once only) by the sender.
+ *
+ * When the destination address is a slave, the receiving slave has to
+ * acknowledge the reception of the command as described above. After a
+ * positive #ACK symbol, the receiving slave has to send its response data.
+ * The response data consists of the number of data bytes, the data bytes
+ * themselves, and the final CRC. The sending master has to acknowledge the
+ * correct reception of the response as described above and in case of a
+ * non-acknowledge, the receiving slave has to repeat its data once.
+ */
 
 using namespace std;