From 219dc95cf771d5ba07aa19a3b33002a649682060 Mon Sep 17 00:00:00 2001 Message-Id: <219dc95cf771d5ba07aa19a3b33002a649682060.1715097118.git.mdw@distorted.org.uk> From: Mark Wooding Date: Mon, 1 Oct 2007 12:14:18 +0100 Subject: [PATCH] doxygen Organization: Straylight/Edgeware From: Richard Kettlewell --- disobedience/client.c | 39 ++++++++++++++-------- disobedience/control.c | 45 ++++++++++++++++++++++---- disobedience/disobedience.c | 64 ++++++++++++++++++++++++++++++------- disobedience/log.c | 44 ++++++++++++++++++++++++- 4 files changed, 160 insertions(+), 32 deletions(-) diff --git a/disobedience/client.c b/disobedience/client.c index ed93d1b..8a300c4 100644 --- a/disobedience/client.c +++ b/disobedience/client.c @@ -17,10 +17,13 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * USA */ +/** @file disobedience/client.c + * @brief GLIB integration for @ref lib/eclient.c client + */ #include "disobedience.h" -/* GSource subclass for disorder_eclient */ +/** @brief GSource subclass for disorder_eclient */ struct eclient_source { GSource gsource; disorder_eclient *client; @@ -28,8 +31,10 @@ struct eclient_source { GPollFD pollfd; }; -/* Called before FDs are polled to choose a timeout. We ask for a 3s - * timeout and every 10s or so we force a dispatch. */ +/** @brief Called before FDs are polled to choose a timeout. + * + * We ask for a 3s timeout and every 10s or so we force a dispatch. + */ static gboolean gtkclient_prepare(GSource *source, gint *timeout) { const struct eclient_source *esource = (struct eclient_source *)source; @@ -40,7 +45,7 @@ static gboolean gtkclient_prepare(GSource *source, return FALSE; /* please poll */ } -/* Check whether we're ready to dispatch. */ +/** @brief Check whether we're ready to dispatch */ static gboolean gtkclient_check(GSource *source) { const struct eclient_source *esource = (struct eclient_source *)source; D(("gtkclient_check fd=%d events=%x revents=%x", @@ -48,7 +53,7 @@ static gboolean gtkclient_check(GSource *source) { return esource->pollfd.fd != -1 && esource->pollfd.revents != 0; } -/* Dispatch */ +/** @brief Called after poll() (or otherwise) to dispatch an event */ static gboolean gtkclient_dispatch(GSource *source, GSourceFunc attribute((unused)) callback, gpointer attribute((unused)) user_data) { @@ -67,7 +72,7 @@ static gboolean gtkclient_dispatch(GSource *source, return TRUE; /* ??? not documented */ } -/* Table of callbacks for GSource subclass */ +/** @brief Table of callbacks for GSource subclass */ static const GSourceFuncs sourcefuncs = { gtkclient_prepare, gtkclient_check, @@ -77,7 +82,7 @@ static const GSourceFuncs sourcefuncs = { 0, }; -/* Tell the mainloop what we need */ +/** @brief Tell the mainloop what we need */ static void gtkclient_poll(void *u, disorder_eclient attribute((unused)) *c, int fd, unsigned mode) { @@ -106,7 +111,11 @@ static void gtkclient_poll(void *u, } } -/* Report a communication-level error. It will be automatically retried. */ +/** @brief Report a communication-level error + * + * Any operations still outstanding are automatically replied by the underlying + * @ref lib/eclient.c code. + */ static void gtkclient_comms_error(void attribute((unused)) *u, const char *msg) { D(("gtkclient_comms_error %s", msg)); @@ -114,9 +123,11 @@ static void gtkclient_comms_error(void attribute((unused)) *u, gtk_label_set_text(GTK_LABEL(report_label), msg); } -/* Report a protocol error. It will not be retried. We offer a callback to - * the submitter of the original command and if none is supplied we pop up an - * error box. */ +/** @brief Report a protocol-level error + * + * The error will not be retried. We offer a callback to the submitter of the + * original command and if none is supplied we pop up an error box. + */ static void gtkclient_protocol_error(void attribute((unused)) *u, void *v, int code, @@ -130,6 +141,7 @@ static void gtkclient_protocol_error(void attribute((unused)) *u, popup_protocol_error(code, msg); } +/** @brief Report callback from eclient */ static void gtkclient_report(void attribute((unused)) *u, const char *msg) { if(!msg) @@ -138,13 +150,14 @@ static void gtkclient_report(void attribute((unused)) *u, menu_update(-1); } +/** @brief Repoort an unhandled protocol-level error to the user */ void popup_protocol_error(int attribute((unused)) code, const char *msg) { gtk_label_set_text(GTK_LABEL(report_label), msg); popup_error(msg); } -/* Table of eclient callbacks */ +/** @brief Table of eclient callbacks */ static const disorder_eclient_callbacks gtkclient_callbacks = { gtkclient_comms_error, gtkclient_protocol_error, @@ -152,7 +165,7 @@ static const disorder_eclient_callbacks gtkclient_callbacks = { gtkclient_report }; -/* Create an eclient using the GLib main loop */ +/** @brief Create a @ref disorder_ecliient using the GLib main loop */ disorder_eclient *gtkclient(void) { GSource *source; struct eclient_source *esource; diff --git a/disobedience/control.c b/disobedience/control.c index 6efadda..1d05167 100644 --- a/disobedience/control.c +++ b/disobedience/control.c @@ -17,6 +17,9 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * USA */ +/** @file disobedience/control.c + * @brief Volume control and buttons + */ #include "disobedience.h" @@ -53,19 +56,38 @@ static gchar *format_balance(GtkScale *scale, gdouble value); /* Control bar ------------------------------------------------------------- */ +/** @brief Guard against feedback loop in volume control */ static int suppress_set_volume; -/* Guard against feedback loop in volume control */ -static struct icon { +/** @brief Definition of an icon + * + * The design here is rather mad: rather than changing the image displayed by + * icons according to their state, we flip the visibility of pairs of icons. + */ +struct icon { + /** @brief Filename for image */ const char *icon; + + /** @brief Text for tooltip */ const char *tip; + + /** @brief Called when button is clicked (activated) */ void (*clicked)(GtkButton *button, gpointer userdata); + + /** @brief Called to update button when state may have changed */ void (*update)(const struct icon *i); + + /** @brief @ref eclient.h function to call */ int (*action)(disorder_eclient *c, disorder_eclient_no_response *completed, void *v); + + /** @brief Pointer to button */ GtkWidget *button; -} icons[] = { +}; + +/** @brief Table of all icons */ +static struct icon icons[] = { { "pause.png", "Pause playing track", clicked_icon, update_pause, disorder_eclient_pause, 0 }, { "play.png", "Resume playing track", clicked_icon, update_play, @@ -81,9 +103,12 @@ static struct icon { { "notescross.png", "Disable play", clicked_icon, update_disable, disorder_eclient_disable, 0 }, }; + +/** @brief Count of icons */ #define NICONS (int)(sizeof icons / sizeof *icons) -GtkAdjustment *volume_adj, *balance_adj; +static GtkAdjustment *volume_adj; +static GtkAdjustment *balance_adj; /** @brief Called whenever last_state changes in any way */ static void control_monitor(void attribute((unused)) *u) { @@ -94,7 +119,7 @@ static void control_monitor(void attribute((unused)) *u) { icons[n].update(&icons[n]); } -/* Create the control bar */ +/** @brief Create the control bar */ GtkWidget *control_widget(void) { GtkWidget *hbox = gtk_hbox_new(FALSE, 1), *vbox; GtkWidget *content; @@ -250,6 +275,7 @@ static void clicked_icon(GtkButton attribute((unused)) *button, icon->action(client, 0, 0); } +/** @brief Called when the volume has been adjusted */ static void volume_adjusted(GtkAdjustment attribute((unused)) *a, gpointer attribute((unused)) user_data) { double v = gtk_adjustment_get_value(volume_adj) / goesupto; @@ -271,7 +297,7 @@ static void volume_adjusted(GtkAdjustment attribute((unused)) *a, 0); } -/* Called to format the volume value */ +/** @brief Formats the volume value */ static gchar *format_volume(GtkScale attribute((unused)) *scale, gdouble value) { char s[32]; @@ -280,7 +306,7 @@ static gchar *format_volume(GtkScale attribute((unused)) *scale, return g_strdup(s); } -/* Called to format the balance value. */ +/** @brief Formats the balance value */ static gchar *format_balance(GtkScale attribute((unused)) *scale, gdouble value) { char s[32]; @@ -318,10 +344,12 @@ static gchar *format_balance(GtkScale attribute((unused)) *scale, * Thanks to Clive and Andrew. */ +/** @brief Return the greater of @p x and @p y */ static double max(double x, double y) { return x > y ? x : y; } +/** @brief Compute the left channel volume */ static double left(double v, double b) { if(b > 0) /* volume = right */ return v * (1 - b); @@ -329,6 +357,7 @@ static double left(double v, double b) { return v; } +/** @brief Compute the right channel volume */ static double right(double v, double b) { if(b > 0) /* volume = right */ return v; @@ -336,10 +365,12 @@ static double right(double v, double b) { return v * (1 + b); } +/** @brief Compute the overall volume */ static double volume(double l, double r) { return max(l, r); } +/** @brief Compute the balance */ static double balance(double l, double r) { if(l > r) return r / l - 1; diff --git a/disobedience/disobedience.c b/disobedience/disobedience.c index bb06347..dc80d0c 100644 --- a/disobedience/disobedience.c +++ b/disobedience/disobedience.c @@ -17,6 +17,9 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * USA */ +/** @file disobedience/disobedience.c + * @brief Main Disobedience program + */ #include "disobedience.h" @@ -31,18 +34,43 @@ /* Variables --------------------------------------------------------------- */ -GMainLoop *mainloop; /* event loop */ -GtkWidget *toplevel; /* top level window */ -GtkWidget *report_label; /* label for progress indicator */ -GtkWidget *tabs; /* main tabs */ +/** @brief Event loop */ +GMainLoop *mainloop; + +/** @brief Top-level window */ +GtkWidget *toplevel; + +/** @brief Label for progress indicator */ +GtkWidget *report_label; + +/** @brief Main tab group */ +GtkWidget *tabs; + +/** @brief Main client */ +disorder_eclient *client; -disorder_eclient *client; /* main client */ +/** @brief Last reported state + * + * This is updated by log_state(). + */ +unsigned long last_state; + +/** @brief True if some track is playing + * + * This ought to be removed in favour of last_state & DISORDER_PLAYING + */ +int playing; + +/** @brief Left channel volume */ +int volume_l; + +/** @brief Right channel volume */ +int volume_r; -unsigned long last_state; /* last reported state */ -int playing; /* true if playing some track */ -int volume_l, volume_r; /* volume */ double goesupto = 10; /* volume upper bound */ -int choosealpha; /* break up choose by letter */ + +/** @brief Break up choose tab by initial letter */ +int choosealpha; /** @brief True if a NOP is in flight */ static int nop_in_flight; @@ -52,6 +80,10 @@ static int nop_in_flight; /* Note that all the client operations kicked off from here will only complete * after we've entered the event loop. */ +/** @brief Called when main window is deleted + * + * Terminates the program. + */ static gboolean delete_event(GtkWidget attribute((unused)) *widget, GdkEvent attribute((unused)) *event, gpointer attribute((unused)) data) { @@ -59,7 +91,10 @@ static gboolean delete_event(GtkWidget attribute((unused)) *widget, exit(0); /* die immediately */ } -/* Called when the current tab is switched. */ +/** @brief Called when the current tab is switched + * + * Updates the menu settings to correspond to the new page. + */ static void tab_switched(GtkNotebook attribute((unused)) *notebook, GtkNotebookPage attribute((unused)) *page, guint page_num, @@ -67,6 +102,7 @@ static void tab_switched(GtkNotebook attribute((unused)) *notebook, menu_update(page_num); } +/** @brief Create the report box */ static GtkWidget *report_box(void) { GtkWidget *vbox = gtk_vbox_new(FALSE, 0); @@ -78,6 +114,7 @@ static GtkWidget *report_box(void) { return vbox; } +/** @brief Create and populate the main tab group */ static GtkWidget *notebook(void) { tabs = gtk_notebook_new(); g_signal_connect(tabs, "switch-page", G_CALLBACK(tab_switched), 0); @@ -90,6 +127,7 @@ static GtkWidget *notebook(void) { return tabs; } +/** @brief Create and populate the main window */ static void make_toplevel_window(void) { GtkWidget *const vbox = gtk_vbox_new(FALSE, 1); GtkWidget *const rb = report_box(); @@ -212,7 +250,7 @@ static const GMemVTable glib_memvtable = { }; #endif -/* Called once every 10 minutes */ +/** @brief Called once every 10 minutes */ static gboolean periodic(gpointer attribute((unused)) data) { D(("periodic")); /* Expire cached data */ @@ -230,6 +268,10 @@ static gboolean periodic(gpointer attribute((unused)) data) { return TRUE; /* don't remove me */ } +/** @brief Called from time to time + * + * Used for debugging purposes + */ static gboolean heartbeat(gpointer attribute((unused)) data) { static struct timeval last; struct timeval now; diff --git a/disobedience/log.c b/disobedience/log.c index d5878c9..d8dbe35 100644 --- a/disobedience/log.c +++ b/disobedience/log.c @@ -17,6 +17,13 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * USA */ +/** @file disobedience/log.c + * @brief State monitoring + * + * Disobedience relies on the server to tell when essentially anything changes, + * even if it initiated the change itself. It uses the @c log command to + * achieve this. + */ #include "disobedience.h" @@ -51,15 +58,28 @@ const disorder_eclient_log_callbacks log_callbacks = { log_volume }; +/** @brief State monitor + * + * We keep a linked list of everything that is interested in state changes. + */ struct monitor { + /** @brief Next monitor */ struct monitor *next; + + /** @brief State bits of interest */ unsigned long mask; + + /** @brief Function to call if any of @c mask change */ monitor_callback *callback; + + /** @brief User data for callback */ void *u; }; +/** @brief List of monitors */ static struct monitor *monitors; +/** @brief Update everything */ void all_update(void) { playing_update(); queue_update(); @@ -67,6 +87,14 @@ void all_update(void) { volume_update(); } +/** @brief Called when the client connects + * + * Depending on server and network state the TCP connection to the server may + * go up or down many times during the lifetime of Disobedience. This function + * is called whenever it connects. + * + * The intent is to use the monitor logic to achieve this in future. + */ static void log_connected(void attribute((unused)) *v) { /* Don't know what we might have missed while disconnected so update * everything. We get this at startup too and this is how we do the initial @@ -74,12 +102,14 @@ static void log_connected(void attribute((unused)) *v) { all_update(); } +/** @brief Called when the current track finishes playing */ static void log_completed(void attribute((unused)) *v, const char attribute((unused)) *track) { playing = 0; playing_update(); } +/** @brief Called when the current track fails */ static void log_failed(void attribute((unused)) *v, const char attribute((unused)) *track, const char attribute((unused)) *status) { @@ -87,9 +117,10 @@ static void log_failed(void attribute((unused)) *v, playing_update(); } +/** @brief Called when some track is moved within the queue */ static void log_moved(void attribute((unused)) *v, const char attribute((unused)) *user) { - queue_update(); + queue_update(); } static void log_playing(void attribute((unused)) *v, @@ -101,27 +132,35 @@ static void log_playing(void attribute((unused)) *v, * here */ } +/** @brief Called when a track is added to the queue */ static void log_queue(void attribute((unused)) *v, struct queue_entry attribute((unused)) *q) { queue_update(); } +/** @brief Called when a track is added to the recently-played list */ static void log_recent_added(void attribute((unused)) *v, struct queue_entry attribute((unused)) *q) { recent_update(); } +/** @brief Called when a track is removed from the recently-played list + * + * We do nothing here - log_recent_added() suffices. + */ static void log_recent_removed(void attribute((unused)) *v, const char attribute((unused)) *id) { /* nothing - log_recent_added() will trigger the relevant update */ } +/** @brief Called when a track is removed from the queue */ static void log_removed(void attribute((unused)) *v, const char attribute((unused)) *id, const char attribute((unused)) *user) { queue_update(); } +/** @brief Called when the current track is scratched */ static void log_scratched(void attribute((unused)) *v, const char attribute((unused)) *track, const char attribute((unused)) *user) { @@ -129,6 +168,7 @@ static void log_scratched(void attribute((unused)) *v, playing_update(); } +/** @brief Called when a state change occurs */ static void log_state(void attribute((unused)) *v, unsigned long state) { const struct monitor *m; @@ -155,6 +195,7 @@ static void log_state(void attribute((unused)) *v, playing_update(); } +/** @brief Called when volume changes */ static void log_volume(void attribute((unused)) *v, int l, int r) { if(volume_l != l || volume_r != r) { @@ -164,6 +205,7 @@ static void log_volume(void attribute((unused)) *v, } } +/** @brief Add a monitor to the list */ void register_monitor(monitor_callback *callback, void *u, unsigned long mask) { -- [mdw]