Document types.h

Doxyfile.in

@@ -726,7 +726,7 @@ WARN_IF_DOC_ERROR      = YES
 # documentation, but not about the absence of documentation.
 # The default value is: NO.
 
-WARN_NO_PARAMDOC       = NO
+WARN_NO_PARAMDOC       = YES
 
 # The WARN_FORMAT tag determines the format of the warning messages that doxygen
 # can produce. The string should contain the $file, $line, and $text tags, which
@@ -1943,7 +1943,7 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             = DEPRECATED=
+PREDEFINED             = __attribute__(x)= UNUSED=
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

src/types.h

@@ -23,8 +23,8 @@
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
-/*
-  types.h
+/**
+  \file types.h
 
   Basic enums and typedefs for common types
 */
@@ -38,34 +38,41 @@
 #include <stddef.h>
 
 
+/** Annotation for unused function parameters */
 #define UNUSED __attribute__((unused))
 
 
+/** A tri-state with the values \em true, \em false and \em undefined */
 typedef struct fastd_tristate {
-	bool set : 1;
-	bool state : 1;
+	bool set : 1;		/**< Specifies if the tri-state is set (\em true or \em false) or not (\em undefined) */
+	bool state : 1;		/**< Speficies if the tri-state is \em true or \em false */
 } fastd_tristate_t;
 
+/** A fastd_tristate_t instance representing the value \em true */
 static const fastd_tristate_t fastd_tristate_true = {true, true};
+/** A fastd_tristate_t instance representing the value \em false */
 static const fastd_tristate_t fastd_tristate_false = {true, false};
+/** A fastd_tristate_t instance representing the value \em undefined */
 static const fastd_tristate_t fastd_tristate_undef = {false, false};
 
 
+/** The defined packet types */
 typedef enum fastd_packet_type {
-	PACKET_UNKNOWN = 0,
-	PACKET_HANDSHAKE,
-	PACKET_DATA,
+	PACKET_HANDSHAKE = 1,	/**< Packet type \em handshake (used to negotiate a session) */
+	PACKET_DATA = 2,	/**< Packet type \em data (used for payload data) */
 } fastd_packet_type_t;
 
+/** The supported modes of operation */
 typedef enum fastd_mode {
-	MODE_TAP,
-	MODE_TUN,
+	MODE_TAP,		/**< TAP (Layer 2/Ethernet mode) */
+	MODE_TUN,		/**< TUN (Layer 3/IP mode) */
 } fastd_mode_t;
 
+/** Specifies when \em fastd drops its capabilities (if supported) */
 typedef enum fastd_drop_caps {
-	DROP_CAPS_OFF,
-	DROP_CAPS_ON,
-	DROP_CAPS_EARLY,
+	DROP_CAPS_OFF,		/**< The capabilities aren't dropped at all */
+	DROP_CAPS_ON,		/**< The capabilities are dropped after executing the on-up command */
+	DROP_CAPS_EARLY,	/**< The capabilities are dropped before executing the on-up command */
 } fastd_drop_caps_t;
 
 
@@ -107,9 +114,10 @@ typedef struct fastd_shell_command fastd_shell_command_t;
 typedef struct fastd_shell_env fastd_shell_env_t;
 
 
+/** A 128-bit aligned block of data, primarily used by the cryptographic functions */
 typedef union fastd_block128 {
-	uint8_t b[16];
-	uint64_t qw[2];
+	uint8_t b[16];		/**< Byte-wise access to the data */
+	uint64_t qw[2];		/**< Quadword-wise access to the data */
 } __attribute__((aligned(16))) fastd_block128_t;