doxygen: add some missing docstrings.

diff --git a/cgi/options.c b/cgi/options.c
index 2403833..521ce35 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 6d0a29d..64694ef 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 6600cf9..fb39ea4 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 a4cb793..2c0ac19 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 e99aaeb..a789325 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 27f9509..316fe6a 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 4afd925..7be53c1 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 8584c85..8a758c9 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 2000a2f..3e1ab44 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 7afbde9..013aa94 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 7cb24b6..71b998a 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;
 };