Add more documentation.

[paraslash.git] / afs.c

diff --git a/afs.c b/afs.c
index de713fa7769502d1ee8d6929d34f1306f7adf1c7..a3b8d8839b633e822c17d8307e303a58806e0c12 100644 (file)
--- a/afs.c
+++ b/afs.c
@@ -123,7 +123,7 @@ struct callback_result {
 };
 
 /**
- * Ask the parent process to call a given function.
+ * Ask the afs process to call a given function.
  *
  * \param f The function to be called.
  * \param query Pointer to arbitrary data for the callback.
@@ -307,6 +307,14 @@ static int action_if_pattern_matches(struct osl_row *row, void *data)
        return 1;
 }
 
+/**
+ * Execute the given function for each matching row.
+ *
+ * \param pmd Describes what to match and how.
+ *
+ * \return The return value of the underlying call to osl_rbtree_loop()
+ * or osl_rbtree_loop_reverse().
+ */
 int for_each_matching_row(struct pattern_match_data *pmd)
 {
        if (pmd->pm_flags & PM_REVERSE_LOOP)
@@ -737,10 +745,11 @@ static void execute_afs_command(int fd, uint32_t expected_cookie)
                        query_shmid);
                return;
        }
-       /* Ignore return value: Errors might be ok here. */
+       /* Ignore return value: Errors might be OK here. */
        call_callback(fd, query_shmid);
 }
 
+/** Shutdown connection if query has not arrived until this many seconds. */
 #define AFS_CLIENT_TIMEOUT 3
 
 static void command_post_select(struct sched *s, struct task *t)
@@ -753,7 +762,7 @@ static void command_post_select(struct sched *s, struct task *t)
        list_for_each_entry_safe(client, tmp, &afs_client_list, node) {
                if (FD_ISSET(client->fd, &s->rfds))
                        execute_afs_command(client->fd, ct->cookie);
-               else { /* prevent bogus connection flodding */
+               else { /* prevent bogus connection flooding */
                        struct timeval diff;
                        tv_diff(now, &client->connect_time, &diff);
                        if (diff.tv_sec < AFS_CLIENT_TIMEOUT)
@@ -793,13 +802,19 @@ static void register_command_task(uint32_t cookie)
        register_task(&ct->task);
 }
 
-void register_tasks(uint32_t cookie)
+static void register_tasks(uint32_t cookie)
 {
        register_signal_task();
        register_command_task(cookie);
 }
 
-__noreturn int afs_init(uint32_t cookie, int socket_fd)
+/**
+ * Initialize the audio file selector process.
+ *
+ * \param cookie The value used for "authentication".
+ * \param socket_fd File descriptor used for communication with the server.
+ */
+__noreturn void afs_init(uint32_t cookie, int socket_fd)
 {
        enum play_mode current_play_mode;
        struct sched s;
@@ -881,9 +896,17 @@ int com_init(int fd, int argc, char * const * const argv)
        return send_va_buffer(fd, "successfully created afs table(s)\n");
 }
 
+/**
+ * Flags for the check command.
+ *
+ * \sa com_check().
+ */
 enum com_check_flags {
+       /** Check the audio file table. */
        CHECK_AFT = 1,
+       /** Check the mood table. */
        CHECK_MOODS = 2,
+       /** Check the playlist table. */
        CHECK_PLAYLISTS = 4
 };