A bit more documentation

1 files changed, 31 insertions, 9 deletions

diff --git a/src/method.h b/src/method.h
index d7f3304..32b5b5c 100644
--- a/src/method.h
+++ b/src/method.h
@@ -23,39 +23,60 @@
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
+/**
+   \file method.h
+
+   Management of encryption methods
+*/
+
 
 #pragma once
 
 #include "fastd.h"
 
 
+/** Information about a single encryption method */
 struct fastd_method_info {
-	const char *name;
-	const fastd_method_provider_t *provider;
-	fastd_method_t *method;
+	const char *name;				/**< The method name */
+	const fastd_method_provider_t *provider;	/**< The provider of the method */
+	fastd_method_t *method;				/**< Provider-specific method data */
 };
 
+/** Describes a method provider (an implementation of a class of encryption methods) */
 struct fastd_method_provider {
-	size_t max_overhead;
-	size_t min_encrypt_head_space;
-	size_t min_decrypt_head_space;
-	size_t min_encrypt_tail_space;
-	size_t min_decrypt_tail_space;
+	size_t max_overhead;				/**< The maximum number of bytes of overhead the methods may add */
+	size_t min_encrypt_head_space;			/**< The minimum head space needed for encrytion */
+	size_t min_decrypt_head_space;			/**< The minimum head space needed for decryption */
+	size_t min_encrypt_tail_space;			/**< The minimum tail space needed for encryption */
+	size_t min_decrypt_tail_space;			/**< The minimum tail space needed for decryption */
 
+	/** Tries to create a method with the given name */
 	bool (*create_by_name)(const char *name, fastd_method_t **method);
+	/** Frees the resources allocated for a method */
 	void (*destroy)(fastd_method_t *method);
 
+	/** Returns the key length used by a method */
 	size_t (*key_length)(const fastd_method_t *method);
 
+	/** Initiates a session */
 	fastd_method_session_state_t* (*session_init)(const fastd_method_t *method, const uint8_t *secret, bool initiator);
+	/** Initiates a session in pre-v11 compatiblity mode */
 	fastd_method_session_state_t* (*session_init_compat)(const fastd_method_t *method, const uint8_t *secret, size_t length, bool initiator);
+	/** Closes a session */
+	void (*session_free)(fastd_method_session_state_t *session);
+
+	/** Determines if a session is currently valid */
 	bool (*session_is_valid)(fastd_method_session_state_t *session);
+	/** Determines if this fastd instance is the intiator of a given session */
 	bool (*session_is_initiator)(fastd_method_session_state_t *session);
+	/** Checks if this side wants to refresh the session, negotiating a new session key */
 	bool (*session_want_refresh)(fastd_method_session_state_t *session);
+	/** Marks a session as superseded after a refresh */
 	void (*session_superseded)(fastd_method_session_state_t *session);
-	void (*session_free)(fastd_method_session_state_t *session);
 
+	/** Encrypts a packet for a given session, adding method-specific headers */
 	bool (*encrypt)(fastd_peer_t *peer, fastd_method_session_state_t *session, fastd_buffer_t *out, fastd_buffer_t in);
+	/** Decrypts a packet for a given session, stripping method-specific headers */
 	bool (*decrypt)(fastd_peer_t *peer, fastd_method_session_state_t *session, fastd_buffer_t *out, fastd_buffer_t in);
 };
 
@@ -63,6 +84,7 @@ struct fastd_method_provider {
 bool fastd_method_create_by_name(const char *name, const fastd_method_provider_t **provider, fastd_method_t **method);
 
 
+/** Finds the fastd_method_info_t for a configured method */
 static inline const fastd_method_info_t* fastd_method_get_by_name(const char *name) {
 	size_t i;
 	for (i = 0; conf.methods[i].name; i++) {