Document *everything*

1 files changed, 23 insertions, 3 deletions

diff --git a/src/verify.c b/src/verify.c
index 694206f..4cf0c67 100644
--- a/src/verify.c
+++ b/src/verify.c
@@ -23,6 +23,12 @@
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
+/**
+   \file
+
+   Handling of on-verify commands to add peers not configured statically ("temporary peers")
+*/
+
 
 #include "verify.h"
 
@@ -35,6 +41,12 @@
 #include <pthread.h>
 
 
+/**
+   Calls the on-verify command and returns the result
+
+   do_verify() may be called from secondary threads as all information about the peer
+   to verify is encoded in the supplied environment
+*/
 static bool do_verify(const fastd_shell_env_t *env) {
 	int ret;
 	if (!fastd_shell_command_exec_sync(&conf.on_verify, env, &ret))
@@ -52,12 +64,14 @@ static bool do_verify(const fastd_shell_env_t *env) {
 	return true;
 }
 
+/** The argument given to asynchronous verifier threads */
 typedef struct verify_arg {
-	fastd_shell_env_t *env;
-	size_t ret_len;
-	fastd_async_verify_return_t ret;
+	fastd_shell_env_t *env;			/**< Enviroment containing information about the peer to verify */
+	size_t ret_len;				/**< Length of the \e ret field (as it contains a flexible member) */
+	fastd_async_verify_return_t ret;	/**< Information to return to the main thread after the verification */
 } verify_arg_t;
 
+/** Verifier thread main function */
 static void * do_verify_thread(void *p) {
 	verify_arg_t *arg = p;
 
@@ -71,6 +85,12 @@ static void * do_verify_thread(void *p) {
 	return NULL;
 }
 
+/**
+   Verifies a peer
+
+   \return A tristate. If on-verify is a synchronous command, it will be \e true or \e false, but if the command is asynchronous (which is the default),
+   \e undef will be returned and the result is sent via the asyncronous notification mechanism.
+*/
 fastd_tristate_t fastd_verify_peer(fastd_peer_t *peer, fastd_socket_t *sock, const fastd_peer_address_t *local_addr, const fastd_peer_address_t *remote_addr, const fastd_method_info_t *method, const void *data, size_t data_len) {
 	if (!fastd_shell_command_isset(&conf.on_verify))
 		exit_bug("tried to verify peer without on-verify command");