From 7539aa70a845623473b6e88e8514be92b6e37404 Mon Sep 17 00:00:00 2001
From: Ryan McLean <pvtryan100@gmail.com>
Date: Wed, 2 Nov 2016 10:11:26 +0000
Subject: [PATCH 4/4] Added more comments for deoxygen

---
 .gitignore           |   1 +
 src/ringbuffer.h     |  36 +++++++-
 src/serial.h         | 226 +++++++++++++++++++++++++--------------------------
 src/suunto_common.h  |  32 +++++++-
 src/suunto_common2.h |  79 +++++++++++++++---
 src/usbhid.h         |  70 ++++++++--------
 6 files changed, 282 insertions(+), 162 deletions(-)

diff --git a/.gitignore b/.gitignore
index 543d9f8..d4bc3ae 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,6 +6,7 @@
 *.rej
 *.exe
 .*.swp
+*.gch
 .deps/
 .libs/
 compile
diff --git a/src/ringbuffer.h b/src/ringbuffer.h
index 3915739..fbabf28 100644
--- a/src/ringbuffer.h
+++ b/src/ringbuffer.h
@@ -18,7 +18,9 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  * MA 02110-1301 USA
  */
-
+/** \file ringbuffer.h
+ * \brief
+ */
 #ifndef RINGBUFFER_H
 #define RINGBUFFER_H
 
@@ -26,15 +28,47 @@
 extern "C" {
 #endif /* __cplusplus */
 
+/** \fn ringbuffer_normalize (unsigned int a, unsigned int begin, unsigned int end);
+ * \brief
+ * \param a
+ * \param begin
+ * \param end
+ * \return unsigned int
+ */
 unsigned int
 ringbuffer_normalize (unsigned int a, unsigned int begin, unsigned int end);
 
+/** \fn ringbuffer_distance (unsigned int a, unsigned int b, int mode, unsigned int begin, unsigned int end);
+ * \brief
+ * \param a
+ * \param b
+ * \param mode
+ * \param begin
+ * \param end
+ * \return unsigned int
+ */
 unsigned int
 ringbuffer_distance (unsigned int a, unsigned int b, int mode, unsigned int begin, unsigned int end);
 
+/** \fn ringbuffer_increment (unsigned int a, unsigned int delta, unsigned int begin, unsigned int end);
+ * \brief
+ * \param a
+ * \param delta
+ * \param begin
+ * \param end
+ * \return unsigned int
+ */
 unsigned int
 ringbuffer_increment (unsigned int a, unsigned int delta, unsigned int begin, unsigned int end);
 
+/** \fn ringbuffer_decrement (unsigned int a, unsigned int delta, unsigned int begin, unsigned int end);
+ * \brief
+ * \param a
+ * \param delta
+ * \param begin
+ * \param end
+ * \return unsigned int
+ */
 unsigned int
 ringbuffer_decrement (unsigned int a, unsigned int delta, unsigned int begin, unsigned int end);
 
diff --git a/src/serial.h b/src/serial.h
index ac94ec8..02558c7 100644
--- a/src/serial.h
+++ b/src/serial.h
@@ -18,7 +18,9 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  * MA 02110-1301 USA
  */
-
+ /** \file serial.h
+  * \brief Header file for serial communications
+  */
 #ifndef DC_SERIAL_H
 #define DC_SERIAL_H
 
@@ -29,13 +31,13 @@
 extern "C" {
 #endif /* __cplusplus */
 
-/**
- * Opaque object representing a serial connection.
+/** \struct dc_serial_t
+ * \brief Opaque object representing a serial connection.
  */
 typedef struct dc_serial_t dc_serial_t;
 
-/**
- * The parity checking scheme.
+/** \enum dc_parity_t
+ * \brief The parity checking scheme.
  */
 typedef enum dc_parity_t {
 	DC_PARITY_NONE, /**< No parity */
@@ -45,8 +47,8 @@ typedef enum dc_parity_t {
 	DC_PARITY_SPACE /**< Space parity (alwasy 0) */
 } dc_parity_t;
 
-/**
- * The number of stop bits.
+/** \enum dc_stopbits_t
+ * \brief The number of stop bits.
  */
 typedef enum dc_stopbits_t {
 	DC_STOPBITS_ONE,          /**< 1 stop bit */
@@ -54,8 +56,8 @@ typedef enum dc_stopbits_t {
 	DC_STOPBITS_TWO           /**< 2 stop bits */
 } dc_stopbits_t;
 
-/**
- * The flow control.
+/** \enum dc_flowcontrol_t
+ * \brief The flow control.
  */
 typedef enum dc_flowcontrol_t {
 	DC_FLOWCONTROL_NONE,     /**< No flow control */
@@ -63,8 +65,8 @@ typedef enum dc_flowcontrol_t {
 	DC_FLOWCONTROL_SOFTWARE  /**< Software (XON/XOFF) flow control */
 } dc_flowcontrol_t;
 
-/**
- * The direction of the data transmission.
+/** \enum dc_direction_t
+ * \brief The direction of the data transmission.
  */
 typedef enum dc_direction_t {
 	DC_DIRECTION_INPUT = 0x01,  /**< Input direction */
@@ -72,8 +74,8 @@ typedef enum dc_direction_t {
 	DC_DIRECTION_ALL = DC_DIRECTION_INPUT | DC_DIRECTION_OUTPUT /**< All directions */
 } dc_direction_t;
 
-/**
- * The serial line signals.
+/** \enum dc_line_t
+ * \brief The serial line signals.
  */
 typedef enum dc_line_t {
 	DC_LINE_DCD = 0x01, /**< Data carrier detect */
@@ -82,64 +84,60 @@ typedef enum dc_line_t {
 	DC_LINE_RNG = 0x08, /**< Ring indicator */
 } dc_line_t;
 
-/**
- * Serial enumeration callback.
- *
- * @param[in]  name      The name of the device node.
- * @param[in]  userdata  The user data pointer.
+/** \typedef *dc_serial_callback_t
+ * \brief Serial enumeration callback.
+ * \param name The name of the device node.
+ * \param userdata The user data pointer.
  */
 typedef void (*dc_serial_callback_t) (const char *name, void *userdata);
 
-/**
- * Enumerate the serial ports.
- *
- * @param[in]  callback  The callback function to call.
- * @param[in]  userdata  User data to pass to the callback function.
- * @returns #DC_STATUS_SUCCESS on success, or another #dc_status_t code
+/** \fn dc_serial_enumerate (dc_serial_callback_t callback, void *userdata);
+ * \brief Enumerate the serial ports.
+ * \param callback The callback function to call.
+ * \param userdata User data to pass to the callback function.
+ * \return dc_status_t #DC_STATUS_SUCCESS on success, or another #dc_status_t code
  * on failure.
  */
 dc_status_t
 dc_serial_enumerate (dc_serial_callback_t callback, void *userdata);
 
-/**
- * Open a serial connection.
- *
- * @param[out]  serial   A location to store the serial connection.
- * @param[in]   context  A valid context object.
- * @param[in]   name     The name of the device node.
- * @returns #DC_STATUS_SUCCESS on success, or another #dc_status_t code
+/** \fn dc_serial_open (dc_serial_t **serial, dc_context_t *context, const char *name);
+ * \brief Open a serial connection.
+ * \param serial A location to store the serial connection.
+ * \param context A valid context object.
+ * \param name The name of the device node.
+ * \return dc_status_t #DC_STATUS_SUCCESS on success, or another #dc_status_t code
  * on failure.
  */
 dc_status_t
 dc_serial_open (dc_serial_t **serial, dc_context_t *context, const char *name);
 
-/**
- * Close the serial connection and free all resources.
- *
- * @param[in]  serial  A valid serial connection.
- * @returns #DC_STATUS_SUCCESS on success, or another #dc_status_t code
+/** \fn dc_serial_close (dc_serial_t *serial);
+ * \brief Close the serial connection and free all resources.
+ * \param serial A valid serial connection.
+ * \return dc_status_t #DC_STATUS_SUCCESS on success, or another #dc_status_t code
  * on failure.
  */
 dc_status_t
 dc_serial_close (dc_serial_t *serial);
 
-/**
- * Configure the serial line settings of the connection.
+/** \fn dc_serial_configure (dc_serial_t *serial, unsigned int baudrate, unsigned int databits, dc_parity_t parity, dc_stopbits_t stopbits, dc_flowcontrol_t flowcontrol);
+ * \brief Configure the serial line settings of the connection.
  *
- * @param[in]  serial       A valid serial connection.
- * @param[in]  baudrate     The baud rate setting.
- * @param[in]  databits     The number of data bits.
- * @param[in]  parity       The parity setting.
- * @param[in]  stopbits     The number of stop bits.
- * @param[in]  flowcontrol  The flow control setting.
- * @returns #DC_STATUS_SUCCESS on success, or another #dc_status_t code
+ * \param serial       A valid serial connection.
+ * \param baudrate     The baud rate setting.
+ * \param databits     The number of data bits.
+ * \param parity       The parity setting.
+ * \param stopbits     The number of stop bits.
+ * \param flowcontrol  The flow control setting.
+ * \return dc_status_t #DC_STATUS_SUCCESS on success, or another #dc_status_t code
  * on failure.
  */
 dc_status_t
 dc_serial_configure (dc_serial_t *serial, unsigned int baudrate, unsigned int databits, dc_parity_t parity, dc_stopbits_t stopbits, dc_flowcontrol_t flowcontrol);
 
-/**
- * Set the read timeout.
+/** \fn dc_serial_set_timeout (dc_serial_t *serial, int timeout);
+ * \brief Set the read timeout.
  *
  * There are three distinct modes available:
  *
@@ -161,155 +159,153 @@ dc_serial_configure (dc_serial_t *serial, unsigned int baudrate, unsigned int da
  *     within the specified amount of time, the operation will return
  *     with the bytes that have already been received.
  *
- * @param[in]  serial   A valid serial connection.
- * @param[in]  timeout  The timeout in milliseconds.
- * @returns #DC_STATUS_SUCCESS on success, or another #dc_status_t code
+ * \param serial   A valid serial connection.
+ * \param timeout  The timeout in milliseconds.
+ * \return dc_status_t #DC_STATUS_SUCCESS on success, or another #dc_status_t code
  * on failure.
  */
 dc_status_t
 dc_serial_set_timeout (dc_serial_t *serial, int timeout);
 
-/**
- * Set the state of the half duplex emulation.
+/** \fn dc_serial_set_halfduplex (dc_serial_t *serial, unsigned int value);
+ * \brief Set the state of the half duplex emulation.
  *
- * @param[in]  serial  A valid serial connection.
- * @param[in]  value   The half duplex state.
- * @returns #DC_STATUS_SUCCESS on success, or another #dc_status_t code
+ * \param serial  A valid serial connection.
+ * \param value   The half duplex state.
+ * \return dc_status_t #DC_STATUS_SUCCESS on success, or another #dc_status_t code
  * on failure.
  */
 dc_status_t
 dc_serial_set_halfduplex (dc_serial_t *serial, unsigned int value);
 
-/**
- * Set the receive latency.
+/** \fn dc_serial_set_latency (dc_serial_t *serial, unsigned int value);
+ * \brief Set the receive latency.
  *
  * The effect of this setting is highly platform and driver specific. On
  * Windows it does nothing at all, on Linux it controls the low latency
  * flag (e.g. only zero vs non-zero latency), and on Mac OS X it sets
  * the receive latency as requested.
  *
- * @param[in]  serial  A valid serial connection.
- * @param[in]  value   The latency in milliseconds.
- * @returns #DC_STATUS_SUCCESS on success, or another #dc_status_t code
+ * \param  serial  A valid serial connection.
+ * \param  value   The latency in milliseconds.
+ * \return dc_status_t #DC_STATUS_SUCCESS on success, or another #dc_status_t code
  * on failure.
  */
 dc_status_t
 dc_serial_set_latency (dc_serial_t *serial, unsigned int value);
 
-/**
- * Read data from the serial connection.
+/** \fn dc_serial_read (dc_serial_t *serial, void *data, size_t size, size_t *actual);
+ * \brief Read data from the serial connection.
  *
- * @param[in]  serial  A valid serial connection.
- * @param[out] data    The memory buffer to read the data into.
- * @param[in]  size    The number of bytes to read.
- * @param[out] actual  An (optional) location to store the actual
+ * \param serial  A valid serial connection.
+ * \param data    The memory buffer to read the data into.
+ * \param size    The number of bytes to read.
+ * \param actual  An (optional) location to store the actual
  *                     number of bytes transferred.
- * @returns #DC_STATUS_SUCCESS on success, or another #dc_status_t code
+ * \return dc_status_t #DC_STATUS_SUCCESS on success, or another #dc_status_t code
  * on failure.
  */
 dc_status_t
 dc_serial_read (dc_serial_t *serial, void *data, size_t size, size_t *actual);
 
-/**
- * Write data to the serial connection.
+/** \fn dc_serial_write (dc_serial_t *serial, const void *data, size_t size, size_t *actual);
+ * \brief Write data to the serial connection.
  *
- * @param[in]  serial  A valid serial connection.
- * @param[in]  data    The memory buffer to write the data from.
- * @param[in]  size    The number of bytes to write.
- * @param[out] actual  An (optional) location to store the actual
+ * \param serial  A valid serial connection.
+ * \param data    The memory buffer to write the data from.
+ * \param size    The number of bytes to write.
+ * \param actual  An (optional) location to store the actual
  *                     number of bytes transferred.
- * @returns #DC_STATUS_SUCCESS on success, or another #dc_status_t code
+ * \return dc_status_t #DC_STATUS_SUCCESS on success, or another #dc_status_t code
  * on failure.
  */
 dc_status_t
 dc_serial_write (dc_serial_t *serial, const void *data, size_t size, size_t *actual);
 
-/**
- * Flush the internal output buffer and wait until the data has been
- * transmitted.
+/** \fn dc_serial_flush (dc_serial_t *serial);
+ * \brief Flush the internal output buffer and wait until the data has been transmitted.
  *
- * @param[in]  serial  A valid serial connection.
- * @returns #DC_STATUS_SUCCESS on success, or another #dc_status_t code
+ * \param serial  A valid serial connection.
+ * \return dc_status_t #DC_STATUS_SUCCESS on success, or another #dc_status_t code
  * on failure.
  */
 dc_status_t
 dc_serial_flush (dc_serial_t *serial);
 
-/**
- * Discards all data from the internal buffers.
+/** \fn dc_serial_purge (dc_serial_t *serial, dc_direction_t direction);
+ * \brief Discards all data from the internal buffers.
  *
- * @param[in]  serial     A valid serial connection.
- * @param[in]  direction  The direction of the buffer(s).
- * @returns #DC_STATUS_SUCCESS on success, or another #dc_status_t code
+ * \param serial     A valid serial connection.
+ * \param direction  The direction of the buffer(s).
+ * \return dc_status_t #DC_STATUS_SUCCESS on success, or another #dc_status_t code
  * on failure.
  */
 dc_status_t
 dc_serial_purge (dc_serial_t *serial, dc_direction_t direction);
 
-/**
- * Set the state of the break condition.
+/** \fn dc_serial_set_break (dc_serial_t *serial, unsigned int value);
+ * \brief Set the state of the break condition.
  *
- * @param[in]  serial  A valid serial connection.
- * @param[in]  value   The break condition state.
- * @returns #DC_STATUS_SUCCESS on success, or another #dc_status_t code
+ * \param serial  A valid serial connection.
+ * \param value   The break condition state.
+ * \return dc_status_t #DC_STATUS_SUCCESS on success, or another #dc_status_t code
  * on failure.
  */
 dc_status_t
 dc_serial_set_break (dc_serial_t *serial, unsigned int value);
 
-/**
- * Set the state of the DTR line.
+/** \fn dc_serial_set_dtr (dc_serial_t *serial, unsigned int value);
+ * \brief Set the state of the DTR line.
  *
- * @param[in]  serial  A valid serial connection.
- * @param[in]  value   The DTR line state.
- * @returns #DC_STATUS_SUCCESS on success, or another #dc_status_t code
+ * \param serial  A valid serial connection.
+ * \param value   The DTR line state.
+ * \return dc_status_t #DC_STATUS_SUCCESS on success, or another #dc_status_t code
  * on failure.
  */
 dc_status_t
 dc_serial_set_dtr (dc_serial_t *serial, unsigned int value);
 
-/**
- * Set the state of the RTS line.
+/** \fn dc_serial_set_rts (dc_serial_t *serial, unsigned int value);
+ * \brief Set the state of the RTS line.
  *
- * @param[in]  serial  A valid serial connection.
- * @param[in]  value   The RTS line state.
- * @returns #DC_STATUS_SUCCESS on success, or another #dc_status_t code
+ * \param serial  A valid serial connection.
+ * \param value   The RTS line state.
+ * \return dc_status_t #DC_STATUS_SUCCESS on success, or another #dc_status_t code
  * on failure.
  */
 dc_status_t
 dc_serial_set_rts (dc_serial_t *serial, unsigned int value);
 
-/**
- * Query the number of available bytes in the input buffer.
+/** \fn dc_serial_get_available (dc_serial_t *serial, size_t *value);
+ * \brief Query the number of available bytes in the input buffer.
  *
- * @param[in]   serial  A valid serial connection.
- * @param[out]  value   A location to store the number of bytes in the
- *                      input buffer.
- * @returns #DC_STATUS_SUCCESS on success, or another #dc_status_t code
+ * \param serial  A valid serial connection.
+ * \param value   A location to store the number of bytes in the input buffer.
+ * \return dc_status_t #DC_STATUS_SUCCESS on success, or another #dc_status_t code
  * on failure.
  */
 dc_status_t
 dc_serial_get_available (dc_serial_t *serial, size_t *value);
 
-/**
- * Query the state of the line signals.
+/** \fn dc_serial_get_lines (dc_serial_t *serial, unsigned int *value);
+ * \brief Query the state of the line signals.
  *
- * @param[in]   serial  A valid serial connection.
- * @param[out]  value   A location to store the bitmap with the state of
+ * \param serial  A valid serial connection.
+ * \param value   A location to store the bitmap with the state of
  *                      the line signals.
- * @returns #DC_STATUS_SUCCESS on success, or another #dc_status_t code
+ * \return dc_status_t #DC_STATUS_SUCCESS on success, or another #dc_status_t code
  * on failure.
  */
 dc_status_t
 dc_serial_get_lines (dc_serial_t *serial, unsigned int *value);
 
-/**
- * Suspend execution of the current thread for the specified amount of
+/** \fn dc_serial_sleep (dc_serial_t *serial, unsigned int milliseconds);
+ * \brief Suspend execution of the current thread for the specified amount of
  * time.
  *
- * @param[in]  serial        A valid serial connection.
- * @param[in]  milliseconds  The number of milliseconds to sleep.
- * @returns #DC_STATUS_SUCCESS on success, or another #dc_status_t code
+ * \param serial        A valid serial connection.
+ * \param milliseconds  The number of milliseconds to sleep.
+ * \return dc_status_t #DC_STATUS_SUCCESS on success, or another #dc_status_t code
  * on failure.
  */
 dc_status_t
diff --git a/src/suunto_common.h b/src/suunto_common.h
index 5a926dd..5106d49 100644
--- a/src/suunto_common.h
+++ b/src/suunto_common.h
@@ -18,7 +18,9 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  * MA 02110-1301 USA
  */
-
+/** \file suunto_common.h
+ * \brief
+ */
 #ifndef SUUNTO_COMMON_H
 #define SUUNTO_COMMON_H
 
@@ -28,25 +30,51 @@
 extern "C" {
 #endif /* __cplusplus */
 
+/** \struct suunto_common_device_t
+ * \brief
+ */
 typedef struct suunto_common_device_t {
 	dc_device_t base;
 	unsigned char fingerprint[5];
 } suunto_common_device_t;
 
+/** \struct suunto_common_layout_t
+ * \brief
+ */
 typedef struct suunto_common_layout_t {
-	unsigned int eop; /**< End-of-profile marker */ 
+	unsigned int eop; /**< End-of-profile marker */
 	unsigned int rb_profile_begin; /**< Profile Ringbuffer Start */
 	unsigned int rb_profile_end; /**< Profile Ringbuffer End */
 	unsigned int fp_offset; /**< Fingerprint */
 	unsigned int peek; /**< Peek */
 } suunto_common_layout_t;
 
+/** \fn suunto_common_device_init (suunto_common_device_t *device);
+ * \brief
+ * \param *device
+ */
 void
 suunto_common_device_init (suunto_common_device_t *device);
 
+/** \fn suunto_common_device_set_fingerprint (dc_device_t *device, const unsigned char data[], unsigned int size);
+ * \brief
+ * \param *device
+ * \param data[]
+ * \param size
+ * \return dc_status_t
+ */
 dc_status_t
 suunto_common_device_set_fingerprint (dc_device_t *device, const unsigned char data[], unsigned int size);
 
+/** \fn suunto_common_extract_dives (suunto_common_device_t *device, const suunto_common_layout_t *layout, const unsigned char data[], dc_dive_callback_t callback, void *userdata);
+ * \brief
+ * \param *device
+ * \param *layout
+ * \param data[]
+ * \param callback
+ * \param *userdata
+ * \return dc_status_t
+ */
 dc_status_t
 suunto_common_extract_dives (suunto_common_device_t *device, const suunto_common_layout_t *layout, const unsigned char data[], dc_dive_callback_t callback, void *userdata);
 
diff --git a/src/suunto_common2.h b/src/suunto_common2.h
index 5eff8d2..341b319 100644
--- a/src/suunto_common2.h
+++ b/src/suunto_common2.h
@@ -18,7 +18,9 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  * MA 02110-1301 USA
  */
-
+/** \file suunto_common2.h
+ * \brief
+ */
 #ifndef SUUNTO_COMMON2_H
 #define SUUNTO_COMMON2_H
 
@@ -28,18 +30,20 @@
 extern "C" {
 #endif /* __cplusplus */
 
+/** \struct suunto_common2_layout_t
+ * \brief
+ */
 typedef struct suunto_common2_layout_t {
-	// Memory size.
-	unsigned int memsize;
-	// Fingerprint
-	unsigned int fingerprint;
-	// Serial number.
-	unsigned int serial;
-	// Profile ringbuffer
-	unsigned int rb_profile_begin;
-	unsigned int rb_profile_end;
+	unsigned int memsize; /**<Memory size*/
+	unsigned int fingerprint; /**<Fingerprint*/
+	unsigned int serial; /**<Serial number.*/
+	unsigned int rb_profile_begin; /**<Profile ringbuffer*/
+	unsigned int rb_profile_end; /**<Profile ringbuffer*/
 } suunto_common2_layout_t;
 
+/** \struct suunto_common2_device_t
+ * \brief
+ */
 typedef struct suunto_common2_device_t {
 	dc_device_t base;
 	const suunto_common2_layout_t *layout;
@@ -47,32 +51,87 @@ typedef struct suunto_common2_device_t {
 	unsigned char fingerprint[7];
 } suunto_common2_device_t;
 
+/** \struct suunto_common2_device_vtable_t
+ * \brief
+ */
 typedef struct suunto_common2_device_vtable_t {
 	dc_device_vtable_t base;
 	dc_status_t (*packet) (dc_device_t *device, const unsigned char command[], unsigned int csize, unsigned char answer[], unsigned int asize, unsigned int size);
 } suunto_common2_device_vtable_t;
 
+/** \fn suunto_common2_device_init (suunto_common2_device_t *device);
+ * \brief
+ * \param *device
+ */
 void
 suunto_common2_device_init (suunto_common2_device_t *device);
 
+/** \fn suunto_common2_device_set_fingerprint (dc_device_t *device, const unsigned char data[], unsigned int size);
+ * \brief
+ * \param *device
+ * \param data[]
+ * \param size
+ * \return dc_status_t
+ */
 dc_status_t
 suunto_common2_device_set_fingerprint (dc_device_t *device, const unsigned char data[], unsigned int size);
 
+/** \fn suunto_common2_device_version (dc_device_t *device, unsigned char data[], unsigned int size);
+ * \brief
+ * \param *device
+ * \param data[]
+ * \param size
+ * \return dc_status_t
+ */
 dc_status_t
 suunto_common2_device_version (dc_device_t *device, unsigned char data[], unsigned int size);
 
+/** \fn suunto_common2_device_read (dc_device_t *device, unsigned int address, unsigned char data[], unsigned int size);
+* \brief
+* \param *device
+* \param address
+* \param data[]
+* \param size
+* \return dc_status_t
+*/
 dc_status_t
 suunto_common2_device_read (dc_device_t *device, unsigned int address, unsigned char data[], unsigned int size);
 
+/** \fn suunto_common2_device_write (dc_device_t *device, unsigned int address, const unsigned char data[], unsigned int size);
+* \brief
+* \param *device
+* \param address
+* \param data[]
+* \param size
+* \return dc_status_t
+*/
 dc_status_t
 suunto_common2_device_write (dc_device_t *device, unsigned int address, const unsigned char data[], unsigned int size);
 
+/** \fn suunto_common2_device_dump (dc_device_t *device, dc_buffer_t *buffer);
+ * \brief
+ * \param *device
+ * \param *buffer
+ * \return dc_status_t
+ */
 dc_status_t
 suunto_common2_device_dump (dc_device_t *device, dc_buffer_t *buffer);
 
+/** \fn suunto_common2_device_foreach (dc_device_t *device, dc_dive_callback_t callback, void *userdata);
+ * \brief
+ * \param *device
+ * \param callback
+ * \param *userdata
+ * \return dc_status_t
+ */
 dc_status_t
 suunto_common2_device_foreach (dc_device_t *device, dc_dive_callback_t callback, void *userdata);
 
+/** \fn suunto_common2_device_reset_maxdepth (dc_device_t *device);
+ * \brief
+ * \param *device
+ * \return dc_status_t
+ */
 dc_status_t
 suunto_common2_device_reset_maxdepth (dc_device_t *device);
 
diff --git a/src/usbhid.h b/src/usbhid.h
index 65d98c1..6b8db89 100644
--- a/src/usbhid.h
+++ b/src/usbhid.h
@@ -18,7 +18,9 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  * MA 02110-1301 USA
  */
-
+/** \file usbhid.h
+ * \brief Header file containing USB HID connection functions
+ */
 #ifndef DC_USBHID_H
 #define DC_USBHID_H
 
@@ -29,36 +31,36 @@
 extern "C" {
 #endif /* __cplusplus */
 
-/**
- * Opaque object representing a USB HID connection.
+/** \struct dc_usbhid_t
+ * \brief Opaque object representing a USB HID connection.
  */
 typedef struct dc_usbhid_t dc_usbhid_t;
 
-/**
- * Open a USB HID connection.
- *
- * @param[out]  usbhid   A location to store the USB HID connection.
- * @param[in]   context  A valid context object.
- * @param[in]   vid      The USB Vendor ID of the device.
- * @param[in]   pid      The USB Product ID of the device.
- * @returns #DC_STATUS_SUCCESS on success, or another #dc_status_t code
+/** \fn dc_usbhid_open (dc_usbhid_t **usbhid, dc_context_t *context, unsigned int vid, unsigned int pid);
+ * \brief Open a USB HID connection.
+ *
+ * \param usbhid   A location to store the USB HID connection.
+ * \param context  A valid context object.
+ * \param vid      The USB Vendor ID of the device.
+ * \param pid      The USB Product ID of the device.
+ * \return dc_status_t #DC_STATUS_SUCCESS on success, or another #dc_status_t code
  * on failure.
  */
 dc_status_t
 dc_usbhid_open (dc_usbhid_t **usbhid, dc_context_t *context, unsigned int vid, unsigned int pid);
 
-/**
- * Close the connection and free all resources.
+/** \fn dc_usbhid_close (dc_usbhid_t *usbhid);
+ * \brief Close the connection and free all resources.
  *
- * @param[in]  usbhid  A valid USB HID connection.
- * @returns #DC_STATUS_SUCCESS on success, or another #dc_status_t code
+ * \param usbhid  A valid USB HID connection.
+ * \return dc_status_t #DC_STATUS_SUCCESS on success, or another #dc_status_t code
  * on failure.
  */
 dc_status_t
 dc_usbhid_close (dc_usbhid_t *usbhid);
 
-/**
- * Set the read timeout.
+/** \fn dc_usbhid_set_timeout (dc_usbhid_t *usbhid, int timeout);
+ * \brief Set the read timeout.
  *
  * There are three distinct modes available:
  *
@@ -80,37 +82,37 @@ dc_usbhid_close (dc_usbhid_t *usbhid);
  *     within the specified amount of time, the operation will return
  *     with the bytes that have already been received.
  *
- * @param[in]  usbhid   A valid USB HID connection.
- * @param[in]  timeout  The timeout in milliseconds.
- * @returns #DC_STATUS_SUCCESS on success, or another #dc_status_t code
+ * \param usbhid   A valid USB HID connection.
+ * \param timeout  The timeout in milliseconds.
+ * \return dc_status_t #DC_STATUS_SUCCESS on success, or another #dc_status_t code
  * on failure.
  */
 dc_status_t
 dc_usbhid_set_timeout (dc_usbhid_t *usbhid, int timeout);
 
-/**
- * Read data from the USB HID connection.
+/** \fn dc_usbhid_read (dc_usbhid_t *usbhid, void *data, size_t size, size_t *actual);
+ * \brief Read data from the USB HID connection.
  *
- * @param[in]  usbhid  A valid USB HID connection.
- * @param[out] data    The memory buffer to read the data into.
- * @param[in]  size    The number of bytes to read.
- * @param[out] actual  An (optional) location to store the actual
+ * \param usbhid  A valid USB HID connection.
+ * \param data    The memory buffer to read the data into.
+ * \param size    The number of bytes to read.
+ * \param actual  An (optional) location to store the actual
  *                     number of bytes transferred.
- * @returns #DC_STATUS_SUCCESS on success, or another #dc_status_t code
+ * \return dc_status_t #DC_STATUS_SUCCESS on success, or another #dc_status_t code
  * on failure.
  */
 dc_status_t
 dc_usbhid_read (dc_usbhid_t *usbhid, void *data, size_t size, size_t *actual);
 
-/**
- * Write data to the USB HID connection.
+/** \fn dc_usbhid_write (dc_usbhid_t *usbhid, const void *data, size_t size, size_t *actual);
+ * \brief Write data to the USB HID connection.
  *
- * @param[in]  usbhid  A valid USB HID connection.
- * @param[in]  data    The memory buffer to write the data from.
- * @param[in]  size    The number of bytes to write.
- * @param[out] actual  An (optional) location to store the actual
+ * \param usbhid  A valid USB HID connection.
+ * \param data    The memory buffer to write the data from.
+ * \param size    The number of bytes to write.
+ * \param actual  An (optional) location to store the actual
  *                     number of bytes transferred.
- * @returns #DC_STATUS_SUCCESS on success, or another #dc_status_t code
+ * \return dc_status_t #DC_STATUS_SUCCESS on success, or another #dc_status_t code
  * on failure.
  */
 dc_status_t
-- 
2.7.4

