Revision 45:67203918bec9, committed 2015-05-21

Comitter:

Alex Young

Date:

Thu May 21 16:14:14 2015 +0200

Parent:

44:b3980e8ac074

Child:

46:f652d199d27e

Commit message:

Documentation of xbuf definitions and utility functions

Changed in this revision

--- a/xbus/xbusdef.h	Thu May 21 16:01:20 2015 +0200
+++ b/xbus/xbusdef.h	Thu May 21 16:14:14 2015 +0200
@@ -16,9 +16,13 @@
 #ifndef __XBUSDEF_H
 #define __XBUSDEF_H
 
+/*! \brief Xbus message preamble byte. */
 #define XBUS_PREAMBLE (0xFA)
+/*! \brief Xbus message bus ID for standalone application. */
 #define XBUS_BUS_ID_STANDALONE (0xFF)
+/*! \brief Xbus length byte for messages without payload. */
 #define XBUS_NO_PAYLOAD (0x00)
+/*! \brief Xbus length byte for message with an extended payload. */
 #define XBUS_EXTENDED_LENGTH (0xFF)
 
 #endif // __XBUSDEF_H

--- a/xbus/xbusutility.c	Thu May 21 16:01:20 2015 +0200
+++ b/xbus/xbusutility.c	Thu May 21 16:14:14 2015 +0200
@@ -15,30 +15,65 @@
 
 #include "xbusutility.h"
 
+/*!
+ * \name Xbus message reading utility functions.
+ * Xbus messages use big-endian representations for multibyte data.
+ * These functions help in reading data from an Xbus message and converting
+ * it to a native type.
+ *
+ * The functions are intended to scan over a message as follows:
+ * \code{.c}
+ * void readValues(XbusMessage const* message)
+ * {
+ *     uint16_t v1;
+ *     uint8_t v2;
+ *     uint32_t v3;
+ *     uint8_t* dptr = message->data;
+ *     dptr = XbusUtility_readU16(&v1, dptr);
+ *     dptr = XbusUtility_readU8(&v2, dptr);
+ *     dptr = XbusUtility_readU32(&v3, dptr);
+ * }
+ * \endcode
+ * \{
+ */
+/*!
+ * \brief Read a uint8_t value from an Xbus message.
+ */
 uint8_t const* XbusUtility_readU8(uint8_t* out, uint8_t const* in)
 {
 	*out = *in;
 	return ++in;
 }
 
+/*! \brief Read a uint16_t value from an Xbus message. */
 uint8_t const* XbusUtility_readU16(uint16_t* out, uint8_t const* in)
 {
 	*out = (in[0] << 8) | in[1];
 	return in + sizeof(uint16_t);
 }
 
+/*! \brief Read a uint32_t value from an Xbus message. */
 uint8_t const* XbusUtility_readU32(uint32_t* out, uint8_t const* in)
 {
 	*out = (in[0] << 24) | (in[1] << 16) | (in[2] << 8) | in[3];
 	return in + sizeof(uint32_t);
 }
+/*! \} */
 
+/*!
+ * \brief Xbus message writing utility functions.
+ * These functions aid in writing native values to big-endian xbus message
+ * payloads. See corresponding reading functions for further details.
+ * \{
+ */
+/*! \brief Write a uint8_t value to an Xbus message. */
 uint8_t* XbusUtility_writeU8(uint8_t* out, uint8_t in)
 {
 	*out++ = in;
 	return out;
 }
 
+/*! \brief Write a uint16_t value to an Xbus message. */
 uint8_t* XbusUtility_writeU16(uint8_t* out, uint16_t in)
 {
 	*out++ = (in >> 8) & 0xFF;
@@ -46,12 +81,13 @@
 	return out;
 }
 
+/*! \brief Write a uint32_t value to an Xbus message. */
 uint8_t* XbusUtility_writeU32(uint8_t* out, uint32_t in)
 {
-
 	*out++ = (in >> 24) & 0xFF;
 	*out++ = (in >> 16) & 0xFF;
 	*out++ = (in >> 8) & 0xFF;
 	*out++ = in & 0xFF;
 	return out;
 }
+/*! \}  */