From 0e4472a082cdbb50ee54e1886abc332f3e11bcce Mon Sep 17 00:00:00 2001 Message-Id: <0e4472a082cdbb50ee54e1886abc332f3e11bcce.1713868324.git.mdw@distorted.org.uk> From: Mark Wooding Date: Tue, 25 Sep 2007 15:22:33 +0100 Subject: [PATCH] doxygen Organization: Straylight/Edgeware From: rjk@greenend.org.uk <> --- lib/cache.c | 2 + lib/cache.h | 10 +++- lib/charset.h | 7 ++- lib/client-common.c | 6 +++ lib/configuration.c | 4 ++ lib/configuration.h | 3 ++ lib/defs.c | 5 +- lib/eclient.c | 114 +++++++++++++++++++++++++++----------------- lib/eclient.h | 76 ++++++++++++++++++++--------- server/speaker.h | 4 +- 10 files changed, 160 insertions(+), 71 deletions(-) diff --git a/lib/cache.c b/lib/cache.c index bc6bc81..faca540 100644 --- a/lib/cache.c +++ b/lib/cache.c @@ -84,6 +84,7 @@ const void *cache_get(const struct cache_type *type, const char *key) { return 0; } +/** @brief Call used by from cache_expire() */ static int expiry_callback(const char *key, void *value, void *u) { const struct cache_entry *c = value; const time_t *now = u; @@ -105,6 +106,7 @@ void cache_expire(void) { } } +/** @brief Callback used by cache_clean() */ static int clean_callback(const char *key, void *value, void *u) { const struct cache_entry *c = value; const struct cache_type *type = u; diff --git a/lib/cache.h b/lib/cache.h index 48aba1c..b2c9ffc 100644 --- a/lib/cache.h +++ b/lib/cache.h @@ -17,14 +17,22 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * USA */ +/** @file lib/cache.h + * @brief Object caching + * + * There is a single cache for the whole process. Objects of different types + * are distinguished. Objects might be thrown out of the cache at any point. + */ #ifndef CACHE_H #define CACHE_H /* Defines a cache mapping keys to typed data items */ +/** @brief Type of a cache object */ struct cache_type { - int lifetime; /* Lifetime of a cache entry */ + /** @brief Lifetime for objects of this type (seconds) */ + int lifetime; }; void cache_put(const struct cache_type *type, diff --git a/lib/charset.h b/lib/charset.h index 369d2b9..f77c583 100644 --- a/lib/charset.h +++ b/lib/charset.h @@ -48,7 +48,12 @@ char *any2any(const char *from/*encoding or 0*/, * that iconv knows. If FROM and TO are both 0 then ANY is returned * unchanged. */ - +/** @brief Insist that @p s is not null + * @param s Pointer to check + * @return @p s + * + * Terminates the process if @p s is a null pointer. + */ static inline char *nullcheck(char *s) { if(!s) exitfn(1); /* assume an error already reported */ return s; diff --git a/lib/client-common.c b/lib/client-common.c index c2dfe02..e1fcce9 100644 --- a/lib/client-common.c +++ b/lib/client-common.c @@ -34,6 +34,12 @@ #include "client-common.h" #include "addr.h" +/** @brief Invoke a function with the connect address + * @param c Passed to callback + * @param function Function to call + * + * Calls @p function with the result of looking up the connect address. + */ int with_sockaddr(void *c, int (*function)(void *c, const struct sockaddr *sa, diff --git a/lib/configuration.c b/lib/configuration.c index 081e6d2..a125bc7 100644 --- a/lib/configuration.c +++ b/lib/configuration.c @@ -17,6 +17,9 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * USA */ +/** @file lib/configuration.c + * @brief Configuration file support + */ #include #include "types.h" @@ -883,6 +886,7 @@ static int config_set(const struct config_state *cs, || which->type->set(cs, which, nvec - 1, vec + 1)); } +/** @brief Error callback used by config_include() */ static void config_error(const char *msg, void *u) { const struct config_state *cs = u; diff --git a/lib/configuration.h b/lib/configuration.h index c7b5b09..2975557 100644 --- a/lib/configuration.h +++ b/lib/configuration.h @@ -17,6 +17,9 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * USA */ +/** @file lib/configuration.h + * @brief Configuration file support + */ #ifndef CONFIGURATION_H #define CONFIGURATION_H diff --git a/lib/defs.c b/lib/defs.c index 494597e..d0f5c66 100644 --- a/lib/defs.c +++ b/lib/defs.c @@ -50,7 +50,10 @@ const char bindir[] = BINDIR; /** @brief System binary directory */ const char sbindir[] = SBINDIR; -/** @brief Fink binary directory */ +/** @brief Fink binary directory + * + * Meaningless if not on a Mac. + */ const char finkbindir[] = FINKBINDIR; /* diff --git a/lib/eclient.c b/lib/eclient.c index 38edb64..57680ca 100644 --- a/lib/eclient.c +++ b/lib/eclient.c @@ -17,6 +17,9 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * USA */ +/** @file lib/eclient.c + * @brief Client code for event-driven programs + */ #include #include "types.h" @@ -57,16 +60,18 @@ /* Types *********************************************************************/ +/** @brief Client state */ enum client_state { - state_disconnected, /* not connected */ - state_connecting, /* waiting for connect() */ - state_connected, /* connected but not authenticated */ - state_idle, /* not doing anything */ - state_cmdresponse, /* waiting for command resonse */ - state_body, /* accumulating body */ - state_log, /* monitoring log */ + state_disconnected, /**< @brief not connected */ + state_connecting, /**< @brief waiting for connect() */ + state_connected, /**< @brief connected but not authenticated */ + state_idle, /**< @brief not doing anything */ + state_cmdresponse, /**< @brief waiting for command resonse */ + state_body, /**< @brief accumulating body */ + state_log, /**< @brief monitoring log */ }; +/** @brief Names for @ref client_state */ static const char *const states[] = { "disconnected", "connecting", @@ -79,42 +84,44 @@ static const char *const states[] = { struct operation; /* forward decl */ +/** @brief Type of an operation callback */ typedef void operation_callback(disorder_eclient *c, struct operation *op); -/* A pending operation. This can be either a command or part of the - * authentication protocol. In the former case new commands are appended to - * the list, in the latter case they are inserted at the front. */ +/** @brief A pending operation. + * + * This can be either a command or part of the authentication protocol. In the + * former case new commands are appended to the list, in the latter case they + * are inserted at the front. */ struct operation { - struct operation *next; /* next operation */ - char *cmd; /* command to send or 0 */ - operation_callback *opcallback; /* internal completion callback */ - void (*completed)(); /* user completion callback or 0 */ - void *v; /* data for COMPLETED */ - disorder_eclient *client; /* owning client */ - int sent; /* true if sent to server */ + struct operation *next; /**< @brief next operation */ + char *cmd; /**< @brief command to send or 0 */ + operation_callback *opcallback; /**< @brief internal completion callback */ + void (*completed)(); /**< @brief user completion callback or 0 */ + void *v; /**< @brief data for COMPLETED */ + disorder_eclient *client; /**< @brief owning client */ + int sent; /**< @brief true if sent to server */ }; +/** @brief Client structure */ struct disorder_eclient { const char *ident; - int fd; - enum client_state state; /* current state */ - int authenticated; /* true when authenicated */ - struct dynstr output; /* output buffer */ - struct dynstr input; /* input buffer */ - int eof; /* input buffer is at EOF */ - /* error reporting callbacks */ - const disorder_eclient_callbacks *callbacks; - void *u; - /* operation queuue */ - struct operation *ops, **opstail; + int fd; /**< @brief connection to server */ + enum client_state state; /**< @brief current state */ + int authenticated; /**< @brief true when authenicated */ + struct dynstr output; /**< @brief output buffer */ + struct dynstr input; /**< @brief input buffer */ + int eof; /**< @brief input buffer is at EOF */ + const disorder_eclient_callbacks *callbacks; /**< @brief error callbacks */ + void *u; /**< @brief user data */ + struct operation *ops; /**< @brief queue of operations */ + struct operation **opstail; /**< @brief queue tail */ /* accumulated response */ - int rc; /* response code */ - char *line; /* complete line */ - struct vector vec; /* body */ - /* log client callback */ - const disorder_eclient_log_callbacks *log_callbacks; - void *log_v; - unsigned long statebits; /* current state */ + int rc; /**< @brief response code */ + char *line; /**< @brief complete line */ + struct vector vec; /**< @brief body */ + const disorder_eclient_log_callbacks *log_callbacks; /**< @brief log callbacks */ + void *log_v; /**< @brief user data */ + unsigned long statebits; /**< @brief current state */ }; /* Forward declarations ******************************************************/ @@ -160,13 +167,18 @@ static void logentry_volume(disorder_eclient *c, int nvec, char **vec); /* Tables ********************************************************************/ -static const struct logentry_handler { - const char *name; - int min, max; +/** @brief One possible log entry */ +struct logentry_handler { + const char *name; /**< @brief Entry name */ + int min; /**< @brief Minimum arguments */ + int max; /**< @brief Maximum arguments */ void (*handler)(disorder_eclient *c, int nvec, - char **vec); -} logentry_handlers[] = { + char **vec); /**< @brief Handler function */ +}; + +/** @brief Table for parsing log entries */ +static const struct logentry_handler logentry_handlers[] = { #define LE(X, MIN, MAX) { #X, MIN, MAX, logentry_##X } LE(completed, 1, 1), LE(failed, 2, 2), @@ -183,6 +195,10 @@ static const struct logentry_handler { /* Setup and teardown ********************************************************/ +/** @brief Create a new client + * + * Does NOT connect the client - connections are made (and re-made) on demand. + */ disorder_eclient *disorder_eclient_new(const disorder_eclient_callbacks *cb, void *u) { disorder_eclient *c = xmalloc(sizeof *c); @@ -201,6 +217,7 @@ disorder_eclient *disorder_eclient_new(const disorder_eclient_callbacks *cb, return c; } +/** @brief Disconnect a client */ void disorder_eclient_close(disorder_eclient *c) { struct operation *op; @@ -223,7 +240,7 @@ void disorder_eclient_close(disorder_eclient *c) { /* Error reporting ***********************************************************/ -/* called when a connection error occurs */ +/** @brief called when a connection error occurs */ static int comms_error(disorder_eclient *c, const char *fmt, ...) { va_list ap; char *s; @@ -237,7 +254,7 @@ static int comms_error(disorder_eclient *c, const char *fmt, ...) { return -1; } -/* called when the server reports an error */ +/** @brief called when the server reports an error */ static int protocol_error(disorder_eclient *c, struct operation *op, int code, const char *fmt, ...) { va_list ap; @@ -253,6 +270,15 @@ static int protocol_error(disorder_eclient *c, struct operation *op, /* State machine *************************************************************/ +/** @brief Called when there's something to do + * @param c Client + * @param mode bitmap of @ref DISORDER_POLL_READ and/or @ref DISORDER_POLL_WRITE. + * + * This should be called from by your code when the file descriptor is readable + * or writable (as requested by the @c poll callback, see @ref + * disorder_eclient_callbacks) and in any case from time to time (with @p mode + * = 0) to allow for retries to work. + */ void disorder_eclient_polled(disorder_eclient *c, unsigned mode) { struct operation *op; @@ -385,7 +411,7 @@ void disorder_eclient_polled(disorder_eclient *c, unsigned mode) { if(c->fd != -1) c->callbacks->poll(c->u, c, c->fd, mode); } -/* Called to start connecting */ +/** @brief Called to start connecting */ static int start_connect(void *cc, const struct sockaddr *sa, socklen_t len, @@ -419,7 +445,7 @@ static int start_connect(void *cc, return 0; } -/* Called when maybe connected */ +/** @brief Called when maybe connected */ static void maybe_connected(disorder_eclient *c) { /* We either connected, or got an error. */ int err; diff --git a/lib/eclient.h b/lib/eclient.h index f9311e5..dd8d9ba 100644 --- a/lib/eclient.h +++ b/lib/eclient.h @@ -17,47 +17,73 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * USA */ +/** @file lib/eclient.h + * @brief Client code for event-driven programs + */ #ifndef ECLIENT_H #define ECLIENT_H /* Asynchronous client interface */ +/** @brief Handle type */ typedef struct disorder_eclient disorder_eclient; struct queue_entry; -#define DISORDER_POLL_READ 1u /* want to read FD */ -#define DISORDER_POLL_WRITE 2u /* want to write FD */ +/** @brief Set to read from the FD */ +#define DISORDER_POLL_READ 1u + +/** @brief Set to write to the FD */ +#define DISORDER_POLL_WRITE 2u -/* Callbacks for all clients. These must all be valid. */ +/** @brief Callbacks for all clients + * + * These must all be valid. + */ typedef struct disorder_eclient_callbacks { + /** @brief Called when a communication error (e.g. connected refused) occurs. + * @param u from disorder_eclient_new() + * @param msg error message + */ void (*comms_error)(void *u, const char *msg); - /* Called when a communication error (e.g. connected refused) occurs. U - * comes from the _new() call and MSG describes the problem.*/ + /** @brief Called when a command fails (including initial authorization). + * @param u from disorder_eclient_new() + * @param v from failed command, or NULL if during setup + * @param msg error message + */ void (*protocol_error)(void *u, void *v, int code, const char *msg); - /* Called when a command fails (including initial authorization). U comes - * from the _new() call, V from the failed command or a null pointer if the - * error is in setup and MSG describes the problem. */ - + + /** @brief Set poll/select flags + * @param u from disorder_eclient_new() + * @param c handle + * @param fd file descriptor + * @param mode bitmap (@ref DISORDER_POLL_READ and/or @ref DISORDER_POLL_WRITE) + * + * Before @p fd is closed you will always get a call with @p mode = 0. + */ void (*poll)(void *u, disorder_eclient *c, int fd, unsigned mode); - /* Set poll/select flags for FD according to MODE. FD will never be -1. - * Before FD is closed, you will always get a call with MODE=0. U comes from - * the _new() call. */ + /** @brief Report current activity + * @param u from disorder_eclient_new() + * @param msg Current activity or NULL + * + * Called with @p msg = NULL when there's nothing going on. + */ void (*report)(void *u, const char *msg); - /* Called from time to time to report what's doing. Called with MSG=0 - * when the client goes idle.*/ } disorder_eclient_callbacks; -/* Callbacks for log clients. All of these are allowed to be a null pointers - * in which case you don't get told about that log event. */ +/** @brief Callbacks for log clients + * + * All of these are allowed to be a null pointers in which case you don't get + * told about that log event. + * + * See disorder_protocol(5) for full documentation. + */ typedef struct disorder_eclient_log_callbacks { + /** @brief Called on (re-)connection */ void (*connected)(void *v); - /* Called on (re-)connection */ - - /* See disorder_protocol(5) for documentation for the rest */ void (*completed)(void *v, const char *track); void (*failed)(void *v, const char *track, const char *status); @@ -73,9 +99,15 @@ typedef struct disorder_eclient_log_callbacks { } disorder_eclient_log_callbacks; /* State bits */ -#define DISORDER_PLAYING_ENABLED 0x00000001 /* play is enabled */ -#define DISORDER_RANDOM_ENABLED 0x00000002 /* random play is enabled */ -#define DISORDER_TRACK_PAUSED 0x00000004 /* track is paused */ + +/** @brief Play is enabled */ +#define DISORDER_PLAYING_ENABLED 0x00000001 + +/** @brief Random play is enabled */ +#define DISORDER_RANDOM_ENABLED 0x00000002 + +/** @brief Track is paused */ +#define DISORDER_TRACK_PAUSED 0x00000004 struct queue_entry; struct kvp; diff --git a/server/speaker.h b/server/speaker.h index 53230cb..02de4b2 100644 --- a/server/speaker.h +++ b/server/speaker.h @@ -133,7 +133,7 @@ struct speaker_backend { * Some devices are effectively always open and have no error state, * in which case this callback can be NULL. In this case @ref * FIXED_FORMAT must be set. Note that @ref device_state still - * switches between @ref device_open and @ref device_closd in this + * switches between @ref device_open and @ref device_closed in this * case. */ void (*activate)(void); @@ -154,7 +154,7 @@ struct speaker_backend { * * For sound devices that are open all the time and have no error * state, this callback can be NULL. Note that @ref device_state - * still switches between @ref device_open and @ref device_closd in + * still switches between @ref device_open and @ref device_closed in * this case. */ void (*deactivate)(void); -- [mdw]