doxygen

diff --git a/disobedience/client.c b/disobedience/client.c
index 8a300c4a235857427220264f4cdee37069c5abeb..8abc243ddd8b612df5b693e316ee8fa7c287fe77 100644 (file)
--- a/disobedience/client.c
+++ b/disobedience/client.c
@@ -165,7 +165,7 @@ static const disorder_eclient_callbacks gtkclient_callbacks = {
   gtkclient_report
 };
 
   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;
 disorder_eclient *gtkclient(void) {
   GSource *source;
   struct eclient_source *esource;

diff --git a/disobedience/queue.c b/disobedience/queue.c
index 65c09d30a0d37f178d3e24469418035a1efedc30..33f7e482c5b652b0363481c47b2f59c0e4465160 100644 (file)
--- 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.
  * @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
  *  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)
  *    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
  *
  * 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.)
  */
 
  * 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);
 /* Queue management -------------------------------------------------------- */
 
 WT(label);


@@ -93,7 +97,7 @@ static const GtkTargetEntry dragtargets[] = {
 };
 #define NDRAGTARGETS (int)(sizeof dragtargets / sizeof *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,
 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 */
 };
 
   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 },
 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 }
 };
   { "Title",  column_namepart, "title",  0 },
   { "Length", column_length,   0,        1 }
 };

+
+/** @brief Number of columns */

 #define NCOLUMNS (int)(sizeof columns / sizeof *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 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 {
 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);
   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);
   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 {
 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);
   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);
   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 */
 
   /* 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 */
 
   /* 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 };
 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 ----------------------------------------------------- */
 
 
 /* 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;
 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;
 
 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();
 }
 
   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;
 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();
 }
 
   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,
 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();
 }
 
   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,
 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);
 }
 
                             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) {
 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;
 }
 
   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) {
 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);
 }
 
     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;
 static long getlength(const char *track) {
   char *key;
   const long *value;


@@ -341,7 +364,7 @@ static long getlength(const char *track) {
 
 /* Column constructors ----------------------------------------------------- */
 
 
 /* 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) {
 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);
 }
 
   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) {
 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 : "");
 }
 
   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,
 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));
 }
 
   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;
 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;
 }
 
     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) {
 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;
 
 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);
 }
 
   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) {
 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;
 }
 
   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,
 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);
 }
 
   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);
 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 ---------------------------------------------- */
 
 
 /* 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;
 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);
 }
 
   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)
 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;
 }
 
   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) {
 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 */
 }
 
   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 */
 }
 
 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;
 
 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);
 }
 
   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;
 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 --------------------------------------------- */
 
 
 /* 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;
 }
 
 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) {
 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);
 }
 
   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) {
 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;
 }
 
   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,
 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;
 }
 
   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,
 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;
 }                              
 
     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,
 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);
 }
 
     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;
 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]);
 }
 
                    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;
 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;
 
 static void remove_drag_targets(struct queuelike *ql) {
   int row;
 


@@ -850,7 +880,7 @@ static void remove_drag_targets(struct queuelike *ql) {
 
 /* Layout ------------------------------------------------------------------ */
 
 
 /* Layout ------------------------------------------------------------------ */
 

-/* Redisplay the queue. */
+/** @brief Redisplay a queue */

 static void redisplay_queue(struct queuelike *ql) {
   struct queue_entry *q;
   int row, col;
 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);
 }
 
   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;
 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);
 }
 
   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;
 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);
 }
 
   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;
 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);
 }
 
   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),
 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 -------------------------------------------------------- */
 
 
 /* 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);
 }
 
 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;
 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;
 }
 
   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);
 
 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;
 }
 
   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) {
 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));
 }
 
           && 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);
 }
 
 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) {
 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)));
 }
 
               || 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;
 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);
 }
 
     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) {
 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));
 }
 
           && (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;
 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);
 }
 
   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) {
 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;
 }
 
   return !!ql->q;
 }
 

+/** @brief Select all tracks */

 static void selectall_activate(GtkMenuItem attribute((unused)) *menuitem,
                                gpointer user_data) {
   const struct menuiteminfo *mii = user_data;
 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 --------------------------------------------------------------- */
 
 
 /* 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;
 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;
 }
 
     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) {
  * 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;
 }
 
   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 },
 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");
 }
 
                    "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;
 
 void queue_update(void) {
   struct callbackdata *cbd;
 


@@ -1239,8 +1286,10 @@ void queue_update(void) {
 
 /* Recently played tracks -------------------------------------------------- */
 
 
 /* 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) {
 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"));
   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;
 }
 
   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 }
 };
 
 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");
 }
 
 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;
 
 void recent_update(void) {
   struct callbackdata *cbd;
 


@@ -1307,6 +1362,7 @@ static const struct tabtype tabtype_queue = {
 
 /* Other entry points ------------------------------------------------------ */
 
 
 /* Other entry points ------------------------------------------------------ */
 

+/** @brief Return nonzero if @p track is in the queue */

 int queued(const char *track) {
   struct queue_entry *q;
 
 int queued(const char *track) {
   struct queue_entry *q;
 

diff --git a/lib/ifreq.c b/lib/ifreq.c
index 91d5090c209cdadabc75fb1e84c0366b772a2d38..e0489ec860def6b123e02bfe9df74cd6aa60102c 100644 (file)
--- a/lib/ifreq.c
+++ b/lib/ifreq.c
@@ -17,7 +17,7 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  * USA
  */
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  * USA
  */

-/** @file lib/ffreq.c
+/** @file lib/ifreq.c

  * @brief Network interface support
  */
 
  * @brief Network interface support
  */
 

diff --git a/lib/wav.c b/lib/wav.c
index 4197068130f9d709e57a1ea129acf52f2fcf9d72..c7d4b9397fa42f9b3ff696adf95e123989aa2a8a 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
 }
 
 /** @brief Visit all the data in a WAV file

+ * @param f WAV file handle

  * @param callback Called for successive blocks of data
  * @param callback Called for successive blocks of data

+ * @param u User data

  *
  * @p callback will only ever be passed whole frames.
  */
  *
  * @p callback will only ever be passed whole frames.
  */

diff --git a/server/normalize.c b/server/normalize.c
index ddbd72599c447f53d10174b8ea09d3af9319b8d6..dc69bb5fc4cdb277f7e5a43541796f139b298985 100644 (file)
--- a/server/normalize.c
+++ b/server/normalize.c
@@ -17,7 +17,7 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  * USA
  */
  * 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.
  * @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 9a48ca60690de70699215f7cec62bb267803456d..c1a76e2ebdfecd367853ab00a5645a995e263c6c 100644 (file)
--- 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.
    *
    * 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);
 
    */
   void (*activate)(void);