From: Richard Kettlewell <rjk@terraraq.org.uk>
Date: Sun, 7 Aug 2011 13:50:50 +0000 (+0100)
Subject: doxygen: add some missing docstrings.
X-Git-Tag: branchpoint-5.1~27
X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/commitdiff_plain/598b07b7de7559ddcaed4063912f68bf951d6701?ds=sidebyside

doxygen: add some missing docstrings.
---

diff --git a/cgi/options.c b/cgi/options.c
index fca5801..5517c76 100644
--- a/cgi/options.c
+++ b/cgi/options.c
@@ -58,9 +58,15 @@ static void option__columns(int nvec,
   hash_add(columns, vec[0], &c, HASH_INSERT_OR_REPLACE);
 }
 
+/** @brief Definition of an option command */
 static struct option {
+  /** @brief Command name */
   const char *name;
-  int minargs, maxargs;
+  /** @brief Minimum number of arguments */
+  int minargs;
+  /** @brief Maximum number of arguments */
+  int maxargs;
+  /** @brief Command handler */
   void (*handler)(int nvec, char **vec);
 } options[] = {
   { "columns", 1, INT_MAX, option__columns },
diff --git a/clients/disorder.c b/clients/disorder.c
index 53fce74..6d0a29d 100644
--- a/clients/disorder.c
+++ b/clients/disorder.c
@@ -672,12 +672,28 @@ static void cf_playlist_set(char **argv) {
     exit(EXIT_FAILURE);
 }
 
-static const struct command {
+/** @brief Command-line client's definition of a command */
+static const struct client_command {
+  /** @brief Command name */
   const char *name;
-  int min, max;
+
+  /** @brief Minimum number of argument */
+  int min;
+
+  /** @brief Maximum number of argument */
+  int max;
+
+  /** @brief Pointer to function implementing command */
   void (*fn)(char **);
+
+  /** @brief Function to recognize a valid argument, or NULL */
   int (*isarg)(const char *);
-  const char *argstr, *desc;
+
+  /** @brief Summary of arguments */
+  const char *argstr;
+
+  /** @brief Description */
+  const char *desc;
 } commands[] = {
   { "adduser",        2, 3, cf_adduser, isarg_rights, "USERNAME PASSWORD [RIGHTS]",
                       "Create a new user" },
diff --git a/clients/disorderfm.c b/clients/disorderfm.c
index ed31dd0..14092da 100644
--- a/clients/disorderfm.c
+++ b/clients/disorderfm.c
@@ -73,7 +73,7 @@ static const char *nativeencoding;
 /* Count of errors */
 static long errors;
 
-/* Included/excluded filename patterns */
+/** @brief Included/excluded filename pattern */
 static struct pattern {
   struct pattern *next;
   const char *pattern;
diff --git a/disobedience/misc.c b/disobedience/misc.c
index a1fdf4d..3878824 100644
--- a/disobedience/misc.c
+++ b/disobedience/misc.c
@@ -22,8 +22,11 @@
 #include "disobedience.h"
 #include "table.h"
 
+/** @brief Embedded image */
 struct image {
+  /** @brief Image name */
   const char *name;
+  /** @brief Image data in GDK pixbuf inline format */
   const guint8 *data;
 };
 
diff --git a/lib/configuration.h b/lib/configuration.h
index 6e3a9a9..63c82c8 100644
--- a/lib/configuration.h
+++ b/lib/configuration.h
@@ -68,6 +68,7 @@ struct collectionlist {
   struct collection *s;
 };
 
+/** @brief A track name part */
 struct namepart {
   char *part;				/* part */
   pcre *re;				/* compiled regexp */
@@ -77,11 +78,13 @@ struct namepart {
   unsigned reflags;			/* regexp flags */
 };
 
+/** @brief A list of track name parts */
 struct namepartlist {
   int n;
   struct namepart *s;
 };
 
+/** @brief A track name transform */
 struct transform {
   char *type;				/* track or dir */
   char *context;			/* sort or choose */
@@ -90,6 +93,7 @@ struct transform {
   unsigned flags;			/* regexp flags */
 };
 
+/** @brief A list of track name transforms */
 struct transformlist {
   int n;
   struct transform *t;
diff --git a/lib/eventdist.c b/lib/eventdist.c
index 37893b6..e0fb0fa 100644
--- a/lib/eventdist.c
+++ b/lib/eventdist.c
@@ -24,10 +24,22 @@
 #include "eventdist.h"
 #include "hash.h"
 
+/** @brief Event data
+ *
+ * @c event_data structures form linked lists; one list per event and one node
+ * per handler.
+ */
 struct event_data {
+  /** @brief Next handler */
   struct event_data *next;
+
+  /** @brief Name of event */
   const char *event;
+
+  /** @brief Handler callback */
   event_handler *callback;
+
+  /** @brief Passed to @ref callback */
   void *callbackdata;
 };
 
diff --git a/lib/eventlog.c b/lib/eventlog.c
index a56884b..9ca2292 100644
--- a/lib/eventlog.c
+++ b/lib/eventlog.c
@@ -28,6 +28,7 @@
 #include "eventlog.h"
 #include "split.h"
 
+/** @brief Linked list of event logs */
 static struct eventlog_output *outputs;
 
 void eventlog_add(struct eventlog_output *lo) {
@@ -44,6 +45,11 @@ void eventlog_remove(struct eventlog_output *lo) {
     *pp = lo->next;
 }
 
+/** @brief Write to the event log
+ * @param keyword Distinguishing keyword for event
+ * @param raw Unformatted data
+ * @param ap Extra data, terminated by (char *)0
+ */
 static void veventlog(const char *keyword, const char *raw, va_list ap) {
   struct eventlog_output *p, *pnext;
   struct dynstr d;
diff --git a/lib/eventlog.h b/lib/eventlog.h
index 87eea51..e29fcfc 100644
--- a/lib/eventlog.h
+++ b/lib/eventlog.h
@@ -21,23 +21,45 @@
 #ifndef EVENTLOG_H
 #define EVENTLOG_H
 
-/* definition of an event log output.  The caller must allocate these
- * (since log.c isn't allowed to perform memory allocation). */
+/** @brief An output for the event log
+ *
+ * The caller must allocate these (since log.c isn't allowed to perform memory
+ * allocation).  They form a linked list, using eventlog_add() and
+ * eventlog_remove().
+ */
 struct eventlog_output {
+  /** @brief Next output */
   struct eventlog_output *next;
+
+  /** @brief Handler for this output */
   void (*fn)(const char *msg, void *user);
+
+  /** @brief Passed to @ref fn */
   void *user;
 };
 
+/** @brief Add an event log output
+ * @param lo Pointer to output to add
+ */
 void eventlog_add(struct eventlog_output *lo);
-/* add a log output */
 
+/** @brief Remove an event log output
+ * @param lo Pointer to output to remove
+ */
 void eventlog_remove(struct eventlog_output *lo);
-/* remove a log output */
 
+/** @brief Send a message to the event log
+ * @param keyword Distinguishing keyword for event
+ * @param ... Extra data, terminated by (char *)0
+ */
 void eventlog(const char *keyword, ...);
+
+/** @brief Send a message to the event log
+ * @param keyword Distinguishing keyword for event
+ * @param raw Unformatted data
+ * @param ... Extra data, terminated by (char *)0
+ */
 void eventlog_raw(const char *keyword, const char *raw, ...);
-/* send a message to the event log */
 
 #endif /* EVENTLOG_H */
 
diff --git a/lib/hash.c b/lib/hash.c
index 573b50a..9dc3469 100644
--- a/lib/hash.c
+++ b/lib/hash.c
@@ -25,6 +25,7 @@
 #include "log.h"
 #include "kvp.h"
 
+/** @brief One entry in a hash table */
 struct entry {
   struct entry *next;                   /* next entry same key */
   size_t h;                             /* hash of KEY */
@@ -32,6 +33,7 @@ struct entry {
   void *value;                          /* value of this entry */
 };
 
+/** @brief A hash table */
 struct hash {
   size_t nslots;                        /* number of slots */
   size_t nitems;                        /* total number of entries */
diff --git a/lib/queue.c b/lib/queue.c
index 0f39b23..e39ca5f 100644
--- a/lib/queue.c
+++ b/lib/queue.c
@@ -194,13 +194,23 @@ static const char *marshall_origin(const struct queue_entry *q, size_t offset) {
 
 #define F(n, h) { #n, offsetof(struct queue_entry, n), marshall_##h, unmarshall_##h, free_##h }
 
-static const struct field {
+/** @brief A field in a @ref queue_entry */
+static const struct queue_field {
+  /** @brief Field name */
   const char *name;
+
+  /** @brief Offset of value in @ref queue_entry structure */
   size_t offset;
+
+  /** @brief Marshaling function */
   const char *(*marshall)(const struct queue_entry *q, size_t offset);
+
+  /** @brief Unmarshaling function */
   int (*unmarshall)(char *data, struct queue_entry *q, size_t offset,
 		    void (*error_handler)(const char *, void *),
 		    void *u);
+
+  /** @brief Destructor */
   void (*free)(struct queue_entry *q, size_t offset);
 } fields[] = {
   /* Keep this table sorted. */
diff --git a/lib/snprintf.c b/lib/snprintf.c
index e62e3c9..f272dc7 100644
--- a/lib/snprintf.c
+++ b/lib/snprintf.c
@@ -30,10 +30,21 @@
 #include "printf.h"
 #include "sink.h"
 
+/** @brief A @ref sink that stores to a fixed buffer
+ *
+ * If there is too much output, it is truncated.
+ */
 struct fixedstr_sink {
+  /** @brief Base */
   struct sink s;
+
+  /** @brief Output buffer */
   char *buffer;
+
+  /** @brief Bytes written so far */
   int nbytes;
+
+  /** @brief Size of buffer */
   size_t size;
 };
 
diff --git a/lib/strptime.c b/lib/strptime.c
index 83d010d..91d57d5 100644
--- a/lib/strptime.c
+++ b/lib/strptime.c
@@ -37,8 +37,12 @@
 #include <langinfo.h>
 #include "strptime.h"
 
+/** @brief Lookup table entry for locale-specific strings */
 struct locale_item_match {
+  /** @brief Locale key to try */
   nl_item key;
+
+  /** @brief Value to return if value of @ref key matches subject string */
   int value;
 };
 
diff --git a/plugins/tracklength-flac.c b/plugins/tracklength-flac.c
index a838966..31a7e9d 100644
--- a/plugins/tracklength-flac.c
+++ b/plugins/tracklength-flac.c
@@ -23,8 +23,12 @@
 
 /* libFLAC's "simplified" interface is rather heavyweight... */
 
+/** @brief State used when computing FLAC file length */
 struct flac_state {
+  /** @brief Duration or -1 */
   long duration;
+
+  /** @brief File being analyzed */
   const char *path;
 };
 
diff --git a/server/server.c b/server/server.c
index 29efbbe..1169e2f 100644
--- a/server/server.c
+++ b/server/server.c
@@ -1845,7 +1845,8 @@ static int c_playlist_unlock(struct conn *c,
   return 1;
 }
 
-static const struct command {
+/** @brief Server's definition of a command */
+static const struct server_command {
   /** @brief Command name */
   const char *name;