Improve doc comments.

diff --git a/lib/trackdb-playlists.c b/lib/trackdb-playlists.c
index bef7107bf9c784976c78fcfaa80b876926616c94..f9f8252068e099ae601447739b29f72ef7cad24e 100644 (file)
--- a/lib/trackdb-playlists.c
+++ b/lib/trackdb-playlists.c
@@ -230,6 +230,7 @@ static int trackdb_playlist_get_tid(const char *name,
 
 /** @brief Modify or create a playlist
  * @param name Playlist name
 
 /** @brief Modify or create a playlist
  * @param name Playlist name

+ * @param who User modifying playlist

  * @param tracks List of tracks to set, or NULL to leave alone
  * @param ntracks Length of @p tracks
  * @param share Sharing status, or NULL to leave alone
  * @param tracks List of tracks to set, or NULL to leave alone
  * @param ntracks Length of @p tracks
  * @param share Sharing status, or NULL to leave alone

diff --git a/lib/trackdb.c b/lib/trackdb.c
index 042bbef3170ff7c659b8a109af445de0712cb262..572f979cce5b72a59ec0db5351c619c2325f17be 100644 (file)
--- a/lib/trackdb.c
+++ b/lib/trackdb.c
@@ -82,8 +82,14 @@ int trackdb_existing_database;
 
 /* setup and teardown ********************************************************/
 
 
 /* setup and teardown ********************************************************/
 

-static const char *home;                /* home had better not change */
-DB_ENV *trackdb_env;                   /* db environment */
+/** @brief Database home directory
+ *
+ * All database files live below here.  It had better never change.
+ */
+static const char *home;
+
+/** @brief Database environment */
+DB_ENV *trackdb_env;

 
 /** @brief The tracks database
  * - Keys are UTF-8(NFC(unicode(path name)))
 
 /** @brief The tracks database
  * - Keys are UTF-8(NFC(unicode(path name)))


@@ -164,23 +170,48 @@ DB *trackdb_usersdb;
  */
 DB *trackdb_playlistsdb;
 
  */
 DB *trackdb_playlistsdb;
 

-static pid_t db_deadlock_pid = -1;      /* deadlock manager PID */
-static pid_t rescan_pid = -1;           /* rescanner PID */
-static int initialized, opened;         /* state */
+/** @brief Deadlock manager PID */
+static pid_t db_deadlock_pid = -1;
+
+/** @brief Rescanner PID */
+static pid_t rescan_pid = -1;
+
+/** @brief Set when the database environment exists */
+static int initialized;
+
+/** @brief Set when databases are open */
+static int opened;

 
 /** @brief Current stats subprocess PIDs */
 static hash *stats_pids;
 
 
 /** @brief Current stats subprocess PIDs */
 static hash *stats_pids;
 

+/** @brief PID of current random track chooser (disorder-choose) */

 static pid_t choose_pid = -1;
 static pid_t choose_pid = -1;

+
+/** @brief Our end of pipe from disorder-choose */

 static int choose_fd;
 static int choose_fd;

+
+/** @brief Callback to supply random track to */

 static random_callback *choose_callback;
 static random_callback *choose_callback;

+
+/** @brief Accumulator for output from disorder-choose */

 static struct dynstr choose_output;
 static struct dynstr choose_output;

+
+/** @brief Current completion status of disorder-choose
+ * A bitmap of @ref CHOOSE_READING and @ref CHOOSE_RUNNING.
+ */

 static unsigned choose_complete;
 static unsigned choose_complete;

+
+/* @brief Exit status from disorder-choose */

 static int choose_status;
 static int choose_status;

+
+/** @brief disorder-choose process is running */

 #define CHOOSE_RUNNING 1
 #define CHOOSE_RUNNING 1

+
+/** @brief disorder-choose pipe is still open */

 #define CHOOSE_READING 2
 
 #define CHOOSE_READING 2
 

-/* comparison function for keys */
+/** @brief Comparison function for filename-based keys */

 static int compare(DB attribute((unused)) *db_,
                   const DBT *a, const DBT *b) {
   return compare_path_raw(a->data, a->size, b->data, b->size);
 static int compare(DB attribute((unused)) *db_,
                   const DBT *a, const DBT *b) {
   return compare_path_raw(a->data, a->size, b->data, b->size);


@@ -274,7 +305,7 @@ void trackdb_init(int flags) {
   D(("initialized database environment"));
 }
 
   D(("initialized database environment"));
 }
 

-/* called when deadlock manager terminates */
+/** @brief Called when deadlock manager terminates */

 static int reap_db_deadlock(ev_source attribute((unused)) *ev,
                             pid_t attribute((unused)) pid,
                             int status,
 static int reap_db_deadlock(ev_source attribute((unused)) *ev,
                             pid_t attribute((unused)) pid,
                             int status,


@@ -289,6 +320,18 @@ static int reap_db_deadlock(ev_source attribute((unused)) *ev,
   return 0;
 }
 
   return 0;
 }
 

+/** @brief Start a subprogram
+ * @param ev Event loop
+ * @param outputfd File descriptor to redirect @c stdout to, or -1
+ * @param prog Program name
+ * @param ... Arguments
+ * @return PID
+ *
+ * Starts a subprocess.  Adds the following arguments:
+ * - @c --config to ensure the right config file is used
+ * - @c --debug or @c --no-debug to match debug settings
+ * - @c --syslog or @c --no-syslog to match log settings
+ */

 static pid_t subprogram(ev_source *ev, int outputfd, const char *prog,
                         ...) {
   pid_t pid;
 static pid_t subprogram(ev_source *ev, int outputfd, const char *prog,
                         ...) {
   pid_t pid;


@@ -328,7 +371,11 @@ static pid_t subprogram(ev_source *ev, int outputfd, const char *prog,
   return pid;
 }
 
   return pid;
 }
 

-/* start deadlock manager */
+/** @brief Start deadlock manager
+ * @param ev Event loop
+ *
+ * Called from the main server (only).
+ */

 void trackdb_master(ev_source *ev) {
   assert(db_deadlock_pid == -1);
   db_deadlock_pid = subprogram(ev, -1, DEADLOCK, (char *)0);
 void trackdb_master(ev_source *ev) {
   assert(db_deadlock_pid == -1);
   db_deadlock_pid = subprogram(ev, -1, DEADLOCK, (char *)0);


@@ -336,6 +383,14 @@ void trackdb_master(ev_source *ev) {
   D(("started deadlock manager"));
 }
 
   D(("started deadlock manager"));
 }
 

+/** @brief Kill a subprocess and wait for it to terminate
+ * @param ev Event loop or NULL
+ * @param pid Process ID or -1
+ * @param what Description of subprocess
+ *
+ * Used during trackdb_deinit().  This function blocks so don't use it for
+ * normal teardown as that will hang the server.
+ */

 static void terminate_and_wait(ev_source *ev,
                                pid_t pid,
                                const char *what) {
 static void terminate_and_wait(ev_source *ev,
                                pid_t pid,
                                const char *what) {


@@ -352,7 +407,9 @@ static void terminate_and_wait(ev_source *ev,
     ev_child_cancel(ev, pid);
 }
 
     ev_child_cancel(ev, pid);
 }
 

-/* close environment */
+/** @brief Close database environment
+ * @param ev Event loop
+ */

 void trackdb_deinit(ev_source *ev) {
   int err;
 
 void trackdb_deinit(ev_source *ev) {
   int err;
 


@@ -384,7 +441,14 @@ void trackdb_deinit(ev_source *ev) {
   D(("deinitialized database environment"));
 }
 
   D(("deinitialized database environment"));
 }
 

-/* open a specific database */
+/** @brief Open a specific database
+ * @param path Relative path to database
+ * @param dbflags Database flags: DB_DUP, DB_DUPSORT, etc
+ * @param dbtype Database type: DB_HASH, DB_BTREE, etc
+ * @param openflags Open flags: DB_RDONLY, DB_CREATE, etc
+ * @param mode Permission mask: usually 0666
+ * @return Database handle
+ */

 static DB *open_db(const char *path,
                    u_int32_t dbflags,
                    DBTYPE dbtype,
 static DB *open_db(const char *path,
                    u_int32_t dbflags,
                    DBTYPE dbtype,


@@ -520,7 +584,7 @@ void trackdb_open(int flags) {
   D(("opened databases"));
 }
 
   D(("opened databases"));
 }
 

-/* close track databases */
+/** @brief Close track databases */

 void trackdb_close(void) {
   int err;
 
 void trackdb_close(void) {
   int err;
 


@@ -578,8 +642,14 @@ int trackdb_getdata(DB *db,
   }
 }
 
   }
 }
 

-/* encode and store a database entry.  Returns 0, DB_KEYEXIST or
- * DB_LOCK_DEADLOCK. */
+/** @brief Encode and store a database entry
+ * @param db Database
+ * @param track Track name
+ * @param k List of key/value pairs to store
+ * @param tid Owning transaction
+ * @param flags DB flags e.g. DB_NOOVERWRITE
+ * @return 0, DB_KEYEXIST or DB_LOCK_DEADLOCK
+ */

 int trackdb_putdata(DB *db,
                     const char *track,
                     const struct kvp *k,
 int trackdb_putdata(DB *db,
                     const char *track,
                     const struct kvp *k,

diff --git a/lib/uaudio-schedule.c b/lib/uaudio-schedule.c
index 361681bc6e2fcc3cf3e36cab1455938aaee56a2c..c42de57633cbe73af51f9ed79b60125a879022e7 100644 (file)
--- a/lib/uaudio-schedule.c
+++ b/lib/uaudio-schedule.c
@@ -140,7 +140,7 @@ uint32_t uaudio_schedule_sync(void) {
 }
 
 /** @brief Report how many samples we actually sent
 }
 
 /** @brief Report how many samples we actually sent

- * @param nsamples Number of samples sent
+ * @param nsamples_sent Number of samples sent

  */
 void uaudio_schedule_sent(size_t nsamples_sent) {
   timestamp += nsamples_sent;
  */
 void uaudio_schedule_sent(size_t nsamples_sent) {
   timestamp += nsamples_sent;

diff --git a/server/background.c b/server/background.c
index be5a3099916629af28a26ed23ef1dba4bfef4deb..4b8a49b28739a904668c9d58562d70b5ff23b864 100644 (file)
--- a/server/background.c
+++ b/server/background.c
@@ -21,7 +21,8 @@
 
 #include "disorder-server.h"
 
 
 #include "disorder-server.h"
 

-/** @brief Fork the player or decoder for @p q 
+/** @brief Fork the player or decoder for @p q
+ * @param ev Event loop

  * @param player Pointer to player information
  * @param q Track to play or decode
  * @param child Function to run inside fork
  * @param player Pointer to player information
  * @param q Track to play or decode
  * @param child Function to run inside fork

diff --git a/server/play.c b/server/play.c
index a0bd8093622f3647fa8ee004a329e8e3e5bb8daa..8fd6d4cf945fcb2107f9d04bd968f4906faa1098 100644 (file)
--- a/server/play.c
+++ b/server/play.c
@@ -267,7 +267,7 @@ static const struct stringlist *find_player(const struct queue_entry *q) {
  * @return @ref START_OK, @ref START_HARDFAIL or @ref START_SOFTFAIL
  *
  * This makes @p actually start playing.  It calls prepare() if necessary and
  * @return @ref START_OK, @ref START_HARDFAIL or @ref START_SOFTFAIL
  *
  * This makes @p actually start playing.  It calls prepare() if necessary and

- * either sends an @ref SM_START command or invokes the player itself in a
+ * either sends an @ref SM_PLAY command or invokes the player itself in a

  * subprocess.
  *
  * It's up to the caller to set @ref playing and @c playing->state (this might
  * subprocess.
  *
  * It's up to the caller to set @ref playing and @c playing->state (this might


@@ -658,8 +658,8 @@ void disable_random(const char *who) {
 /* Scratching --------------------------------------------------------------- */
 
 /** @brief Scratch a track
 /* Scratching --------------------------------------------------------------- */
 
 /** @brief Scratch a track

- * @param User responsible (or NULL)
- * @param Track ID (or NULL for current)
+ * @param who User responsible (or NULL)
+ * @param id Track ID (or NULL for current)

  */
 void scratch(const char *who, const char *id) {
   struct queue_entry *q;
  */
 void scratch(const char *who, const char *id) {
   struct queue_entry *q;

diff --git a/server/state.c b/server/state.c
index bb36ee44f2d13d99919986c1dc8cb59fda2cf99e..74f156698f38bf433d4d88e983cc5c60e6ae3d96 100644 (file)
--- a/server/state.c
+++ b/server/state.c
@@ -160,6 +160,7 @@ void reset_sockets(ev_source *ev) {
 }
 
 /** @brief Reconfigure the server
 }
 
 /** @brief Reconfigure the server

+ * @param ev Event loop

  * @param flags Flags
  * @return As config_read(); 0 on success, -1 if could not (re-)read config
  */
  * @param flags Flags
  * @return As config_read(); 0 on success, -1 if could not (re-)read config
  */