Docs: reformat header files, fix doxygen errors

tstenner · tstenner · commit a133ab335ed7 · 2020-03-16T15:47:40.000+01:00
diff --git a/docs/Doxyfile_API b/docs/Doxyfile_API
@@ -8,21 +8,19 @@ OUTPUT_DIRECTORY       = liblsl_api
 FULL_PATH_NAMES        = NO
 DISTRIBUTE_GROUP_DOC   = YES
 INLINE_SIMPLE_STRUCTS  = YES
-EXTRACT_ALL            = YES
+WARN_IF_UNDOCUMENTED   = NO
 SHOW_NAMESPACES        = NO
-INPUT                  = ../include
+INPUT                  = ../include ../include/lsl/
 JAVADOC_AUTOBRIEF      = YES
-FILE_PATTERNS          = *.c \
-                         *.cpp \
-                        *.h
+FILE_PATTERNS          = *.h
 EXCLUDE_SYMBOLS        =  lslboost
 SOURCE_BROWSER         = YES
 CLANG_ASSISTED_PARSING = NO
 CLANG_OPTIONS          = -I../lslboost
 MACRO_EXPANSION        = YES
 EXPAND_ONLY_PREDEF     = YES
 ENABLE_PREPROCESSING   = YES
-PREDEFINED             = LIBLSL_C_API DOXYGEN_SHOULD_SKIP_THIS
+PREDEFINED             = LIBLSL_C_API
 ALPHABETICAL_INDEX     = NO
 HTML_DYNAMIC_SECTIONS  = YES
 GENERATE_TREEVIEW      = YES
diff --git a/include/lsl/common.h b/include/lsl/common.h
@@ -1,7 +1,6 @@
 #pragma once
 
-/** @file common.h
- * @brief Global constants for liblsl */
+/// @file common.h Global constants for liblsl
 
 #if defined(LIBLSL_FFI)
 // Skip any typedefs that might confuse a FFI header parser, e.g. cffi
@@ -36,7 +35,7 @@ typedef unsigned int uint32_t;
 #define LIBLSL_C_API __attribute__((visibility("default")))
 #endif
 
-//! Constant to indicate that a stream has variable sampling rate.
+/// Constant to indicate that a stream has variable sampling rate.
 #define LSL_IRREGULAR_RATE 0.0
 
 /**
@@ -48,7 +47,7 @@ typedef unsigned int uint32_t;
  * before will is assumed). */
 #define LSL_DEDUCED_TIMESTAMP -1.0
 
-//! A very large time value (ca. 1 year); can be used in timeouts.
+/// A very large time value (ca. 1 year); can be used in timeouts.
 #define LSL_FOREVER 32000000.0
 
 /**
@@ -58,84 +57,78 @@ typedef unsigned int uint32_t;
  */
 #define LSL_NO_PREFERENCE 0
 
-//! Data format of a channel (each transmitted sample holds an array of channels).
+/// Data format of a channel (each transmitted sample holds an array of channels).
 typedef enum {
-	/*! For up to 24-bit precision measurements in the appropriate physical unit (e.g., microvolts).
+	/** For up to 24-bit precision measurements in the appropriate physical unit (e.g., microvolts).
 	 * Integers from -16777216 to 16777216 are represented accurately. */
 	cft_float32 = 1,
-
-	/*! For universal numeric data as long as permitted by network & disk budget.
+	/** For universal numeric data as long as permitted by network & disk budget.
 	 * The largest representable integer is 53-bit. */
 	cft_double64 = 2,
-
-	/*! For variable-length ASCII strings or data blobs, such as video frames, complex event
+	/** For variable-length ASCII strings or data blobs, such as video frames, complex event
 	   descriptions, etc. */
 	cft_string = 3,
-
-	/*! For high-rate digitized formats that require 32-bit precision.
+	/** For high-rate digitized formats that require 32-bit precision.
 	 * Depends critically on meta-data to represent meaningful units.
 	 * Useful for application event codes or other coded data. */
 	cft_int32 = 4,
-
-	/*! For very high rate signals (40Khz+) or consumer-grade audio.
+	/** For very high rate signals (40Khz+) or consumer-grade audio.
 	 * For professional audio float is recommended. */
 	cft_int16 = 5,
-
-	/*! For binary signals or other coded data. Not recommended for encoding string data. */
+	/// For binary signals or other coded data. Not recommended for encoding string data.
 	cft_int8 = 6,
-
-	/*! For now only for future compatibility. Support for this type is not yet
-							 exposed in all languages. Also, some builds of liblsl will not be able
-	   to send or receive data of this type.*/
+	/** 64 bit integers. Support for this type is not yet exposed in all languages.
+	 * Also, some builds of liblsl will not be able to send or receive data of this type. */
 	cft_int64 = 7,
-
-	//! Can not be transmitted.
+	/// Can not be transmitted.
 	cft_undefined = 0
 } lsl_channel_format_t;
 
-//! Post-processing options for stream inlets.
+/// Post-processing options for stream inlets.
 typedef enum {
-	/*! No automatic post-processing; return the ground-truth time stamps for manual
-	 * post-processing. This is the default behavior of the inlet. */
+	/** No automatic post-processing; return the ground-truth time stamps for manual
+	   post-processing. This is the default behavior of the inlet. */
 	proc_none = 0,
 
-	/*! Perform automatic clock synchronization;
-	 * equivalent to manually adding the time_correction() value to the received time stamps. */
+	/** Perform automatic clock synchronization; equivalent to manually adding the time_correction()
+	   value to the received time stamps. */
 	proc_clocksync = 1,
 
-	/*! Remove jitter from time stamps.<br>
-	 * This will apply a smoothing algorithm to the received time stamps;
-	 * the smoothing needs to see a minimum number of samples (30-120 seconds worst-case)
-	 * until the remaining jitter is consistently below 1ms. */
+	/** Remove jitter from time stamps.
+	 *
+	 * This will apply a smoothing algorithm to the received time stamps; the smoothing needs to see
+	 * a minimum number of samples (30-120 seconds worst-case) until the remaining jitter is
+	 * consistently below 1ms. */
 	proc_dejitter = 2,
 
-	/*! Force the time-stamps to be monotonically ascending.<br>
+	/** Force the time-stamps to be monotonically ascending.
+	 *
 	 * Only makes sense if timestamps are dejittered. */
 	proc_monotonize = 4,
 
-	/*! Post-processing is thread-safe (same inlet can be read from by multiple threads);
+	/** Post-processing is thread-safe (same inlet can be read from by multiple threads);
 	 * uses somewhat more CPU. */
 	proc_threadsafe = 8,
 
-	//! The combination of all possible post-processing options.
+	/// The combination of all possible post-processing options.
 	proc_ALL = 1 | 2 | 4 | 8
 } lsl_processing_options_t;
 
 /// Possible error codes.
 typedef enum {
-	//! No error occurred
+	/// No error occurred
 	lsl_no_error = 0,
 
-	//! The operation failed due to a timeout.
+	/// The operation failed due to a timeout.
 	lsl_timeout_error = -1,
 
-	//! The stream has been lost.
+	/// The stream has been lost.
 	lsl_lost_error = -2,
 
-	//! An argument was incorrectly specified (e.g., wrong format or wrong length).
+	/// An argument was incorrectly specified (e.g., wrong format or wrong length).
 	lsl_argument_error = -3,
 
-	//! Some other internal error has happened.
+	/// Some other internal error has happened.
 	lsl_internal_error = -4
 } lsl_error_code_t;
 
diff --git a/include/lsl/inlet.h b/include/lsl/inlet.h
@@ -2,6 +2,9 @@
 #include "common.h"
 #include "types.h"
 
+
+/// @file inlet.h Stream inlet functions
+
 /** @defgroup lsl_inlet The lsl_inlet object
  * @{
  */
diff --git a/include/lsl/outlet.h b/include/lsl/outlet.h
@@ -2,6 +2,8 @@
 #include "./common.h"
 #include "types.h"
 
+/// @file outlet.h Stream outlet functions
+
 /** @defgroup outlet The lsl_outlet object
  *
  * This object represents an outlet sending data to all connected inlets.
diff --git a/include/lsl/resolver.h b/include/lsl/resolver.h
@@ -2,6 +2,8 @@
 #include "common.h"
 #include "types.h"
 
+/// @file resolver.h Stream resolution functions
+
 /** @defgroup continuous_resolver The lsl_continuous_resolver
  * @ingroup resolve
  *
diff --git a/include/lsl/streaminfo.h b/include/lsl/streaminfo.h
@@ -2,6 +2,8 @@
 #include "common.h"
 #include "types.h"
 
+/// @file streaminfo.h Stream info functions
+
 /** @defgroup streaminfo The lsl_streaminfo object
  *
  * The #lsl_streaminfo object keeps a stream's meta data and connection settings.
diff --git a/include/lsl/types.h b/include/lsl/types.h
@@ -1,12 +1,11 @@
 #ifndef LSL_TYPES
 #define LSL_TYPES
 
-/* ===================================================== */
-/* ==== Objects provided by the lab streaming layer ==== */
-/* ===================================================== */
-
 /**
- * Handle to a stream info object. Stores the declaration of a data stream.
+ * @class lsl_streaminfo
+ * Handle to a stream info object.
+ *
+ * Stores the declaration of a data stream.
  * Represents the following information:
  *
  *  - stream data format (number of channels, channel format)
@@ -22,18 +21,21 @@
 typedef struct lsl_streaminfo_struct_ *lsl_streaminfo;
 
 /**
+ * @class lsl_outlet
  * A stream outlet handle.
  * Outlets are used to make streaming data (and the meta-data) available on the lab network.
  */
 typedef struct lsl_outlet_struct_ *lsl_outlet;
 
 /**
+ * @class lsl_inlet
  * A stream inlet handle.
  * Inlets are used to receive streaming data (and meta-data) from the lab network.
  */
 typedef struct lsl_inlet_struct_ *lsl_inlet;
 
 /**
+ * @class lsl_xml_ptr
  * A lightweight XML element tree handle; models the description of a streaminfo object.
  * XML elements behave like advanced pointers into memory that is owned by some respective
  * streaminfo.
@@ -47,6 +49,8 @@ typedef struct lsl_inlet_struct_ *lsl_inlet;
 typedef struct lsl_xml_ptr_struct_ *lsl_xml_ptr;
 
 /**
+ * @class lsl_continuous_resolver
+ *
  * Handle to a convenience object that resolves streams continuously in the background throughout
  * its lifetime and which can be queried at any time for the set of streams that are currently
  * visible on the network.
diff --git a/include/lsl/xml.h b/include/lsl/xml.h
@@ -2,6 +2,8 @@
 #include "common.h"
 #include "types.h"
 
+/// @file inlet.h XML functions
+
 /** @defgroup xml_ptr The lsl_xml_ptr object
  * @{
  */
diff --git a/include/lsl_cpp.h b/include/lsl_cpp.h
diff --git a/testing/DataType.cpp b/testing/DataType.cpp

Original file line number	Diff line number	Diff line change
`@@ -2,6 +2,8 @@`
`2`	`2`	`#include "./common.h"`
`3`	`3`	`#include "types.h"`
`4`	`4`
	`5`	`+/// @file outlet.h Stream outlet functions`
	`6`	`+`
`5`	`7`	`/** @defgroup outlet The lsl_outlet object`
`6`	`8`	`*`
`7`	`9`	`* This object represents an outlet sending data to all connected inlets.`
Original file line number	Diff line number	Diff line change
`@@ -2,6 +2,8 @@`
`2`	`2`	`#include "common.h"`
`3`	`3`	`#include "types.h"`
`4`	`4`
	`5`	`+/// @file resolver.h Stream resolution functions`
	`6`	`+`
`5`	`7`	`/** @defgroup continuous_resolver The lsl_continuous_resolver`
`6`	`8`	`* @ingroup resolve`
`7`	`9`	`*`