chiark / gitweb /
doxygen
authorRichard Kettlewell <rjk@greenend.org.uk>
Mon, 1 Oct 2007 13:38:14 +0000 (14:38 +0100)
committerRichard Kettlewell <rjk@greenend.org.uk>
Mon, 1 Oct 2007 13:38:14 +0000 (14:38 +0100)
disobedience/client.c
disobedience/queue.c
lib/ifreq.c
lib/wav.c
server/normalize.c
server/speaker.h

index 8a300c4..8abc243 100644 (file)
@@ -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;
index 65c09d3..33f7e48 100644 (file)
  * @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:
+ *
+ * <pre>
  *  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)
+ * </pre>
  *
  * titlescroll never has any scrollbars.  Instead whenever mainscroll's
  * horizontal adjustment is changed, queue_scrolled adjusts titlescroll to
  * 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;
 
index 91d5090..e0489ec 100644 (file)
@@ -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
  */
 
index 4197068..c7d4b93 100644 (file)
--- 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.
  */
index ddbd725..dc69bb5 100644 (file)
@@ -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.
index 9a48ca6..c1a76e2 100644 (file)
@@ -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);