Revision 48:69d35430fe8b, committed 2015-05-21

Comitter:

Alex Young

Date:

Thu May 21 16:45:07 2015 +0200

Parent:

47:c4610a65dade

Child:

49:38ecfbff5391

Commit message:

Add documentation for xbusmessage

Changed in this revision

--- a/xbus/xbusmessage.c	Thu May 21 16:32:53 2015 +0200
+++ b/xbus/xbusmessage.c	Thu May 21 16:45:07 2015 +0200
@@ -17,6 +17,9 @@
 #include "xbusdef.h"
 #include "xbusutility.h"
 
+/*!
+ * \brief Calculate the number of bytes needed for \a message payload.
+ */
 static uint16_t messageLength(struct XbusMessage const* message)
 {
 	switch (message->mid)
@@ -29,6 +32,9 @@
 	}
 }
 
+/*!
+ * \brief Format a message with a pointer to an array of OutputConfiguration elements.
+ */
 static void formatOutputConfig(uint8_t* raw, struct XbusMessage const* message)
 {
 	struct OutputConfiguration* conf = message->data;
@@ -40,6 +46,10 @@
 	}
 }
 
+/*!
+ * \brief Format the payload of a message from a native data type to
+ * raw bytes.
+ */
 static void formatPayload(uint8_t* raw, struct XbusMessage const* message)
 {
 	switch (message->mid)
@@ -57,6 +67,10 @@
 	}
 }
 
+/*!
+ * \brief Format a message into the raw Xbus format ready for transmission to
+ * a motion tracker.
+ */
 size_t XbusMessage_format(uint8_t* raw, struct XbusMessage const* message)
 {
 	uint8_t* dptr = raw;
@@ -96,6 +110,14 @@
 	return dptr - raw;
 }
 
+/*!
+ * \brief Get a pointer to the data correspondind to \a id.
+ * \param id The data identifier to find in the message.
+ * \param data Pointer to the raw message payload.
+ * \param dataLength The length of the payload in bytes.
+ * \returns Pointer to data item, or NULL if the identifier is not present in
+ * the message.
+ */
 static uint8_t const* getPointerToData(enum XsDataIdentifier id, uint8_t const* data, uint16_t dataLength)
 {
 	uint8_t const* dptr = data;
@@ -114,6 +136,12 @@
 	return NULL;
 }
 
+/*!
+ * \brief Read a number of floats from a message payload.
+ * \param out Pointer to where to output data.
+ * \param raw Pointer to the start of the raw float data.
+ * \param floats The number of floats to read.
+ */
 static void readFloats(float* out, uint8_t const* raw, uint8_t floats)
 {
 	for (int i = 0; i < floats; ++i)
@@ -122,6 +150,13 @@
 	}
 }
 
+/*!
+ * \brief Get a data item from a XMID_MtData2 Xbus message.
+ * \param item Pointer to where to store the data.
+ * \param id The data identifier to get.
+ * \param message The message to read the data item from.
+ * \returns true if the data item is found in the message, else false.
+ */
 bool XbusMessage_getDataItem(void* item, enum XsDataIdentifier id, struct XbusMessage const* message)
 {
 	uint8_t const* raw = getPointerToData(id, message->data, message->length);
@@ -161,6 +196,9 @@
 	}
 }
 
+/*!
+ * \brief Get a string descriptions for the passed data identifier.
+ */
 char const* XbusMessage_dataDescription(enum XsDataIdentifier id)
 {
 	switch (id)

--- a/xbus/xbusmessage.h	Thu May 21 16:32:53 2015 +0200
+++ b/xbus/xbusmessage.h	Thu May 21 16:45:07 2015 +0200
@@ -24,6 +24,7 @@
 extern "C" {
 #endif
 
+/*! \brief Xbus message IDs. */
 enum XsMessageId
 {
 	XMID_Wakeup             = 0x3E,
@@ -43,6 +44,7 @@
 	XMID_Error              = 0x42,
 };
 
+/*! \brief Xbus data message type IDs. */
 enum XsDataIdentifier
 {
 	XDI_PacketCounter  = 0x1020,
@@ -56,16 +58,36 @@
 	XDI_StatusWord     = 0xE020,
 };
 
+/*!
+ * \brief An Xbus message structure with optional payload.
+ */
 struct XbusMessage
 {
+	/*! \brief The message ID of the message. */
 	enum XsMessageId mid;
+	/*!
+	 * \brief The length of the payload.
+	 *
+	 * \note The meaning of the length is message dependent. For example,
+	 * for XMID_OutputConfig messages it is the number of OutputConfiguration
+	 * elements in the configuration array.
+	 */
 	uint16_t length;
+	/*! \brief Pointer to the payload data. */
 	void* data;
 };
 
+/*!
+ * \brief Output configuration structure.
+ */
 struct OutputConfiguration
 {
+	/*! \brief Data type of the output. */
 	enum XsDataIdentifier dtype;
+	/*!
+	 * \brief The output frequency in Hz, or 65535 if the value should be
+	 * included in every data message.
+	 */
 	uint16_t freq;
 };