Improve documentation

Doxyfile

@@ -4,3 +4,4 @@ INPUT                  = include/
 STRIP_CODE_COMMENTS    = NO
 ALPHABETICAL_INDEX     = NO
 IGNORE_PREFIX          = ohmd_ OHMD_
+ENUM_VALUES_PER_LINE   = 1

include/openhmd.h

@@ -48,95 +48,95 @@ typedef enum {
 	OHMD_S_USER_RESERVED = -16384,
 } ohmd_status;
 
-/** A collection of string value information types used for getting information with ohmd_list_gets(). */
+/** A collection of string value information types, used for getting information with ohmd_list_gets(). */
 typedef enum {
 	OHMD_VENDOR    = 0,
 	OHMD_PRODUCT   = 1,
 	OHMD_PATH      = 2,
 } ohmd_string_value;
 
-/** A collection of float value information types used for getting and setting information with
+/** A collection of float value information types, used for getting and setting information with
  ohmd_device_getf() and ohmd_device_setf(). */
 typedef enum {
-	/** float[4], get - Absolute rotation of the device, in space, as a quaternion. */
+	/** float[4] (get): Absolute rotation of the device, in space, as a quaternion (x, y, z, w). */
 	OHMD_ROTATION_QUAT                    =  1,
 
-	/** float[16], get - A "ready to use" OpenGL style 4x4 matrix with a modelview matrix for the
+	/** float[16] (get): A "ready to use" OpenGL style 4x4 matrix with a modelview matrix for the
 	 left eye of the HMD. */
 	OHMD_LEFT_EYE_GL_MODELVIEW_MATRIX     =  2,
 
-	/** float[16], get - A "ready to use" OpenGL style 4x4 matrix with a modelview matrix for the
+	/** float[16] (get): A "ready to use" OpenGL style 4x4 matrix with a modelview matrix for the
 	 right eye of the HMD. */
 	OHMD_RIGHT_EYE_GL_MODELVIEW_MATRIX    =  3,
 
-	/** float[16], get - A "ready to use" OpenGL style 4x4 matrix with a projection matrix for the
+	/** float[16] (get): A "ready to use" OpenGL style 4x4 matrix with a projection matrix for the
 	 left eye of the HMD. */
 	OHMD_LEFT_EYE_GL_PROJECTION_MATRIX    =  4,
-	/** float[16], get - A "ready to use" OpenGL style 4x4 matrix with a projection matrix for the
+	/** float[16] (get): A "ready to use" OpenGL style 4x4 matrix with a projection matrix for the
 	 right eye of the HMD. */
 	OHMD_RIGHT_EYE_GL_PROJECTION_MATRIX   =  5,
 
-	/** float[3], get - A 3-D vector representing the absolute position of the device, in space. */
+	/** float[3] (get): A 3-D vector representing the absolute position of the device, in space. */
 	OHMD_POSITION_VECTOR                  =  6,
 
-	/** float[1], get - Physical width of the device screen, in centimeters. */
+	/** float[1] (get): Physical width of the device screen in centimetres. */
 	OHMD_SCREEN_HORIZONTAL_SIZE           =  7,
-	/** float[1], get - Physical height of the device screen, in centimeters. */
+	/** float[1] (get): Physical height of the device screen in centimetres. */
 	OHMD_SCREEN_VERTICAL_SIZE             =  8,
 
-	/** float[1], get - Physical speration of the device lenses, in centimeters. */
+	/** float[1] (get): Physical separation of the device lenses in centimetres. */
 	OHMD_LENS_HORIZONTAL_SEPARATION       =  9,
-	/** float[1], get - Physical vertical position of the lenses, in centimeters. */
+	/** float[1] (get): Physical vertical position of the lenses in centimetres. */
 	OHMD_LENS_VERTICAL_POSITION           = 10,
 
-	/** float[1], get - Physical field of view for the left eye, in degrees. */
+	/** float[1] (get): Physical field of view for the left eye in degrees. */
 	OHMD_LEFT_EYE_FOV                     = 11,
-	/** float[1], get - Physical display aspect ratio for the left eye screen. */
+	/** float[1] (get): Physical display aspect ratio for the left eye screen. */
 	OHMD_LEFT_EYE_ASPECT_RATIO            = 12,
-	/** float[1], get - Physical field of view for the left right, in degrees. */
+	/** float[1] (get): Physical field of view for the left right in degrees. */
 	OHMD_RIGHT_EYE_FOV                    = 13,
-	/** float[1], get
-	      Physical display aspect ratio for the right eye screen. */
+	/** float[1] (get): Physical display aspect ratio for the right eye screen. */
 	OHMD_RIGHT_EYE_ASPECT_RATIO           = 14,
 
-	/** float[1], get/set - Physical interpupilary distance of the user, in centimeters. */
+	/** float[1] (get, set): Physical interpupillary distance of the user in centimetres. */
 	OHMD_EYE_IPD                          = 15,
 
-	/** float[1], get/set - Z-far value for the projection matrix calculations, i.e. drawing distance. */
+	/** float[1] (get, set): Z-far value for the projection matrix calculations (i.e. drawing distance). */
 	OHMD_PROJECTION_ZFAR                  = 16,
-	/** float[1], get/set - Z-near value for the projection matrix calculations, i.e. close clipping
-	 distance. */
+	/** float[1] (get, set): Z-near value for the projection matrix calculations (i.e. close clipping distance). */
 	OHMD_PROJECTION_ZNEAR                 = 17,
 
-	/** float[6], get - Device specifc distortion value. */
+	/** float[6] (get): Device specific distortion value. */
 	OHMD_DISTORTION_K                     = 18,
 	
-	/** float[10], set - Perform sensor fusion on values from external sensors. Values are: dt (time since last update, in seconds) X, Y, Z gyro, X, Y, Z accelerometer and X, Y, Z magnetometer. */
+	/**
+	 * float[10] (set): Perform sensor fusion on values from external sensors.
+	 *
+	 * Values are: dt (time since last update in seconds) X, Y, Z gyro, X, Y, Z accelerometer and X, Y, Z magnetometer.
+	 **/
 	OHMD_EXTERNAL_SENSOR_FUSION           = 19,
 
 } ohmd_float_value;
 
-/** A collection of int value information types used for getting information with ohmd_device_geti()
-*/
+/** A collection of int value information types used for getting information with ohmd_device_geti(). */
 typedef enum {
-	/** int[1], get
-	      Physical horizontal resolution of the device screen. */
+	/** int[1] (get): Physical horizontal resolution of the device screen. */
 	OHMD_SCREEN_HORIZONTAL_RESOLUTION     =  0,
-	/** int[1], get
-	      Physical vertical resolution of the device screen. */
+	/** int[1] (get): Physical vertical resolution of the device screen. */
 	OHMD_SCREEN_VERTICAL_RESOLUTION       =  1,
 
 } ohmd_int_value;
 
-/** A collection of data information types used for setting information with ohmd_set_data()
-*/
+/** A collection of data information types used for setting information with ohmd_set_data(). */
 typedef enum {
-    /** void*, set
-        Set void* data for use in the internal drivers. */
+	/** void* (set): Set void* data for use in the internal drivers. */
     OHMD_DRIVER_DATA		= 0,
-    /** ohmd_device_properties*, set
-        Set the device properties based on the ohmd_device_properties struct for use in the internal drivers. 
-        This can be used to fill in information about the device such as Android internally, or for setting profiles.*/  
+	/**
+	 * ohmd_device_properties* (set):
+	 * Set the device properties based on the ohmd_device_properties struct for use in the internal drivers.
+	 *
+	 * This can be used to fill in information about the device internally, such as Android, or for setting profiles.
+	 **/
 	OHMD_DRIVER_PROPERTIES	= 1,
 } ohmd_data_value;
 
@@ -149,7 +149,7 @@ typedef struct ohmd_device ohmd_device;
 /**
  * Create an OpenHMD context.
  *
- * @return a pointer to an allocated ohmd_context on success or NULL if it fails
+ * @return a pointer to an allocated ohmd_context on success or NULL if it fails.
  */
 OHMD_APIENTRYDLL ohmd_context* OHMD_APIENTRY ohmd_ctx_create();
 
@@ -167,10 +167,10 @@ OHMD_APIENTRYDLL void OHMD_APIENTRY ohmd_ctx_destroy(ohmd_context* ctx);
  * Get the last error as a human readable string.
  *
  * If a function taking a context as an argument (ohmd_context "methods") returns non-successfully,
- * a human readable error message describing what went wrong can be retreived with this function.
+ * a human readable error message describing what went wrong can be retrieved with this function.
  *
- * @param ctx The context to retreive the error message from.
- * @return a pointer to the error message
+ * @param ctx The context to retrieve the error message from.
+ * @return a pointer to the error message.
  */
 OHMD_APIENTRYDLL const char* OHMD_APIENTRY ohmd_ctx_get_error(ohmd_context* ctx);
 
@@ -193,7 +193,7 @@ OHMD_APIENTRYDLL void OHMD_APIENTRY ohmd_ctx_update(ohmd_context* ctx);
  * Probes for and enumerates supported devices attached to the system.
  *
  * @param ctx A context with no currently open devices.
- * @return number of devices found on the system
+ * @return the number of devices found on the system.
  */
 OHMD_APIENTRYDLL int OHMD_APIENTRY ohmd_ctx_probe(ohmd_context* ctx);
 
@@ -201,25 +201,27 @@ OHMD_APIENTRYDLL int OHMD_APIENTRY ohmd_ctx_probe(ohmd_context* ctx);
  * Get device description from enumeration list index.
  *
  * Gets a human readable device description string from a zero indexed enumeration index
- * between 0 and max, where max is the number ohmd_ctx_probe returned.
- * (I.e. if ohmd_ctx_probe returns 3,valid indices are 0, 1 and 2).
+ * between 0 and (max - 1), where max is the number ohmd_ctx_probe returned
+ * (i.e. if ohmd_ctx_probe returns 3, valid indices are 0, 1 and 2).
  * The function can return three types of data. The vendor name, the product name and
  * a driver specific path where the device is attached.
+ *
  * ohmd_ctx_probe must be called before calling ohmd_list_gets.
  *
  * @param ctx A (probed) context.
  * @param index An index, between 0 and the value returned from ohmd_ctx_probe.
  * @param type The type of data to fetch. One of OHMD_VENDOR, OHMD_PRODUCT and OHMD_PATH.
- * @return a string with a human readable device name
+ * @return a string with a human readable device name.
  */
 OHMD_APIENTRYDLL const char* OHMD_APIENTRY ohmd_list_gets(ohmd_context* ctx, int index, ohmd_string_value type);
 
 /**
  * Open a device.
  *
- * Opens a device from a zero indexed enumeration index between 0 and max,
- * where max is the number ohmd_ctx_probe returned. (I.e. if ohmd_ctx_probe returns 3,
+ * Opens a device from a zero indexed enumeration index between 0 and (max - 1)
+ * where max is the number ohmd_ctx_probe returned (i.e. if ohmd_ctx_probe returns 3,
  * valid indices are 0, 1 and 2).
+ *
  * ohmd_ctx_probe must be called before calling ohmd_list_open_device.
  *
  * @param ctx A (probed) context.
@@ -232,7 +234,7 @@ OHMD_APIENTRYDLL ohmd_device* OHMD_APIENTRY ohmd_list_open_device(ohmd_context*
  * Close a device.
  *
  * Closes a device opened by ohmd_list_open_device. Note that ohmd_ctx_destroy automatically closes any open devices
- * assoiciated with the context being destroyed.
+ * associated with the context being destroyed.
  *
  * @param device The open device.
  * @return 0 on success, <0 on failure.
@@ -243,9 +245,9 @@ OHMD_APIENTRYDLL int OHMD_APIENTRY ohmd_close_device(ohmd_device* device);
  * Get a floating point value from a device.
  *
  *
- * @param device An open device to retreive the value from.
- * @param type What type of value to retreive, see ohmd_float_value section for more information.
- * @param[out] out A pointer to a float, or float array where the retreived value should be written.
+ * @param device An open device to retrieve the value from.
+ * @param type What type of value to retrieve, see ohmd_float_value section for more information.
+ * @param[out] out A pointer to a float, or float array where the retrieved value should be written.
  * @return 0 on success, <0 on failure.
  */
 OHMD_APIENTRYDLL int OHMD_APIENTRY ohmd_device_getf(ohmd_device* device, ohmd_float_value type, float* out);
@@ -263,9 +265,9 @@ OHMD_APIENTRYDLL int OHMD_APIENTRY ohmd_device_setf(ohmd_device* device, ohmd_fl
 /**
  * Get an integer value from a device.
  *
- * @param device An open device to retreive the value from.
- * @param type What type of value to retreive, ohmd_int_value section for more information.
- * @param[out] out A pointer to an integer, or integer array where the retreived value should be written.
+ * @param device An open device to retrieve the value from.
+ * @param type What type of value to retrieve, ohmd_int_value section for more information.
+ * @param[out] out A pointer to an integer, or integer array where the retrieved value should be written.
  * @return 0 on success, <0 on failure.
  */
 OHMD_APIENTRYDLL int OHMD_APIENTRY ohmd_device_geti(ohmd_device* device, ohmd_int_value type, int* out);