doxygen: add some missing docstrings.

diff --git a/cgi/options.c b/cgi/options.c
index 24038331d2bd29cbc5739611286c172e051029d7..521ce354016d1e3dbda11514caca6f5255802e9a 100644 (file)
--- a/cgi/options.c
+++ b/cgi/options.c
@@ -24,8 +24,12 @@
 
 #include "disorder-cgi.h"
 
+/** @brief State for parsing an options file */
 struct read_options_state {
+  /** @brief Filename */
   const char *name;
+
+  /** @brief Line number */
   int line;
 };
 

diff --git a/clients/disorder.c b/clients/disorder.c
index 6d0a29d971b7290f96ae1887662f10a0ff6b75b7..64694ef836cf7b0f29519756e733902411ed93ad 100644 (file)
--- a/clients/disorder.c
+++ b/clients/disorder.c
@@ -504,9 +504,15 @@ static void cf_setup_guest(char **argv) {
     exit(EXIT_FAILURE);
 }
 
+/** @brief A scheduled event read from the server */
 struct scheduled_event {
+  /** @brief When event should occur */
   time_t when;
+
+  /** @brief Details of action */
   struct kvp *actiondata;
+
+  /** @brief Event ID */
   char *id;
 };
 

diff --git a/disobedience/properties.c b/disobedience/properties.c
index 6600cf947ed88b0b7f0ed1caccd7e7cf212cf15d..fb39ea4f23de17212b3e103f6ed6b387b0409bca 100644 (file)
--- a/disobedience/properties.c
+++ b/disobedience/properties.c
@@ -61,23 +61,26 @@ struct prefdata {
   GtkWidget *widget;
 };
 
-/* The type of a preference is the collection of callbacks needed to get,
- * display and set it */
+/** @brief Type of a track preference
+ *
+ * The type of a preference is the collection of callbacks needed to get,
+ * display and set it.
+ */
 struct preftype {
+  /** @brief Kick off the request to fetch the pref from the server. */
   void (*kickoff)(struct prefdata *f);
-  /* Kick off the request to fetch the pref from the server. */
 
+  /** @brief Called when the value comes back in; creates the widget. */
   void (*completed)(struct prefdata *f);
-  /* Called when the value comes back in; creates the widget. */
 
+  /** @brief Get the edited value from the widget. */
   const char *(*get_edited)(struct prefdata *f);
-  /* Get the edited value from the widget. */
 
   /** @brief Update the edited value */
   void (*set_edited)(struct prefdata *f, const char *value);
 
+  /** @brief Set the new value and (if necessary) arrange for our display to update. */
   void (*set)(struct prefdata *f, const char *value);
-  /* Set the new value and (if necessary) arrange for our display to update. */
 };
 
 /* A namepart pref */
@@ -107,7 +110,7 @@ static const struct preftype preftype_boolean = {
   set_boolean
 };
 
-/* @brief The known prefs for each track */
+/** @brief The known prefs for each track */
 static const struct pref {
   const char *label;                    /**< @brief user-level description */
   const char *part;                     /**< @brief protocol-level tag */

diff --git a/disobedience/queue-generic.c b/disobedience/queue-generic.c
index a4cb793c854dba125dc8bf25fedfb7eca848bd1a..2c0ac190e221978a02d826076de4fe9ebf6c9b09 100644 (file)
--- a/disobedience/queue-generic.c
+++ b/disobedience/queue-generic.c
@@ -227,6 +227,10 @@ void ql_update_list_store(struct queuelike *ql) {
   }
 }
 
+/** @brief Old and new queue data
+ *
+ * Used when updating a @ref queuelike with new data from the server.
+ */
 struct newqueue_data {
   struct queue_entry *old, *new;
 };

diff --git a/lib/resample.h b/lib/resample.h
index e99aaeb3455de23d77fef9a981f61bcf0157120a..a78932571726afbe4b5ae11f59cebe9db7e49864 100644 (file)
--- a/lib/resample.h
+++ b/lib/resample.h
@@ -29,12 +29,45 @@
 
 #include "byte-order.h"
 
+/** @brief An audio resampler */
 struct resampler {
-  int input_bits, input_channels, input_rate, input_signed, input_endian;
-  int output_bits, output_channels, output_rate, output_signed, output_endian;
+  /** @brief Bits/sample in input */
+  int input_bits;
+
+  /** @brief Number of input channels */
+  int input_channels;
+
+  /** @brief Frames/second in input */
+  int input_rate;
+
+  /** @brief Whether input samples are signed or unsigned */
+  int input_signed;
+
+  /** @brief Input endianness (@c ENDIAN_BIG or @c ENDIAN_LITTLE) */
+  int input_endian;
+
+  /** @brief Bits/sample in output */
+  int output_bits;
+
+  /** @brief Number of output channels */
+  int output_channels;
+
+  /** @brief Frames/second in output */
+  int output_rate;
+
+  /** @brief Whether output samples are signed or unsigned */
+  int output_signed;
+
+  /** @brief Output endianness (@c ENDIAN_BIG or @c ENDIAN_LITTLE) */
+  int output_endian;
+
+  /** @brief  */
   int input_bytes_per_sample;
+
+  /** @brief  */
   int input_bytes_per_frame;
 #if HAVE_SAMPLERATE_H
+  /** @brief Libsamplerate handle */
   SRC_STATE *state;
 #endif
 };

diff --git a/lib/signame.c b/lib/signame.c
index 27f9509c49653419b7f19fdf8a0e3460035fe23b..316fe6a441fb217e186753d988716f0b741f1934 100644 (file)
--- a/lib/signame.c
+++ b/lib/signame.c
@@ -26,8 +26,12 @@
 #include "table.h"
 #include "signame.h"
 
+/** @brief Mapping between signal names and numbers */
 static const struct sigtable {
+  /** @brief Signal number */
   int signal;
+
+  /* @brief Signal name ("SIGwhatever") */
   const char *name;
 } signals[] = {
 #define S(sig) { sig, #sig }

diff --git a/lib/trackdb.c b/lib/trackdb.c
index 4afd9257929960eb168fb921d383a906a2968fd5..7be53c14d3b92d7866be5ef4b81bd9661d5cad1f 100644 (file)
--- a/lib/trackdb.c
+++ b/lib/trackdb.c
@@ -1389,6 +1389,7 @@ int trackdb_obsolete(const char *track, DB_TXN *tid) {
 #define H(name) { #name, offsetof(DB_HASH_STAT, name) }
 #define B(name) { #name, offsetof(DB_BTREE_STAT, name) }
 
+/** @brief Table of libdb stats to return */
 static const struct statinfo {
   const char *name;
   size_t offset;

diff --git a/python/disorder.py.in b/python/disorder.py.in
index 8584c8598327de17307e8a449853a9ea16283ce0..8a758c9bc11a586a631d6dc5f96722ba368cee51 100644 (file)
--- a/python/disorder.py.in
+++ b/python/disorder.py.in
@@ -87,6 +87,7 @@ class Error(Exception):
   """Base class for DisOrder exceptions."""
 
 class _splitError(Error):
+  """Error parsing a quoted string list"""
   # _split failed
   def __init__(self, value):
     self.value = value

diff --git a/server/disorderd.c b/server/disorderd.c
index 2000a2f2d55aefafb732f30346605d7df2259da9..3e1ab441c897bfcdfd33dd8a74b54cc65a787aa9 100644 (file)
--- a/server/disorderd.c
+++ b/server/disorderd.c
@@ -80,8 +80,12 @@ static int handle_sigterm(ev_source attribute((unused)) *ev_,
 
 /* periodic actions --------------------------------------------------------- */
 
+/** @brief A job executed periodically by the server */
 struct periodic_data {
+  /** @brief Callback to process job */
   void (*callback)(ev_source *);
+
+  /** @brief Period of job in seconds */
   int period;
 };
 

diff --git a/server/plugin.c b/server/plugin.c
index 7afbde9ccd397010b79e7f041f616810e05b6b5f..013aa9415e676498af810172f31465a704c29fbc 100644 (file)
--- a/server/plugin.c
+++ b/server/plugin.c
@@ -28,9 +28,15 @@
 # define SOSUFFIX ".so"
 #endif
 
+/** @brief A loaded plugin */
 struct plugin {
+  /** @brief Next plugin */
   struct plugin *next;
+
+  /** @brief Handle returned from dlopen() */
   void *dlhandle;
+
+  /** @brief Plugin name */
   const char *name;
 };
 

diff --git a/server/rescan.c b/server/rescan.c
index 7cb24b6a3c1ef75538916a8519cf37698e3a562f..71b998ad948798a13ce358045c77b83e5c8e46ec 100644 (file)
--- a/server/rescan.c
+++ b/server/rescan.c
@@ -164,14 +164,33 @@ done:
       ;
 }
 
+/** @brief State for the recheck phase of the rescan */
 struct recheck_state {
+  /** @brief Collection being rechecked */
   const struct collection *c;
-  long nobsolete, nnocollection, nlength;
+
+  /** @brief Number of tracks obsoleted */
+  long nobsolete;
+
+  /** @brief Number of tracks belonging to no collection */
+  long nnocollection;
+
+  /** @brief Number of lengths computed */
+  long nlength;
+
+  /** @brief Linked list of tracks to recheck */
   struct recheck_track *tracks;
 };
 
+/** @brief A track to recheck
+ *
+ * A node in a linked list.
+ */
 struct recheck_track {
+  /** @brief Next track */
   struct recheck_track *next;
+
+  /** @brief Track */
   const char *track;
 };