From 717ba9873384d81663a2da9eb7071824c30a739f Mon Sep 17 00:00:00 2001 Message-Id: <717ba9873384d81663a2da9eb7071824c30a739f.1714778949.git.mdw@distorted.org.uk> From: Mark Wooding Date: Mon, 1 Oct 2007 14:38:14 +0100 Subject: [PATCH] doxygen Organization: Straylight/Edgeware From: Richard Kettlewell --- disobedience/client.c | 2 +- disobedience/queue.c | 250 ++++++++++++++++++++++++++---------------- lib/ifreq.c | 2 +- lib/wav.c | 2 + server/normalize.c | 2 +- server/speaker.h | 8 +- 6 files changed, 161 insertions(+), 105 deletions(-) diff --git a/disobedience/client.c b/disobedience/client.c index 8a300c4..8abc243 100644 --- a/disobedience/client.c +++ b/disobedience/client.c @@ -165,7 +165,7 @@ static const disorder_eclient_callbacks gtkclient_callbacks = { gtkclient_report }; -/** @brief Create a @ref disorder_ecliient using the GLib main loop */ +/** @brief Create a @ref disorder_eclient using the GLib main loop */ disorder_eclient *gtkclient(void) { GSource *source; struct eclient_source *esource; diff --git a/disobedience/queue.c b/disobedience/queue.c index 65c09d3..33f7e48 100644 --- a/disobedience/queue.c +++ b/disobedience/queue.c @@ -21,15 +21,10 @@ * @brief Queue widgets * * This file provides both the queue widget and the recently-played widget. - */ - -#include "disobedience.h" - -#define HCELLPADDING 4 -#define VCELLPADDING 2 - -/* A queue layout is structured as follows: * + * A queue layout is structured as follows: + * + * 
  *  vbox
  *   titlescroll
  *    titlelayout
@@ -39,6 +34,7 @@
  *    mainlayout
  *     cells[row * N + c]              eventbox (made by wrap_queue_cell)
  *      cells[row * N + c]->child      label (from column constructors)
+ *
* * titlescroll never has any scrollbars. Instead whenever mainscroll's * horizontal adjustment is changed, queue_scrolled adjusts titlescroll to @@ -58,6 +54,14 @@ * too but this way around the d+d code is a bit more self-contained.) */ +#include "disobedience.h" + +/** @brief Horizontal padding for queue cells */ +#define HCELLPADDING 4 + +/** @brief Vertical padding for queue cells */ +#define VCELLPADDING 2 + /* Queue management -------------------------------------------------------- */ WT(label); @@ -93,7 +97,7 @@ static const GtkTargetEntry dragtargets[] = { }; #define NDRAGTARGETS (int)(sizeof dragtargets / sizeof *dragtargets) -/* Definition of a column */ +/** @brief Definition of a column */ struct column { const char *name; /* Column name */ GtkWidget *(*widget)(const struct queuelike *ql, @@ -103,7 +107,10 @@ struct column { gfloat xalign; /* Alignment of the label */ }; -/* Need this in the middle of the types for NCOLUMNS */ +/** @brief Table of columns + * + * Need this in the middle of the types for NCOLUMNS + */ static const struct column columns[] = { { "When", column_when, 0, 1 }, { "Who", column_who, 0, 0 }, @@ -112,72 +119,86 @@ static const struct column columns[] = { { "Title", column_namepart, "title", 0 }, { "Length", column_length, 0, 1 } }; + +/** @brief Number of columns */ #define NCOLUMNS (int)(sizeof columns / sizeof *columns) -/* Data passed to menu item activation handlers */ +/** @brief Data passed to menu item activation handlers */ struct menuiteminfo { - struct queuelike *ql; /* which queue we're dealing with */ - struct queue_entry *q; /* hovered entry or 0 */ + struct queuelike *ql; /**< @brief which queue we're dealing with */ + struct queue_entry *q; /**< @brief hovered entry or 0 */ }; +/** @brief An item in the queue's popup menu */ struct menuitem { - /* Parameters */ - const char *name; /* name */ + /** @brief Menu item name */ + const char *name; - /* Callbacks */ + /** @brief Called to activate the menu item + * + * The user data is the queue entry that the pointer was over when the menu + * popped up. */ void (*activate)(GtkMenuItem *menuitem, gpointer user_data); - /* Called to activate the menu item. The user data is the queue entry that - * the pointer was over when the menu popped up. */ + /** @brief Called to determine whether the menu item is usable. + * + * Returns @c TRUE if it should be sensitive and @c FALSE otherwise. @p q + * points to the queue entry the pointer is over. + */ int (*sensitive)(struct queuelike *ql, struct menuitem *m, struct queue_entry *q); - /* Called to determine whether the menu item is usable. Returns TRUE if it - * should be sensitive and FALSE otherwise. Q points to the queue entry the - * pointer is over. */ - /* State */ - gulong handlerid; /* signal handler ID */ - GtkWidget *w; /* menu item widget */ + /** @brief Signal handler ID */ + gulong handlerid; + + /** @brief Widget for menu item */ + GtkWidget *w; }; +/** @brief A queue-like object + * + * There are (currently) two of these: @ref ql_queue and @ref ql_recent. + */ struct queuelike { - /* Parameters */ - const char *name; /* queue or recent */ + /** @brief Name of this queue */ + const char *name; - /* Callbacks */ + /** @brief Called when an update completes */ void (*notify)(void); - /* Called when an update completes. */ - + + /** @brief Called to fix up the queue after update + * @param q The list passed back from the server + * @return Assigned to @c ql->q + */ struct queue_entry *(*fixup)(struct queue_entry *q); - /* Fix up the queue after update, or 0. Q is the list passed back from the - * server, the return value is assigned to ql->q. */ /* Widgets */ - GtkWidget *mainlayout; /* main layout */ - GtkWidget *mainscroll; /* scroller for main layout */ - GtkWidget *titlelayout; /* title layout */ - GtkWidget *titlecells[NCOLUMNS + 1]; /* title cells */ - GtkWidget **cells; /* all the cells */ - GtkWidget *menu; /* popup menu */ - struct menuitem *menuitems; /* menu items */ - GtkWidget *dragmark; /* drag destination marker */ - GtkWidget **dropzones; /* drag targets */ + GtkWidget *mainlayout; /**< @brief main layout */ + GtkWidget *mainscroll; /**< @brief scroller for main layout */ + GtkWidget *titlelayout; /**< @brief title layout */ + GtkWidget *titlecells[NCOLUMNS + 1]; /**< @brief title cells */ + GtkWidget **cells; /**< @brief all the cells */ + GtkWidget *menu; /**< @brief popup menu */ + struct menuitem *menuitems; /**< @brief menu items */ + GtkWidget *dragmark; /**< @brief drag destination marker */ + GtkWidget **dropzones; /**< @brief drag targets */ /* State */ - struct queue_entry *q; /* head of queue */ - struct queue_entry *last_click; /* last click */ - int nrows; /* number of rows */ - int mainrowheight; /* height of one row */ - hash *selection; /* currently selected items */ - int swallow_release; /* swallow button release from drag */ + struct queue_entry *q; /**< @brief head of queue */ + struct queue_entry *last_click; /**< @brief last click */ + int nrows; /**< @brief number of rows */ + int mainrowheight; /**< @brief height of one row */ + hash *selection; /**< @brief currently selected items */ + int swallow_release; /**< @brief swallow button release from drag */ }; -static struct queuelike ql_queue, ql_recent; /* queue and recently played */ -static struct queue_entry *actual_queue; /* actual queue */ -static struct queue_entry *playing_track; /* currenty playing */ -static time_t last_playing = (time_t)-1; /* when last got playing */ +static struct queuelike ql_queue; /**< @brief The main queue */ +static struct queuelike ql_recent; /*< @brief Recently-played tracks */ +static struct queue_entry *actual_queue; /**< @brief actual queue */ +static struct queue_entry *playing_track; /**< @brief currenty playing */ +static time_t last_playing = (time_t)-1; /**< @brief when last got playing */ static int namepart_lookups_outstanding; static int namepart_completions_deferred; /* # of completions not processed */ static const struct cache_type cachetype_string = { 3600 }; @@ -220,7 +241,7 @@ static void dump_layout(const struct queuelike *ql) { /* Track detail lookup ----------------------------------------------------- */ -/* A namepart lookup has completed or failed. */ +/** @brief Called when a namepart lookup has completed or failed */ static void namepart_completed_or_failed(void) { D(("namepart_completed_or_failed")); --namepart_lookups_outstanding; @@ -231,7 +252,7 @@ static void namepart_completed_or_failed(void) { } } -/* A namepart lookup has completed. */ +/** @brief Called when A namepart lookup has completed */ static void namepart_completed(void *v, const char *value) { struct callbackdata *cbd = v; @@ -241,7 +262,7 @@ static void namepart_completed(void *v, const char *value) { namepart_completed_or_failed(); } -/* A length lookup has completed. */ +/** @brief Called when a length lookup has completed */ static void length_completed(void *v, long l) { struct callbackdata *cbd = v; long *value; @@ -254,7 +275,7 @@ static void length_completed(void *v, long l) { namepart_completed_or_failed(); } -/* A length or namepart lookup has failed. */ +/** @brief Called when a length or namepart lookup has failed */ static void namepart_protocol_error( struct callbackdata attribute((unused)) *cbd, int attribute((unused)) code, @@ -264,7 +285,7 @@ static void namepart_protocol_error( namepart_completed_or_failed(); } -/* Arrange to fill in a namepart cache entry */ +/** @brief Arrange to fill in a namepart cache entry */ static void namepart_fill(const char *track, const char *context, const char *part, @@ -279,9 +300,10 @@ static void namepart_fill(const char *track, track, context, part, cbd); } -/* Look up a namepart. If it is in the cache then just return its value. If - * not then look it up and arrange for the queues to be updated when its value - * is available. */ +/** @brief Look up a namepart + * + * If it is in the cache then just return its value. If not then look it up + * and arrange for the queues to be updated when its value is available. */ static const char *namepart(const char *track, const char *context, const char *part) { @@ -302,7 +324,7 @@ static const char *namepart(const char *track, return value; } -/* Called from properties.c when we know a name part has changed */ +/** @brief Called from @ref disobedience/properties.c when we know a name part has changed */ void namepart_update(const char *track, const char *context, const char *part) { @@ -315,9 +337,10 @@ void namepart_update(const char *track, namepart_fill(track, context, part, key); } -/* Look up a track length. If it is in the cache then just return its value. - * If not then look it up and arrange for the queues to be updated when its - * value is available. */ +/** @brief Look up a track length + * + * If it is in the cache then just return its value. If not then look it up + * and arrange for the queues to be updated when its value is available. */ static long getlength(const char *track) { char *key; const long *value; @@ -341,7 +364,7 @@ static long getlength(const char *track) { /* Column constructors ----------------------------------------------------- */ -/* Format the 'when' column */ +/** @brief Format the 'when' column */ static GtkWidget *column_when(const struct queuelike attribute((unused)) *ql, const struct queue_entry *q, const char attribute((unused)) *data) { @@ -377,7 +400,7 @@ static GtkWidget *column_when(const struct queuelike attribute((unused)) *ql, return gtk_label_new(when); } -/* Format the 'who' column */ +/** @brief Format the 'who' column */ static GtkWidget *column_who(const struct queuelike attribute((unused)) *ql, const struct queue_entry *q, const char attribute((unused)) *data) { @@ -386,7 +409,7 @@ static GtkWidget *column_who(const struct queuelike attribute((unused)) *ql, return gtk_label_new(q->submitter ? q->submitter : ""); } -/* Format one of the track name columns */ +/** @brief Format one of the track name columns */ static GtkWidget *column_namepart(const struct queuelike attribute((unused)) *ql, const struct queue_entry *q, @@ -396,7 +419,7 @@ static GtkWidget *column_namepart(const struct queuelike return gtk_label_new(namepart(q->track, "display", data)); } -/* Compute the length field */ +/** @brief Compute the length field */ static const char *text_length(const struct queue_entry *q) { long l; time_t now; @@ -425,7 +448,7 @@ static const char *text_length(const struct queue_entry *q) { return length; } -/* Format the length column */ +/** @brief Format the length column */ static GtkWidget *column_length(const struct queuelike attribute((unused)) *ql, const struct queue_entry *q, const char attribute((unused)) *data) { @@ -445,7 +468,7 @@ static GtkWidget *column_length(const struct queuelike attribute((unused)) *ql, } -/* Apply a new queue contents, transferring the selection from the old value */ +/** @brief Apply a new queue contents, transferring the selection from the old value */ static void update_queue(struct queuelike *ql, struct queue_entry *newq) { struct queue_entry *q; @@ -469,7 +492,7 @@ static void update_queue(struct queuelike *ql, struct queue_entry *newq) { selection_cleanup(ql->selection); } -/* Wrap up a widget for putting into the queue or title */ +/** @brief Wrap up a widget for putting into the queue or title */ static GtkWidget *wrap_queue_cell(GtkWidget *label, const char *name, int *wp) { @@ -495,7 +518,7 @@ static GtkWidget *wrap_queue_cell(GtkWidget *label, return bg; } -/* Create the wrapped widget for a cell in the queue display */ +/** @brief Create the wrapped widget for a cell in the queue display */ static GtkWidget *get_queue_cell(struct queuelike *ql, const struct queue_entry *q, int row, @@ -509,7 +532,7 @@ static GtkWidget *get_queue_cell(struct queuelike *ql, return wrap_queue_cell(label, name, wp); } -/* Add a padding cell to the end of a row */ +/** @brief Add a padding cell to the end of a row */ static GtkWidget *get_padding_cell(const char *name) { D(("get_padding_cell")); NW(label); @@ -518,7 +541,7 @@ static GtkWidget *get_padding_cell(const char *name) { /* User button press and menu ---------------------------------------------- */ -/* Update widget states in order to reflect the selection status */ +/** @brief Update widget states in order to reflect the selection status */ static void set_widget_states(struct queuelike *ql) { struct queue_entry *q; int row, col; @@ -533,6 +556,7 @@ static void set_widget_states(struct queuelike *ql) { menu_update(-1); } +/** @brief Ordering function for queue entries */ static int queue_before(const struct queue_entry *a, const struct queue_entry *b) { while(a && a != b) @@ -540,7 +564,7 @@ static int queue_before(const struct queue_entry *a, return !!a; } -/* A button was pressed and released */ +/** @brief A button was pressed and released */ static gboolean queuelike_button_released(GtkWidget attribute((unused)) *widget, GdkEventButton *event, gpointer user_data) { @@ -634,14 +658,16 @@ static gboolean queuelike_button_released(GtkWidget attribute((unused)) *widget, return FALSE; /* propagate */ } -/* A button was pressed or released on the mainlayout. For debugging only at - * the moment. */ +/** @brief A button was pressed or released on the mainlayout + * + * For debugging only at the moment. */ static gboolean mainlayout_button(GtkWidget attribute((unused)) *widget, GdkEventButton attribute((unused)) *event, gpointer attribute((unused)) user_data) { return FALSE; /* propagate */ } +/** @brief Select all entries in a queue */ void queue_select_all(struct queuelike *ql) { struct queue_entry *qq; @@ -651,6 +677,7 @@ void queue_select_all(struct queuelike *ql) { set_widget_states(ql); } +/** @brief Pop up properties for selected tracks */ void queue_properties(struct queuelike *ql) { struct vector v; const struct queue_entry *qq; @@ -665,11 +692,12 @@ void queue_properties(struct queuelike *ql) { /* Drag and drop rearrangement --------------------------------------------- */ +/** @brief Return nonzero if @p is a draggable row */ static int draggable_row(const struct queue_entry *q) { return q->ql == &ql_queue && q != playing_track; } -/* Called when a drag begings */ +/** @brief Called when a drag begings */ static void queue_drag_begin(GtkWidget attribute((unused)) *widget, GdkDragContext attribute((unused)) *dc, gpointer data) { @@ -692,7 +720,7 @@ static void queue_drag_begin(GtkWidget attribute((unused)) *widget, add_drag_targets(ql); } -/* Convert an ID back into a queue entry and a screen row number */ +/** @brief Convert @p id back into a queue entry and a screen row number */ static struct queue_entry *findentry(struct queuelike *ql, const char *id, int *rowp) { @@ -710,7 +738,7 @@ static struct queue_entry *findentry(struct queuelike *ql, return q; } -/* Called when data is dropped */ +/** @brief Called when data is dropped */ static gboolean queue_drag_drop(GtkWidget attribute((unused)) *widget, GdkDragContext *drag_context, gint attribute((unused)) x, @@ -736,7 +764,7 @@ static gboolean queue_drag_drop(GtkWidget attribute((unused)) *widget, return TRUE; } -/* Called when we enter, or move within, a drop zone */ +/** @brief Called when we enter, or move within, a drop zone */ static gboolean queue_drag_motion(GtkWidget attribute((unused)) *widget, GdkDragContext *drag_context, gint attribute((unused)) x, @@ -769,7 +797,7 @@ static gboolean queue_drag_motion(GtkWidget attribute((unused)) *widget, return FALSE; } -/* Called when we leave a drop zone */ +/** @brief Called when we leave a drop zone */ static void queue_drag_leave(GtkWidget attribute((unused)) *widget, GdkDragContext attribute((unused)) *drag_context, guint attribute((unused)) when, @@ -780,8 +808,10 @@ static void queue_drag_leave(GtkWidget attribute((unused)) *widget, gtk_widget_hide(ql->dragmark); } -/* Add a drag target at position Y. ID is the track to insert the moved tracks - * after, and might be 0 to insert before the start. */ +/** @brief Add a drag target at position @p y + * + * @p id is the track to insert the moved tracks after, and might be 0 to + * insert before the start. */ static void add_drag_target(struct queuelike *ql, int y, int row, const char *id) { GtkWidget *eventbox; @@ -816,7 +846,7 @@ static void add_drag_target(struct queuelike *ql, int y, int row, G_CALLBACK(gtk_widget_destroyed), &ql->dropzones[row]); } -/* Create dropzones for dragging into */ +/** @brief Create dropzones for dragging into */ static void add_drag_targets(struct queuelike *ql) { int row, y; struct queue_entry *q; @@ -835,7 +865,7 @@ static void add_drag_targets(struct queuelike *ql) { } } -/* Remove the dropzones */ +/** @brief Remove the dropzones */ static void remove_drag_targets(struct queuelike *ql) { int row; @@ -850,7 +880,7 @@ static void remove_drag_targets(struct queuelike *ql) { /* Layout ------------------------------------------------------------------ */ -/* Redisplay the queue. */ +/** @brief Redisplay a queue */ static void redisplay_queue(struct queuelike *ql) { struct queue_entry *q; int row, col; @@ -965,7 +995,7 @@ static void redisplay_queue(struct queuelike *ql) { gtk_widget_set_size_request(ql->titlelayout, -1, titlerowheight); } -/* Called with new queue/recent contents */ +/** @brief Called with new queue/recent contents */ static void queuelike_completed(void *v, struct queue_entry *q) { struct callbackdata *cbd = v; struct queuelike *ql = cbd->u.ql; @@ -981,7 +1011,7 @@ static void queuelike_completed(void *v, struct queue_entry *q) { menu_update(-1); } -/* Called with a new currently playing track */ +/** @brief Called with a new currently playing track */ static void playing_completed(void attribute((unused)) *v, struct queue_entry *q) { struct callbackdata cbd; @@ -994,6 +1024,7 @@ static void playing_completed(void attribute((unused)) *v, queuelike_completed(&cbd, actual_queue); } +/** @brief Called when the queue is scrolled */ static void queue_scrolled(GtkAdjustment *adjustment, gpointer user_data) { GtkAdjustment *titleadj = user_data; @@ -1002,7 +1033,7 @@ static void queue_scrolled(GtkAdjustment *adjustment, gtk_adjustment_set_value(titleadj, adjustment->value); } -/* Create a queuelike thing (queue/recent) */ +/** @brief Create a queuelike thing (queue/recent) */ static GtkWidget *queuelike(struct queuelike *ql, struct queue_entry *(*fixup)(struct queue_entry *), void (*notify)(void), @@ -1072,12 +1103,12 @@ static GtkWidget *queuelike(struct queuelike *ql, /* Popup menu items -------------------------------------------------------- */ -/* Count the number of items selected */ +/** @brief Count the number of items selected */ static int queue_count_selected(const struct queuelike *ql) { return hash_count(ql->selection); } -/* Count the number of items selected */ +/** @brief Count the number of items selected */ static int queue_count_entries(const struct queuelike *ql) { int nitems = 0; const struct queue_entry *q; @@ -1087,8 +1118,8 @@ static int queue_count_entries(const struct queuelike *ql) { return nitems; } -/* Count the number of items selected, excluding the playing track if there is - * one */ +/** @brief Count the number of items selected, excluding the playing track if + * there is one */ static int count_selected_nonplaying(const struct queuelike *ql) { int nselected = queue_count_selected(ql); @@ -1097,6 +1128,7 @@ static int count_selected_nonplaying(const struct queuelike *ql) { return nselected; } +/** @brief Determine whether the scratch option should be sensitive */ static int scratch_sensitive(struct queuelike attribute((unused)) *ql, struct menuitem attribute((unused)) *m, struct queue_entry attribute((unused)) *q) { @@ -1106,12 +1138,14 @@ static int scratch_sensitive(struct queuelike attribute((unused)) *ql, && selection_selected(ql->selection, playing_track->id)); } +/** @brief Scratch the playing track */ static void scratch_activate(GtkMenuItem attribute((unused)) *menuitem, gpointer attribute((unused)) user_data) { if(playing_track) disorder_eclient_scratch(client, playing_track->id, 0, 0); } +/** @brief Determine whether the remove option should be sensitive */ static int remove_sensitive(struct queuelike *ql, struct menuitem attribute((unused)) *m, struct queue_entry *q) { @@ -1123,6 +1157,7 @@ static int remove_sensitive(struct queuelike *ql, || count_selected_nonplaying(ql))); } +/** @brief Remove selected track(s) */ static void remove_activate(GtkMenuItem attribute((unused)) *menuitem, gpointer user_data) { const struct menuiteminfo *mii = user_data; @@ -1139,6 +1174,7 @@ static void remove_activate(GtkMenuItem attribute((unused)) *menuitem, disorder_eclient_remove(client, q->id, 0, 0); } +/** @brief Determine whether the properties menu option should be sensitive */ static int properties_sensitive(struct queuelike *ql, struct menuitem attribute((unused)) *m, struct queue_entry attribute((unused)) *q) { @@ -1147,6 +1183,7 @@ static int properties_sensitive(struct queuelike *ql, && (disorder_eclient_state(client) & DISORDER_CONNECTED)); } +/** @brief Pop up properties for the selected tracks */ static void properties_activate(GtkMenuItem attribute((unused)) *menuitem, gpointer user_data) { const struct menuiteminfo *mii = user_data; @@ -1154,6 +1191,7 @@ static void properties_activate(GtkMenuItem attribute((unused)) *menuitem, queue_properties(mii->ql); } +/** @brief Determine whether the select all menu option should be sensitive */ static int selectall_sensitive(struct queuelike *ql, struct menuitem attribute((unused)) *m, struct queue_entry attribute((unused)) *q) { @@ -1161,6 +1199,7 @@ static int selectall_sensitive(struct queuelike *ql, return !!ql->q; } +/** @brief Select all tracks */ static void selectall_activate(GtkMenuItem attribute((unused)) *menuitem, gpointer user_data) { const struct menuiteminfo *mii = user_data; @@ -1169,7 +1208,7 @@ static void selectall_activate(GtkMenuItem attribute((unused)) *menuitem, /* The queue --------------------------------------------------------------- */ -/* Fix up the queue by sticking the currently playing track on the front */ +/** @brief Fix up the queue by sticking the currently playing track on the front */ static struct queue_entry *fixup_queue(struct queue_entry *q) { D(("fixup_queue")); actual_queue = q; @@ -1182,7 +1221,9 @@ static struct queue_entry *fixup_queue(struct queue_entry *q) { return actual_queue; } -/* Called regularly to adjust the so-far played label (redrawing the whole +/** @brief Adjust track played label + * + * Called regularly to adjust the so-far played label (redrawing the whole * queue once a second makes disobedience occupy >10% of the CPU on my Athlon * which is ureasonable expensive) */ static gboolean adjust_sofar(gpointer attribute((unused)) data) { @@ -1192,8 +1233,9 @@ static gboolean adjust_sofar(gpointer attribute((unused)) data) { return TRUE; } -/* Popup menu for the queue. Put the properties first so that finger trouble - * is less dangerous. */ +/** @brief Popup menu for the queue + * + * Properties first so that finger trouble is less dangerous. */ static struct menuitem queue_menu[] = { { "Track properties", properties_activate, properties_sensitive, 0, 0 }, { "Select all tracks", selectall_activate, selectall_sensitive, 0, 0 }, @@ -1226,6 +1268,11 @@ GtkWidget *queue_widget(void) { "queue"); } +/** @brief Arrange an update of the queue widget + * + * Called when a track is added to the queue, removed from the queue (by user + * cmmand or because it is to be played) or moved within the queue + */ void queue_update(void) { struct callbackdata *cbd; @@ -1239,8 +1286,10 @@ void queue_update(void) { /* Recently played tracks -------------------------------------------------- */ +/** @brief Fix up the recently played list + * + * It's in the wrong order! TODO fix this globally */ static struct queue_entry *fixup_recent(struct queue_entry *q) { - /* 'recent' is in the wrong order. TODO: globally fix this! */ struct queue_entry *qr = 0, *qn; D(("fixup_recent")); @@ -1257,17 +1306,23 @@ static struct queue_entry *fixup_recent(struct queue_entry *q) { return qr; } +/** @brief Pop-up menu for recently played list */ static struct menuitem recent_menu[] = { { "Track properties", properties_activate, properties_sensitive,0, 0 }, { "Select all tracks", selectall_activate, selectall_sensitive, 0, 0 }, { 0, 0, 0, 0, 0 } }; +/** @brief Create the recently-played list */ GtkWidget *recent_widget(void) { D(("recent_widget")); return queuelike(&ql_recent, fixup_recent, 0, recent_menu, "recent"); } +/** @brief Update the recently played list + * + * Called whenever a track is added to it or removed from it. + */ void recent_update(void) { struct callbackdata *cbd; @@ -1307,6 +1362,7 @@ static const struct tabtype tabtype_queue = { /* Other entry points ------------------------------------------------------ */ +/** @brief Return nonzero if @p track is in the queue */ int queued(const char *track) { struct queue_entry *q; diff --git a/lib/ifreq.c b/lib/ifreq.c index 91d5090..e0489ec 100644 --- a/lib/ifreq.c +++ b/lib/ifreq.c @@ -17,7 +17,7 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * USA */ -/** @file lib/ffreq.c +/** @file lib/ifreq.c * @brief Network interface support */ diff --git a/lib/wav.c b/lib/wav.c index 4197068..c7d4b93 100644 --- a/lib/wav.c +++ b/lib/wav.c @@ -211,7 +211,9 @@ void wav_destroy(struct wavfile *f) { } /** @brief Visit all the data in a WAV file + * @param f WAV file handle * @param callback Called for successive blocks of data + * @param u User data * * @p callback will only ever be passed whole frames. */ diff --git a/server/normalize.c b/server/normalize.c index ddbd725..dc69bb5 100644 --- a/server/normalize.c +++ b/server/normalize.c @@ -17,7 +17,7 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * USA */ -/** @file server/disorder-normalize.c +/** @file server/normalize.c * @brief Convert "raw" format output to the configured format * * Currently we invoke sox even for trivial conversions such as byte-swapping. diff --git a/server/speaker.h b/server/speaker.h index 9a48ca6..c1a76e2 100644 --- a/server/speaker.h +++ b/server/speaker.h @@ -135,11 +135,9 @@ struct speaker_backend { * If it is @ref device_closed then the device should be opened with * the right sample format. * - * 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_closed in this - * case. + * Some devices are effectively always open and have no error state, in which + * case this callback can be NULL. Note that @ref device_state still + * switches between @ref device_open and @ref device_closed in this case. */ void (*activate)(void); -- [mdw]