From: Andre Noll <maan@systemlinux.org>
Date: Mon, 5 Feb 2007 23:13:22 +0000 (+0100)
Subject: audiod: Add missing documentation
X-Git-Tag: v0.2.15~30
X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=commitdiff_plain;h=101e1fd3252d838458a6ad4015f497818c54c897;hp=af50bfb04d6156d588e0a91884debbd917b304dc

audiod: Add missing documentation
---

diff --git a/audiod.c b/audiod.c
index ec9f34d5..9d0d0741 100644
--- a/audiod.c
+++ b/audiod.c
@@ -66,12 +66,28 @@ struct audio_format_info {
 	struct timeval restart_barrier;
 };
 
+/**
+ * para_audiod uses \p MAX_STREAM_SLOTS different slots, each of which may
+ * be associated with a receiver/filter/writer triple. This array holds all
+ * information on the status of these slots.
+ *
+ * \sa struct slot_info
+ * */
 struct slot_info slot[MAX_STREAM_SLOTS];
 
 
+/**
+ * the current mode of operation of which can be changed by the on/off/cycle
+ * commands. It is either, AUDIOD_OFF, AUDIOD_ON or AUDIOD_STANDBY.
+ */
 int audiod_status = AUDIOD_ON;
 
+/**
+ * the gengetopt args_info struct that holds information on all command line
+ * arguments
+ */
 struct audiod_args_info conf;
+
 static char *socket_name;
 static FILE *logfile;
 static struct audio_format_info afi[NUM_AUDIO_FORMATS];
@@ -79,6 +95,12 @@ static struct audio_format_info afi[NUM_AUDIO_FORMATS];
 static struct signal_task signal_task_struct, *sig_task = &signal_task_struct;
 
 static struct status_task status_task_struct;
+
+/**
+ * the task that calls the status command of para_server
+ *
+ * \sa struct status_task
+ */
 struct status_task *stat_task = &status_task_struct;
 static struct timeval initial_delay_barrier;
 
@@ -125,8 +147,11 @@ int get_audio_format_num(char *name)
 	return -E_UNSUPPORTED_AUDIO_FORMAT;
 }
 
-/*
- * log function. first argument is loglevel.
+/**
+ * the log function of para_audiod
+ *
+ * \param ll loglevel
+ * \param fmt the format string
  */
 void para_log(int ll, const char* fmt,...)
 {
@@ -960,6 +985,18 @@ static void close_stat_pipe(void)
 	}
 }
 
+/**
+ * close the connection to para_server and exit
+ *
+ * \param status the exit status which is passed to exit(3)
+ * \param msg the log message
+ *
+ * Log \a msg with loglevel \p EMERG, close the connection to para_server if
+ * open, and call \p exit(status). \a status should be either EXIT_SUCCESS or
+ * EXIT_FAILURE.
+ *
+ * \sa exit(3)
+ */
 void __noreturn clean_exit(int status, const char *msg)
 {
 	PARA_EMERG_LOG("%s\n", msg);
@@ -1073,6 +1110,16 @@ static void set_initial_status(void)
 		PARA_WARNING_LOG("%s", "invalid mode\n");
 }
 
+/**
+ * the main function of para_audiod
+ *
+ * \param argc usual argument count
+ * \param argv usual argument vector
+ *
+ * \return EXIT_SUCCESS or EXIT_FAILURE
+ *
+ * \sa para_audiod(1)
+ * */
 int main(int argc, char *argv[])
 {
 	char *cf;
diff --git a/audiod.h b/audiod.h
index 7628c1ea..ab75c584 100644
--- a/audiod.h
+++ b/audiod.h
@@ -37,8 +37,8 @@ extern const char *audio_formats[];
  * - off: disconnect from para_server
  * - on: receive status information from para_server and play the audio stream
  * - sb: only receive status information but not the audio stream
-*/
-enum {AUDIOD_OFF, AUDIOD_ON, AUDIOD_STANDBY};
+ */
+enum audiod_status_info {AUDIOD_OFF, AUDIOD_ON, AUDIOD_STANDBY};
 
 /** defines one command of para_audiod */
 struct audiod_command {
@@ -65,7 +65,7 @@ struct audiod_command {
  *
  * \sa receier_node, receiver, filter, filter_node, filter_chain, writer,
  * writer_node, writer_node_group.
-  */
+ */
 struct slot_info {
 	/** number of the audio format in this slot */
 	int format;
diff --git a/audiod_command.c b/audiod_command.c
index 3bb94ad6..349480ff 100644
--- a/audiod_command.c
+++ b/audiod_command.c
@@ -406,6 +406,21 @@ static int check_perms(uid_t uid)
 	return -E_UCRED_PERM;
 }
 
+/**
+ * handle arriving connections on the local socket
+ *
+ * \param accept_fd the fd to call accept() on
+ *
+ * This is called whenever para_audiod's main task detects an incoming
+ * connection by the readability of \a accept_fd. This function reads the
+ * command sent by the peer, checks the connecting user's permissions by using
+ * unix socket credentials (if supported by the OS) and calls the corresponding
+ * command handler if permissions are OK.
+ *
+ * \return positive on success, negative on errors
+ *
+ * \sa para_accept(), recv_cred_buffer()
+ * */
 int handle_connect(int accept_fd)
 {
 	int i, argc, ret, clifd = -1;