doxygen: add some missing docstrings.

diff --git a/cgi/options.c b/cgi/options.c
index fca5801caa3024d2acb99df61b095ade57afcaa7..5517c76b05077d5914e4110f1080fd3f3738f3a2 100644 (file)
--- 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);
 }
 
   hash_add(columns, vec[0], &c, HASH_INSERT_OR_REPLACE);
 }
 

+/** @brief Definition of an option command */

 static struct option {
 static struct option {

+  /** @brief Command name */

   const char *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 },
   void (*handler)(int nvec, char **vec);
 } options[] = {
   { "columns", 1, INT_MAX, option__columns },

diff --git a/clients/disorder.c b/clients/disorder.c
index 53fce74c778c0b5aaf6c24d634f291b5f24ed731..6d0a29d971b7290f96ae1887662f10a0ff6b75b7 100644 (file)
--- a/clients/disorder.c
+++ b/clients/disorder.c
@@ -672,12 +672,28 @@ static void cf_playlist_set(char **argv) {
     exit(EXIT_FAILURE);
 }
 
     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;
   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 **);
   void (*fn)(char **);

+
+  /** @brief Function to recognize a valid argument, or NULL */

   int (*isarg)(const char *);
   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" },
 } 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 ed31dd073025ebc66384be48f7f938b00331fd91..14092dad74b1c9aa90d0586a6f237145d4ddb0d1 100644 (file)
--- a/clients/disorderfm.c
+++ b/clients/disorderfm.c
@@ -73,7 +73,7 @@ static const char *nativeencoding;
 /* Count of errors */
 static long errors;
 
 /* Count of errors */
 static long errors;
 

-/* Included/excluded filename patterns */
+/** @brief Included/excluded filename pattern */

 static struct pattern {
   struct pattern *next;
   const char *pattern;
 static struct pattern {
   struct pattern *next;
   const char *pattern;

diff --git a/disobedience/misc.c b/disobedience/misc.c
index a1fdf4d5f7b72d9ec2bdb96097d366f62503f788..38788241cd7e875552b679cc5baf3c3c64538900 100644 (file)
--- a/disobedience/misc.c
+++ b/disobedience/misc.c
@@ -22,8 +22,11 @@
 #include "disobedience.h"
 #include "table.h"
 
 #include "disobedience.h"
 #include "table.h"
 

+/** @brief Embedded image */

 struct image {
 struct image {

+  /** @brief Image name */

   const char *name;
   const char *name;

+  /** @brief Image data in GDK pixbuf inline format */

   const guint8 *data;
 };
 
   const guint8 *data;
 };
 

diff --git a/lib/configuration.h b/lib/configuration.h
index 6e3a9a946b8a04a2024e589d3a0c98fda9bd9b71..63c82c8db368d2c8358b0a072aa59833e4df871d 100644 (file)
--- a/lib/configuration.h
+++ b/lib/configuration.h
@@ -68,6 +68,7 @@ struct collectionlist {
   struct collection *s;
 };
 
   struct collection *s;
 };
 

+/** @brief A track name part */

 struct namepart {
   char *part;                          /* part */
   pcre *re;                            /* compiled regexp */
 struct namepart {
   char *part;                          /* part */
   pcre *re;                            /* compiled regexp */


@@ -77,11 +78,13 @@ struct namepart {
   unsigned reflags;                    /* regexp flags */
 };
 
   unsigned reflags;                    /* regexp flags */
 };
 

+/** @brief A list of track name parts */

 struct namepartlist {
   int n;
   struct namepart *s;
 };
 
 struct namepartlist {
   int n;
   struct namepart *s;
 };
 

+/** @brief A track name transform */

 struct transform {
   char *type;                          /* track or dir */
   char *context;                       /* sort or choose */
 struct transform {
   char *type;                          /* track or dir */
   char *context;                       /* sort or choose */


@@ -90,6 +93,7 @@ struct transform {
   unsigned flags;                      /* regexp flags */
 };
 
   unsigned flags;                      /* regexp flags */
 };
 

+/** @brief A list of track name transforms */

 struct transformlist {
   int n;
   struct transform *t;
 struct transformlist {
   int n;
   struct transform *t;

diff --git a/lib/eventdist.c b/lib/eventdist.c
index 37893b6ef1cc30fd5dfdf6d60441ea00002b5e0d..e0fb0fa9b4256aeb8d4aecf835b85395a73e9732 100644 (file)
--- a/lib/eventdist.c
+++ b/lib/eventdist.c
@@ -24,10 +24,22 @@
 #include "eventdist.h"
 #include "hash.h"
 
 #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 {
 struct event_data {

+  /** @brief Next handler */

   struct event_data *next;
   struct event_data *next;

+
+  /** @brief Name of event */

   const char *event;
   const char *event;

+
+  /** @brief Handler callback */

   event_handler *callback;
   event_handler *callback;

+
+  /** @brief Passed to @ref callback */

   void *callbackdata;
 };
 
   void *callbackdata;
 };
 

diff --git a/lib/eventlog.c b/lib/eventlog.c
index a56884b33d50b3874f3f537eca2b5daedbfb3b5a..9ca22926719870db7d7622fdc7c0de64a1914473 100644 (file)
--- a/lib/eventlog.c
+++ b/lib/eventlog.c
@@ -28,6 +28,7 @@
 #include "eventlog.h"
 #include "split.h"
 
 #include "eventlog.h"
 #include "split.h"
 

+/** @brief Linked list of event logs */

 static struct eventlog_output *outputs;
 
 void eventlog_add(struct eventlog_output *lo) {
 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;
 }
 
     *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;
 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 87eea513495368e51c3ee588b54477f00cf40923..e29fcfc7db300c13fb9d4c1c46f4a3c0b55dd1b9 100644 (file)
--- a/lib/eventlog.h
+++ b/lib/eventlog.h
@@ -21,23 +21,45 @@
 #ifndef EVENTLOG_H
 #define EVENTLOG_H
 
 #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 {
 struct eventlog_output {

+  /** @brief Next output */

   struct eventlog_output *next;
   struct eventlog_output *next;

+
+  /** @brief Handler for this output */

   void (*fn)(const char *msg, void *user);
   void (*fn)(const char *msg, void *user);

+
+  /** @brief Passed to @ref fn */

   void *user;
 };
 
   void *user;
 };
 

+/** @brief Add an event log output
+ * @param lo Pointer to output to add
+ */

 void eventlog_add(struct eventlog_output *lo);
 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);
 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, ...);
 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, ...);
 void eventlog_raw(const char *keyword, const char *raw, ...);

-/* send a message to the event log */

 
 #endif /* EVENTLOG_H */
 
 
 #endif /* EVENTLOG_H */
 

diff --git a/lib/hash.c b/lib/hash.c
index 573b50aa91b9a235294a0e59338ccb474f8a0faa..9dc346950680a2d83eb7d439ac3a0d7419437e5e 100644 (file)
--- a/lib/hash.c
+++ b/lib/hash.c
@@ -25,6 +25,7 @@
 #include "log.h"
 #include "kvp.h"
 
 #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 */
 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 */
 };
 
   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 */
 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 0f39b23800fa5c31991fda8e7b21fb9ecdbc4842..e39ca5f3f92fb36c28429bdb0fb74335833d9036 100644 (file)
--- 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 }
 
 
 #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;
   const char *name;

+
+  /** @brief Offset of value in @ref queue_entry structure */

   size_t offset;
   size_t offset;

+
+  /** @brief Marshaling function */

   const char *(*marshall)(const struct queue_entry *q, size_t offset);
   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);
   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. */
   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 e62e3c9434a80c0698d5ab69141710cff950f812..f272dc77fb96352c82cd845b56b217ead0c23993 100644 (file)
--- a/lib/snprintf.c
+++ b/lib/snprintf.c
@@ -30,10 +30,21 @@
 #include "printf.h"
 #include "sink.h"
 
 #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 {
 struct fixedstr_sink {

+  /** @brief Base */

   struct sink s;
   struct sink s;

+
+  /** @brief Output buffer */

   char *buffer;
   char *buffer;

+
+  /** @brief Bytes written so far */

   int nbytes;
   int nbytes;

+
+  /** @brief Size of buffer */

   size_t size;
 };
 
   size_t size;
 };
 

diff --git a/lib/strptime.c b/lib/strptime.c
index 83d010da60d1b1eebe587156f93aae123854c133..91d57d55451ae2212bd785004cc581226e35c250 100644 (file)
--- a/lib/strptime.c
+++ b/lib/strptime.c
@@ -37,8 +37,12 @@
 #include <langinfo.h>
 #include "strptime.h"
 
 #include <langinfo.h>
 #include "strptime.h"
 

+/** @brief Lookup table entry for locale-specific strings */

 struct locale_item_match {
 struct locale_item_match {

+  /** @brief Locale key to try */

   nl_item key;
   nl_item key;

+
+  /** @brief Value to return if value of @ref key matches subject string */

   int value;
 };
 
   int value;
 };
 

diff --git a/plugins/tracklength-flac.c b/plugins/tracklength-flac.c
index a838966bc0e28885477594af1c570ac8bf7c7b98..31a7e9d0774465564c5396e33fcd71b23614fe71 100644 (file)
--- a/plugins/tracklength-flac.c
+++ b/plugins/tracklength-flac.c
@@ -23,8 +23,12 @@
 
 /* libFLAC's "simplified" interface is rather heavyweight... */
 
 
 /* libFLAC's "simplified" interface is rather heavyweight... */
 

+/** @brief State used when computing FLAC file length */

 struct flac_state {
 struct flac_state {

+  /** @brief Duration or -1 */

   long duration;
   long duration;

+
+  /** @brief File being analyzed */

   const char *path;
 };
 
   const char *path;
 };
 

diff --git a/server/server.c b/server/server.c
index 29efbbe75e28bad5231d0eac34b7c1401a3a9b38..1169e2fa09f6f7756b6c33e19e2c6bc6739b160c 100644 (file)
--- a/server/server.c
+++ b/server/server.c
@@ -1845,7 +1845,8 @@ static int c_playlist_unlock(struct conn *c,
   return 1;
 }
 
   return 1;
 }
 

-static const struct command {
+/** @brief Server's definition of a command */
+static const struct server_command {

   /** @brief Command name */
   const char *name;
 
   /** @brief Command name */
   const char *name;