Add some API comments.

diff --git a/src/admin.c b/src/admin.c
index d3897794c1d5ffedc9bc6a4289cce5366aecce58..c2c0aa7acf6da9ed7de3aa856980cabf28c14e28 100644 (file)
--- a/src/admin.c
+++ b/src/admin.c
@@ -130,7 +130,7 @@ struct global *admin_get_global(admin_handle h)
 
 /**
  * Return the network handle associated with an admin context.
- * @param Admin context handle
+ * @param h Admin context handle
  * @return Network, or NULL if no network is associated.
  */
 struct network *admin_get_network(admin_handle h)
@@ -1039,6 +1039,10 @@ static gboolean replication_set(admin_handle h, const char *value)
        return TRUE;
 }
 
+/**
+ * Table of administration settings that can be
+ * viewed and changed using the SET command.
+ */
 static struct admin_setting {
        const char *name;
        char *(*get) (admin_handle h);

diff --git a/src/admin.h b/src/admin.h
index fc147f9ae500fe89124238e4dcefa1db079bf2eb..94e2ddf00304ea87a835c81a9b1d4e6a8086bad8 100644 (file)
--- a/src/admin.h
+++ b/src/admin.h
@@ -12,6 +12,9 @@ typedef struct admin_handle *admin_handle;
 
 typedef void (*admin_command_handler) (admin_handle, char **, void *userdata);
 
+/**
+ * Handle used in the administration subsystem.
+ */
 struct admin_handle
 {
        struct global *global;

diff --git a/src/auto_away.c b/src/auto_away.c
index 1406e2e5eb940a2aba0216f7a208c574213b80e7..fddb3199c43b1b7252b8bc9bd7d0b2cec14ea4bf 100644 (file)
--- a/src/auto_away.c
+++ b/src/auto_away.c
@@ -27,6 +27,9 @@
 #include "ctrlproxy.h"
 #include <string.h>
 
+/**
+ * State data for auto-away.
+ */
 struct auto_away_data {
        struct auto_away_config *config;
        time_t last_message;

diff --git a/src/cache.c b/src/cache.c
index 20a58744da2abcef400a2f787869ee5e654788f3..877c02a2ca0bfba4e40960cf5b92a03bd7995945 100644 (file)
--- a/src/cache.c
+++ b/src/cache.c
@@ -246,6 +246,9 @@ static gboolean client_try_cache_names(struct client *c, struct line *l)
        return TRUE;
 }
 
+/**
+ * Table of commands of which the result can be cached.
+ */
 struct cache_command {
        const char *name;
        /* Should return FALSE if command couldn't be cached */

diff --git a/src/ctcp.c b/src/ctcp.c
index 53445716191912f1503a1d9429e6b161c1cd7237..3bbbe9e4c63ca462e6ea85643f848c5011d2e60e 100644 (file)
--- a/src/ctcp.c
+++ b/src/ctcp.c
@@ -169,6 +169,9 @@ void ctcp_register_handler(const struct ctcp_handler *h)
        cmds = g_list_append(cmds, g_memdup(h, sizeof(*h)));
 }
 
+/**
+ * A CTCP request.
+ */
 struct ctcp_request {
        struct client *client;
        char *destination;

diff --git a/src/ctrlproxy.h b/src/ctrlproxy.h
index ab6b2588eb4cb5c6d2178c49836099c87aeb40b5..bba4da5c7c5b2ac1824803cefa8ee890cd88af8d 100644 (file)
--- a/src/ctrlproxy.h
+++ b/src/ctrlproxy.h
@@ -27,6 +27,9 @@
 #include <glib.h>
 #include <gmodule.h>
 
+/**
+ * Current version of the plugin API.
+ */
 #define CTRLPROXY_PLUGIN_VERSION 3
 
 /**
@@ -80,6 +83,9 @@ struct global {
        gint admin_incoming_id;
 };
 
+/**
+ * Plugin description. Required to be defined by all plugins.
+ */
 struct plugin_ops {
        int version;
        char *name;

diff --git a/src/help.h b/src/help.h
index 25fe3bcf9c160e818e038b0db71788e9c17c9589..0f39e95a206eafc6a0f13aa5ba39840afcc2fb13 100644 (file)
--- a/src/help.h
+++ b/src/help.h
@@ -26,6 +26,9 @@
 #ifndef _HELP_H
 #define _HELP_H
 
+/**
+ * Help file.
+ */
 typedef struct help
 {
 #if GLIB_MAJOR_VERSION == 2 && GLIB_MINOR_VERSION >= 8

diff --git a/src/hooks.c b/src/hooks.c
index f8fa174f6c055f8753e8e68d5540d71b1bb88212..081ee21d1574c1d10d5cc23d9371c39f733a522b 100644 (file)
--- a/src/hooks.c
+++ b/src/hooks.c
@@ -138,8 +138,7 @@ gboolean run_client_filter(struct client *c, const struct line *l, enum data_dir
        return TRUE;
 }
 
-/* Hooks that are called when a client is added or removed. 
- * Very useful for replication backends */
+/* Hooks that are called when a client is added or removed. */
 
 struct new_client_hook_data {
        char *name;

diff --git a/src/linestack-cmd.c b/src/linestack-cmd.c
index db04c93d1796beda4c53383d50dfcd2cdb95c640..1eca6b78b1abcfef84b252dc09f23288e374483f 100644 (file)
--- a/src/linestack-cmd.c
+++ b/src/linestack-cmd.c
@@ -18,6 +18,9 @@ static void handle_exit(int, char **);
 static void handle_insert(int, char **);
 static GHashTable *markers = NULL;
 
+/**
+ * Shell command.
+ */
 struct cmd {
        const char *name;
        void (*handler) (int argc, char **);

diff --git a/src/linestack_file.c b/src/linestack_file.c
index 33d0828611315aac387abd3b01f63c0efb1140ef..df66b61ac866e8bdbb4dfe69e98d74bd4f6742f4 100644 (file)
--- a/src/linestack_file.c
+++ b/src/linestack_file.c
@@ -413,6 +413,9 @@ static gboolean marshall_network_state(enum marshall_mode m, GIOChannel *t,
 
 #define STATE_DUMP_INTERVAL 1000
 
+/**
+ * Linestack_file backend data
+ */
 struct lf_data {
        GIOChannel *line_file;
        GIOChannel *state_file;

diff --git a/src/listener.c b/src/listener.c
index 0c52d8d70f9fe282fe51a6d445ccb5b10c62ecb4..2b9a9c473a76d0182073a91a489796706102ebab 100644 (file)
--- a/src/listener.c
+++ b/src/listener.c
@@ -647,6 +647,9 @@ static gboolean pass_handle_data(struct pending_client *cl)
        }
 }
 
+/**
+ * Socks methods.
+ */
 static struct socks_method {
        gint id;
        const char *name;

diff --git a/src/listener.h b/src/listener.h
index 17764a54c8e5c4d083d2f61ad6e8c37dcaf157d8..c2b120367cc9f94b9ab9acc646ab51e36efd2209 100644 (file)
--- a/src/listener.h
+++ b/src/listener.h
@@ -23,6 +23,9 @@ struct listener {
 
 struct socks_method;
 
+/**
+ * Client connection that has not been authenticated yet.
+ */
 struct pending_client {
        GIOChannel *connection;
        char *user;

diff --git a/src/log_custom.c b/src/log_custom.c
index 1af47121eec38daff44b6eb6541fbf7ed6e76702..fa7d029d65eaac63360dc8981de8238ab2345e40 100644 (file)
--- a/src/log_custom.c
+++ b/src/log_custom.c
@@ -26,7 +26,9 @@ struct log_custom_data {
        struct log_support_context *log_ctx;
 };
 
-/* Translation table */
+/**
+ * Translation table
+ */
 struct log_mapping {
        char *command;
        char subst;

diff --git a/src/log_support.h b/src/log_support.h
index a1fe621535e4181c1b132cd7652e01d7d6f4d4f5..198873f522452700b92e06dd74acba3af0aad48c 100644 (file)
--- a/src/log_support.h
+++ b/src/log_support.h
@@ -22,11 +22,19 @@
 
 #include <stdio.h>
 
+/**
+ * Log file information.
+ */
 struct log_file_info {
        FILE *file;
        time_t last_used;
 };
 
+/**
+ * Common logging data. Contains a cache of log files that have been 
+ * written to. Will keep a limited number of file descriptors open, 
+ * for performance reasons.
+ */
 struct log_support_context {
        GHashTable *files;
        int num_opened;

diff --git a/src/settings.h b/src/settings.h
index 5050774cce81d57b02fb58e8d82f4288604316e4..445365482111482f4eb1553b6ae2271b73ac8112 100644 (file)
--- a/src/settings.h
+++ b/src/settings.h
@@ -81,6 +81,11 @@ struct network_config
        } type_settings; 
 };
 
+/**
+ * Log file configuration. Contains substitution variable for 
+ * the path of the log file and for the format used for various events 
+ * when logging.
+ */
 struct log_file_config {
        const char *logfilename;
        const char *nickchange;
@@ -97,6 +102,9 @@ struct log_file_config {
 
 };
 
+/**
+ * Allowed user/password combination for SOCKS.
+ */
 struct allow_rule {
        char *username;
        char *password;
@@ -116,6 +124,9 @@ struct listener_config {
        gboolean is_default; /* Whether this is the "default" listener, stored in ~/.ctrlproxy/config */
 };
 
+/**
+ * Auto-away configuration.
+ */
 struct auto_away_config {
        time_t max_idle_time;
        gint client_limit;