Revision 46:f652d199d27e, committed 2015-05-21

Comitter:

Alex Young

Date:

Thu May 21 16:30:21 2015 +0200

Parent:

45:67203918bec9

Child:

47:c4610a65dade

Commit message:

Add documentation for xbusparser

Changed in this revision

--- a/xbus/xbusparser.c	Thu May 21 16:14:14 2015 +0200
+++ b/xbus/xbusparser.c	Thu May 21 16:30:21 2015 +0200
@@ -19,6 +19,7 @@
 #include <stdlib.h>
 #include <string.h>
 
+/*! \brief XbusParser states. */
 enum XbusParserState
 {
 	XBPS_Preamble,          /*!< \brief Looking for preamble. */
@@ -31,20 +32,39 @@
 	XBPS_Checksum           /*!< \brief Waiting for checksum. */
 };
 
+/*!
+ * \brief Xbus Parser state structure.
+ */
 struct XbusParser
 {
+	/*! \brief Callbacks for memory management, and message handling. */
 	struct XbusParserCallback callbacks;
+	/*! \brief Storage for the current message being received. */
 	struct XbusMessage currentMessage;
+	/*! \brief The number of bytes of payload received for the current message. */
 	uint16_t payloadReceived;
+	/*! \brief The calculated checksum for the current message. */
 	uint8_t checksum;
+	/*! \brief The state of the parser. */
 	enum XbusParserState state;
 };
 
+/*!
+ * \brief Get the amount of memory needed for the XbusParser structure.
+ */
 size_t XbusParser_mem(void)
 {
 	return sizeof(struct XbusParser);
 }
 
+/*!
+ * \brief Create a new XbusParser object.
+ * \param callback Pointer to callback structure containing callback functions
+ * for memory management and handling received messages.
+ * \returns Pointer the new XbusParser structure.
+ *
+ * Uses malloc to allocate the memory required for the parser.
+ */
 struct XbusParser* XbusParser_create(struct XbusParserCallback const* callback)
 {
 	void* mem = malloc(XbusParser_mem());
@@ -55,11 +75,22 @@
 	return NULL;
 }
 
+/*!
+ * \brief Frees an XbusParser structure allocated by XbusParser_create().
+ */
 void XbusParser_destroy(struct XbusParser* parser)
 {
 	free(parser);
 }
 
+/*!
+ * \brief Initializes an XbusParser in the passed memory location.
+ * \param parserMem Pointer to memory to use for storing parser state. Should
+ * be at least as big as the value returned by XbusParser_mem().
+ * \param callback Pointer to callback structure containing callback functions
+ * for memory management and handling received messages.
+ * \returns Initialized XbusParser structure.
+ */
 struct XbusParser* XbusParser_init(void* parserMem, struct XbusParserCallback const* callback)
 {
 	struct XbusParser* parser = (struct XbusParser*)parserMem;
@@ -70,6 +101,11 @@
 	return parser;
 }
 
+/*!
+ * \brief Parse a XMID_DeviceId message to extract the device ID value.
+
+ * Replaces the raw Xbus message data with the device ID.
+ */
 static void parseDeviceId(struct XbusParser* parser, uint8_t const* rawData)
 {
 	uint32_t* deviceId = parser->callbacks.allocateBuffer(sizeof(uint32_t));
@@ -85,6 +121,12 @@
 	}
 }
 
+/*!
+ * \brief Parse a XMID_OutputConfig message.
+ *
+ * Replaces the raw Xbus message data with an array of OutputConfiguration
+ * structures.
+ */
 static void parseOutputConfig(struct XbusParser* parser, uint8_t const* rawData)
 {
 	uint8_t fields = parser->currentMessage.length / 4;
@@ -107,6 +149,13 @@
 	}
 }
 
+/*!
+ * \brief Converts raw Xbus payload data to native structures if possible.
+ *
+ * Raw data payloads are converted to native data structures and the
+ * message data pointer is changed to point to the native structure.
+ * The raw data is automatically deallocated.
+ */
 static void parseMessagePayload(struct XbusParser* parser)
 {
 	uint8_t const* const rawData = parser->currentMessage.data;
@@ -129,12 +178,24 @@
 		parser->callbacks.deallocateBuffer(rawData);
 }
 
+/*!
+ * \brief Prepare for receiving a message payload.
+ *
+ * Requests a memory area to store the received data to using the
+ * registered callbacks.
+ */
 void prepareForPayload(struct XbusParser* parser)
 {
 	parser->payloadReceived = 0;
 	parser->currentMessage.data = parser->callbacks.allocateBuffer(parser->currentMessage.length);
 }
 
+/*!
+ * \brief Parse a byte of data from a motion tracker.
+ *
+ * When a complete message is received the user will be notified by a call
+ * to the handleMessage() callback function.
+ */
 void XbusParser_parseByte(struct XbusParser* parser, const uint8_t byte)
 {
 	switch (parser->state)
@@ -221,6 +282,9 @@
 	}
 }
 
+/*!
+ * \brief Parse a buffer of data received from a motion tracker.
+ */
 void XbusParser_parseBuffer(struct XbusParser* parser, uint8_t const* buf, size_t bufSize)
 {
 	for (size_t i = 0; i < bufSize; ++i)

--- a/xbus/xbusparser.h	Thu May 21 16:14:14 2015 +0200
+++ b/xbus/xbusparser.h	Thu May 21 16:30:21 2015 +0200
@@ -26,6 +26,9 @@
 
 struct XbusParser;
 
+/*!
+ * \brief Callback function structure for use with the XbusParser.
+ */
 struct XbusParserCallback
 {
 	/*!