More documentation

22 files changed, 90 insertions, 62 deletions

diff --git a/src/async.c b/src/async.c
index 6025ef3..fb1af41 100644
--- a/src/async.c
+++ b/src/async.c
@@ -24,7 +24,7 @@
 */
 
 /**
-   \file async.c
+   \file src/async.c
 
    Asynchronous notifications
 */
diff --git a/src/async.h b/src/async.h
index ee81b73..4622c3c 100644
--- a/src/async.h
+++ b/src/async.h
@@ -24,7 +24,7 @@
 */
 
 /**
-   \file async.h
+   \file src/async.h
 
    Asynchronous notifications
 */
@@ -45,26 +45,26 @@ typedef enum fastd_async_type {
 
 /** A DNS resolver response */
 typedef struct fastd_async_resolve_return {
-	uint64_t peer_id;
-	size_t remote;
+	uint64_t peer_id;			/**< The ID of the peer the resolved remote belongs to */
+	size_t remote;				/**< The index of the resolved remote */
 
-	size_t n_addr;
-	fastd_peer_address_t addr[];
+	size_t n_addr;				/**< The number of addresses returned */
+	fastd_peer_address_t addr[];		/**< The resolved addresses */
 } fastd_async_resolve_return_t;
 
 /** A on-verify response */
 typedef struct fastd_async_verify_return {
-	bool ok;
+	bool ok;				/**< true if the verification was successful */
 
-	uint64_t peer_id;
+	uint64_t peer_id;			/**< The ID of the verified peer */
 
-	const fastd_method_info_t *method;
-	fastd_socket_t *sock;
+	const fastd_method_info_t *method;	/**< The method supplied in the handshake causing the verification */
+	fastd_socket_t *sock;			/**< The socket the handshake causing the verification was received on */
 
-	fastd_peer_address_t local_addr;
-	fastd_peer_address_t remote_addr;
+	fastd_peer_address_t local_addr;	/**< The local address the handshake was received on */
+	fastd_peer_address_t remote_addr;	/**< The address the handshake was received from */
 
-	uint8_t protocol_data[] __attribute__((aligned(8)));
+	uint8_t protocol_data[] __attribute__((aligned(8))); /**< Protocol-specific data */
 } fastd_async_verify_return_t;
 
 
diff --git a/src/buffer.h b/src/buffer.h
index ac1df3d..afd18d5 100644
--- a/src/buffer.h
+++ b/src/buffer.h
@@ -24,7 +24,7 @@
 */
 
 /**
-   \file buffer.h
+   \file src/buffer.h
 
    Buffer management
 */
diff --git a/src/compat.h b/src/compat.h
index 1e857a0..25e6be5 100644
--- a/src/compat.h
+++ b/src/compat.h
@@ -24,7 +24,7 @@
 */
 
 /**
-   \file compat.h
+   \file src/compat.h
 
    Portablity definitions
 */
diff --git a/src/crypto.h b/src/crypto.h
index de2bddf..a228f5a 100644
--- a/src/crypto.h
+++ b/src/crypto.h
@@ -23,6 +23,12 @@
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
+/**
+   \file src/crypto.h
+
+   Cyptographic algorithm API and utilities
+*/
+
 
 #pragma once
 
diff --git a/src/dlist.h b/src/dlist.h
index d1fc40c..a8118f0 100644
--- a/src/dlist.h
+++ b/src/dlist.h
@@ -24,7 +24,7 @@
 */
 
 /**
-   \file dlist.h
+   \file src/dlist.h
 
    Doubly-linked lists
 */
diff --git a/src/fastd.h b/src/fastd.h
index 68a9f5b..50f90a9 100644
--- a/src/fastd.h
+++ b/src/fastd.h
@@ -24,7 +24,7 @@
 */
 
 /**
-   \file fastd.h
+   \file src/fastd.h
 
    \em fastd main header file defining most data structures
  */
diff --git a/src/handshake.h b/src/handshake.h
index 7b5ebf3..34597ed 100644
--- a/src/handshake.h
+++ b/src/handshake.h
@@ -23,57 +23,72 @@
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
+/**
+   \file src/handshake.h
+
+   Functions and structures for composing and decomposing handshake packets
+*/
+
 
 #pragma once
 
 #include "fastd.h"
 
 
+/**
+   The type field of a handshake TLV record
+
+   In the handshake packet, the type field will be 2 bytes wide and big endian
+*/
 typedef enum fastd_handshake_record_type {
-	RECORD_HANDSHAKE_TYPE = 0,
-	RECORD_REPLY_CODE,
-	RECORD_ERROR_DETAIL,
-	RECORD_FLAGS,
-	RECORD_MODE,
-	RECORD_PROTOCOL_NAME,
-	RECORD_PROTOCOL1,
-	RECORD_PROTOCOL2,
-	RECORD_PROTOCOL3,
-	RECORD_PROTOCOL4,
-	RECORD_PROTOCOL5,
-	RECORD_MTU,
-	RECORD_METHOD_NAME,
-	RECORD_VERSION_NAME,
-	RECORD_METHOD_LIST,
-	RECORD_TLV_MAC,
-	RECORD_MAX,
+	RECORD_HANDSHAKE_TYPE = 0,	/**< the handshake type (initial, response or finish) */
+	RECORD_REPLY_CODE,		/**< The reply code */
+	RECORD_ERROR_DETAIL,		/**< The error detail code */
+	RECORD_FLAGS,			/**< The flags field */
+	RECORD_MODE,			/**< The mode field */
+	RECORD_PROTOCOL_NAME,		/**< The handshake protocol */
+	RECORD_PROTOCOL1,		/**< Protocol-specific value 1 */
+	RECORD_PROTOCOL2,		/**< Protocol-specific value 2 */
+	RECORD_PROTOCOL3,		/**< Protocol-specific value 3 */
+	RECORD_PROTOCOL4,		/**< Protocol-specific value 4 */
+	RECORD_PROTOCOL5,		/**< Protocol-specific value 5 */
+	RECORD_MTU,			/**< MTU field */
+	RECORD_METHOD_NAME,		/**< The default/chosen method */
+	RECORD_VERSION_NAME,		/**< The fastd version */
+	RECORD_METHOD_LIST,		/**< Zero-separated list of supported methods */
+	RECORD_TLV_MAC,			/**< Message authentication code of the TLV records */
+	RECORD_MAX,			/**< (Number of defined record types) */
 } fastd_handshake_record_type_t;
 
+/** The reply codes */
 typedef enum fastd_reply_code {
-	REPLY_SUCCESS = 0,
-	REPLY_MANDATORY_MISSING,
-	REPLY_UNACCEPTABLE_VALUE,
-	REPLY_MAX,
+	REPLY_SUCCESS = 0,		/**< The handshake was sucessfull */
+	REPLY_MANDATORY_MISSING,	/**< A required TLV field is missing */
+	REPLY_UNACCEPTABLE_VALUE,	/**< A TLV field has an invalid value */
+	REPLY_MAX,			/**< (Number of defined reply codes */
 } fastd_reply_code_t;
 
 
+/** The handshake packet structure (not including the initial packet type byte) */
 typedef struct __attribute__((__packed__)) fastd_handshake_packet {
-	uint8_t rsv;
-	uint16_t tlv_len;
-	uint8_t tlv_data[];
+	uint8_t rsv;			/**< Reserved (must be 0) */
+	uint16_t tlv_len;		/**< Length of the TLV records (before fastd v11 this was always 0, which is interpreted as "the whole packet") */
+	uint8_t tlv_data[];		/**< TLV record data */
 } fastd_handshake_packet_t;
 
+/** A record descriptor */
 typedef struct fastd_handshake_record {
-	size_t length;
-	uint8_t *data;
+	size_t length;			/**< The length of the value */
+	uint8_t *data;			/**< Points to the value of the TLV record */
 } fastd_handshake_record_t;
 
+/** Describes a handshake packet */
 struct fastd_handshake {
-	uint8_t type;
-	const char *peer_version;
-	fastd_handshake_record_t records[RECORD_MAX];
-	uint16_t tlv_len;
-	void *tlv_data;
+	uint8_t type;			/**< The handshake type */
+	const char *peer_version;	/**< The fastd version of the peer */
+	fastd_handshake_record_t records[RECORD_MAX]; /**< The TLV records of the handshake */
+	uint16_t tlv_len;		/**< The length of the TLV record data */
+	void *tlv_data;			/**< TLV record data */
 };
 
 
@@ -83,16 +98,19 @@ fastd_buffer_t fastd_handshake_new_reply(uint8_t type, const fastd_method_info_t
 void fastd_handshake_handle(fastd_socket_t *sock, const fastd_peer_address_t *local_addr, const fastd_peer_address_t *remote_addr, fastd_peer_t *peer, fastd_buffer_t buffer);
 
 
+/** Returns the TLV data of a handshake packet in a given buffer */
 static inline void* fastd_handshake_tlv_data(const fastd_buffer_t *buffer) {
 	fastd_handshake_packet_t *packet = buffer->data;
 	return packet->tlv_data;
 }
 
+/** Returns the length the TLV data of a handshake packet in a given buffer */
 static inline uint16_t fastd_handshake_tlv_len(const fastd_buffer_t *buffer) {
 	fastd_handshake_packet_t *packet = buffer->data;
 	return ntohs(packet->tlv_len);
 }
 
+/** Adds an uninitialized TLV record of given type and length to a handshake buffer */
 static inline uint8_t* fastd_handshake_extend(fastd_buffer_t *buffer, fastd_handshake_record_type_t type, size_t len) {
 	uint8_t *dst = buffer->data + buffer->len;
 
@@ -112,12 +130,14 @@ static inline uint8_t* fastd_handshake_extend(fastd_buffer_t *buffer, fastd_hand
 	return dst+4;
 }
 
+/** Adds an TLV record of given type and length initialized with arbitraty data to a handshake buffer */
 static inline void fastd_handshake_add(fastd_buffer_t *buffer, fastd_handshake_record_type_t type, size_t len, const void *data) {
 	uint8_t *dst = fastd_handshake_extend(buffer, type, len);
 
 	memcpy(dst, data, len);
 }
 
+/** Adds an TLV record of given type and length initialized with zeros to a handshake buffer */
 static inline uint8_t* fastd_handshake_add_zero(fastd_buffer_t *buffer, fastd_handshake_record_type_t type, size_t len) {
 	uint8_t *dst = fastd_handshake_extend(buffer, type, len);
 
@@ -125,12 +145,14 @@ static inline uint8_t* fastd_handshake_add_zero(fastd_buffer_t *buffer, fastd_ha
 	return dst;
 }
 
+/** Adds an uint8 TLV record of given type and value to a handshake buffer */
 static inline void fastd_handshake_add_uint8(fastd_buffer_t *buffer, fastd_handshake_record_type_t type, uint8_t value) {
 	uint8_t *dst = fastd_handshake_extend(buffer, type, 1);
 
 	dst[0] = value;
 }
 
+/** Adds an uint16 TLV record of given type and value to a handshake buffer */
 static inline void fastd_handshake_add_uint16(fastd_buffer_t *buffer, fastd_handshake_record_type_t type, uint16_t value) {
 	uint8_t *dst = fastd_handshake_extend(buffer, type, 2);
 
diff --git a/src/log.h b/src/log.h
index 8cfee16..ec11299 100644
--- a/src/log.h
+++ b/src/log.h
@@ -24,7 +24,7 @@
 */
 
 /**
-   \file log.h
+   \file src/log.h
 
    Logging functions and macros
 */
diff --git a/src/method.h b/src/method.h
index 32b5b5c..da70a7b 100644
--- a/src/method.h
+++ b/src/method.h
@@ -24,7 +24,7 @@
 */
 
 /**
-   \file method.h
+   \file src/method.h
 
    Management of encryption methods
 */
diff --git a/src/peer.c b/src/peer.c
index 63e0b2f..924d4b0 100644
--- a/src/peer.c
+++ b/src/peer.c
@@ -24,7 +24,7 @@
 */
 
 /**
-   \file peer.c
+   \file src/peer.c
 
    Implementations of functions for peer management
 */
diff --git a/src/peer.h b/src/peer.h
index cd5bb15..5eb8b87 100644
--- a/src/peer.h
+++ b/src/peer.h
@@ -24,7 +24,7 @@
 */
 
 /**
-   \file peer.h
+   \file src/peer.h
 
    Structures and functions for peer management
 */
diff --git a/src/poll.c b/src/poll.c
index 911fc2e..f10e619 100644
--- a/src/poll.c
+++ b/src/poll.c
@@ -24,7 +24,7 @@
 */
 
 /**
-   \file poll.c
+   \file src/poll.c
 
    Portable polling API implementations
 */
diff --git a/src/poll.h b/src/poll.h
index ae9c8cd..456ee68 100644
--- a/src/poll.h
+++ b/src/poll.h
@@ -24,7 +24,7 @@
 */
 
 /**
-   \file poll.h
+   \file src/poll.h
 
    Portable polling API
 */
diff --git a/src/resolve.c b/src/resolve.c
index 0415852..0635ddf 100644
--- a/src/resolve.c
+++ b/src/resolve.c
@@ -24,7 +24,7 @@
 */
 
 /**
-   \file resolve.c
+   \file src/resolve.c
 
    DNS resolver functions
  */
diff --git a/src/sha256.c b/src/sha256.c
index c05adbc..bed55fd 100644
--- a/src/sha256.c
+++ b/src/sha256.c
@@ -24,7 +24,7 @@
 */
 
 /**
-   \file sha256.c
+   \file src/sha256.c
 
    Small SHA256 and HMAC-SHA256 implementation
 */
diff --git a/src/sha256.h b/src/sha256.h
index a0b8805..2d45b2d 100644
--- a/src/sha256.h
+++ b/src/sha256.h
@@ -24,7 +24,7 @@
 */
 
 /**
-   \file sha256.h
+   \file src/sha256.h
 
    Small SHA256 and HMAC-SHA256 implementation
 */
diff --git a/src/shell.c b/src/shell.c
index d8f044b..524d38e 100644
--- a/src/shell.c
+++ b/src/shell.c
@@ -25,7 +25,7 @@
 
 
 /**
-   \file shell.c
+   \file src/shell.c
 
    Execution of shell commands and management of environment variables
 */
diff --git a/src/shell.h b/src/shell.h
index 9c2b8ab..3a402f7 100644
--- a/src/shell.h
+++ b/src/shell.h
@@ -24,7 +24,7 @@
 */
 
 /**
-   \file shell.h
+   \file src/shell.h
 
    Execution of shell commands and management of environment variables
 */
diff --git a/src/types.h b/src/types.h
index 2dae259..6854a7c 100644
--- a/src/types.h
+++ b/src/types.h
@@ -24,7 +24,7 @@
 */
 
 /**
-  \file types.h
+  \file src/types.h
 
   Basic enums and typedefs for common types
 */
diff --git a/src/vector.c b/src/vector.c
index 4bf5853..4b451b1 100644
--- a/src/vector.c
+++ b/src/vector.c
@@ -24,7 +24,7 @@
 */
 
 /**
-   \file vector.c
+   \file src/vector.c
 
    Typesafe dynamically sized arrays
 */
diff --git a/src/vector.h b/src/vector.h
index 0a61341..526dfaf 100644
--- a/src/vector.h
+++ b/src/vector.h
@@ -24,7 +24,7 @@
 */
 
 /**
-   \file vector.h
+   \file src/vector.h
 
    Typesafe dynamically sized arrays
 */