From 2c6ee627861951ee978793cca4fd14638c34976f Mon Sep 17 00:00:00 2001 Message-Id: <2c6ee627861951ee978793cca4fd14638c34976f.1715305690.git.mdw@distorted.org.uk> From: Mark Wooding Date: Sun, 7 Aug 2011 16:49:06 +0100 Subject: [PATCH] doxygen: add some missing docstrings. Organization: Straylight/Edgeware From: Richard Kettlewell --- cgi/options.c | 4 ++++ clients/disorder.c | 6 ++++++ disobedience/properties.c | 17 ++++++++++------- disobedience/queue-generic.c | 4 ++++ lib/resample.h | 37 ++++++++++++++++++++++++++++++++++-- lib/signame.c | 4 ++++ lib/trackdb.c | 1 + python/disorder.py.in | 1 + server/disorderd.c | 4 ++++ server/plugin.c | 6 ++++++ server/rescan.c | 21 +++++++++++++++++++- 11 files changed, 95 insertions(+), 10 deletions(-) diff --git a/cgi/options.c b/cgi/options.c index 2403833..521ce35 100644 --- 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 --- 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 --- 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 --- 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 --- 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 --- 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 --- 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 --- 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 --- 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 --- 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 --- 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; }; -- [mdw]