afs.c: Improve documentation.

Add an overview of the file and expand the description of
open_next_audio_file() and afs_init().

diff --git a/afs.c b/afs.c
index 445d5871097b79cdcd14170c2a1f59998354dc98..286f6df656a2ac615331b36289785a8f09ab833e 100644 (file)
--- a/afs.c
+++ b/afs.c
@@ -1,6 +1,14 @@
 /* Copyright (C) 2007 Andre Noll <maan@tuebingen.mpg.de>, see file COPYING. */
 
-/** \file afs.c Paraslash's audio file selector. */
+/**
+ * \file afs.c Paraslash's audio file selector (afs).
+ *
+ * The functions of this file execute either in afs or in command handler
+ * process context where the afs and the command handler processes are siblings
+ * of each other, i.e. direct descendants of the server process. Inter-process
+ * communication between command handlers, server and afs is performed through
+ * Unix domain sockets.
+ */
 
 #include <netinet/in.h>
 #include <sys/socket.h>
@@ -389,16 +397,14 @@ static int pass_afd(int fd, char *buf, size_t size)
        return 1;
 }
 
-/**
- * Pass the fd of the next audio file to the server process.
- *
- * This stores all information for streaming the "best" audio file in a shared
- * memory area. The id of that area and an open file descriptor for the next
- * audio file are passed to the server process.
+/*
+ * Send audio file information to the server process.
  *
- * \return Standard.
- *
- * \sa \ref open_and_update_audio_file().
+ * This first calls \ref open_and_update_audio_file() to obtain a file
+ * descriptor to the upcoming audio file and an id of a shared memory area
+ * containing information for the virtual streaming system. The file descriptor
+ * and the id are transferred to the server process through the Unix domain
+ * socket that was passed to \ref afs_init().
  */
 static int open_next_audio_file(void)
 {
@@ -917,11 +923,22 @@ static int afs_poll(struct pollfd *fds, nfds_t nfds, int timeout)
        mutex_unlock(mmd_mutex);
        return xpoll(fds, nfds, timeout);
 }
-
 /**
- * Initialize the audio file selector process.
+ * Initialize the audio file selector.
+ *
+ * \param socket_fd File descriptor for communication with the server process.
+ *
+ * Open all tables of the afs database, then schedule the signal task and the
+ * command task. The former reacts to signals by reloading the database or by
+ * terminating after closing all database tables. The command task dispatches
+ * commands from the server and from command handlers.
  *
- * \param socket_fd File descriptor used for communication with the server.
+ * The server connects the command task when the virtual streaming system
+ * needs to stream the next audio file. The command task opens the highest
+ * scoring admissible file and sends streaming information back to the
+ * server. The command task also accepts connections from command handlers,
+ * modifies or queries the afs database accordingly, and reports its findings
+ * back to the command handler.
  */
 __noreturn void afs_init(int socket_fd)
 {