From c79899fe6a1e8eb3086749f46c599d9790d99921 Mon Sep 17 00:00:00 2001
From: Andre Noll <maan@systemlinux.org>
Date: Sat, 10 Feb 2007 19:54:26 +0100
Subject: [PATCH] add more missing documentation

---
 aac_afh.c        |  8 +++----
 aacdec.c         | 16 +++++++++++--
 alsa_write.c     |  2 +-
 audioc.c         | 17 +++++++++++++-
 audiod_command.c |  4 +++-
 client.c         | 15 ++++++++++--
 client.h         |  1 +
 crypt.c          | 14 +++++++++--
 dccp_send.c      |  5 ++--
 filter.h         | 14 ++++-------
 filter_chain.c   |  5 +++-
 http.h           |  4 ++++
 http_recv.c      |  8 +++----
 ipc.h            |  1 +
 list.h           | 11 +++++----
 mp3_afh.c        |  6 +++++
 mp3dec.c         |  4 +++-
 net.h            |  3 ++-
 ogg_afh.c        | 14 +++++++----
 osx_write.c      |  4 ++--
 recv.h           | 15 +++++++-----
 recv_common.c    | 17 +++++++++++++-
 sched.c          |  6 +++--
 server.c         | 28 ++++++++++++++++------
 server.h         |  2 +-
 signal.h         |  2 +-
 stat.c           | 10 ++++++--
 user_list.c      |  8 +++++++
 vss.c            | 10 ++++++++
 vss.h            |  7 +++++-
 write.c          |  4 ++++
 write.h          |  2 +-
 write_common.c   | 60 +++++++++++++++++++++++++++++++++++++++++++++++-
 write_common.h   |  5 ++--
 34 files changed, 265 insertions(+), 67 deletions(-)

diff --git a/aac_afh.c b/aac_afh.c
index a2347065..d5ec442b 100644
--- a/aac_afh.c
+++ b/aac_afh.c
@@ -31,19 +31,19 @@
 #include "aac.h"
 #include "fd.h"
 
-/* must be big enough to hold header */
+/** size of the input buffer, must be big enough to hold header */
 #define DEFAULT_INBUF_SIZE 65536
 
 static FILE *infile;
 static int inbuf_size;
 static unsigned char *inbuf;
 static size_t inbuf_len;
-struct audio_format_handler *af;
+static struct audio_format_handler *af;
 static size_t num_chunks;
 static size_t entry;
 
 static size_t *chunk_table;
-NeAACDecHandle handle;
+static NeAACDecHandle handle;
 
 static void aac_close_audio_file(void)
 {
@@ -116,7 +116,7 @@ static int read_chunk_table(size_t skip)
 	return 1;
 }
 
-long unsigned aac_set_chunk_tv(mp4AudioSpecificConfig *mp4ASC)
+static long unsigned aac_set_chunk_tv(mp4AudioSpecificConfig *mp4ASC)
 {
 	float tmp = mp4ASC->sbr_present_flag == 1? 2047 : 1023,
 		ms = 1000.0 * num_chunks * tmp / mp4ASC->samplingFrequency;
diff --git a/aacdec.c b/aacdec.c
index edbe2637..9ed12012 100644
--- a/aacdec.c
+++ b/aacdec.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2006 Andre Noll <maan@systemlinux.org>
+ * Copyright (C) 2006-2007 Andre Noll <maan@systemlinux.org>
  *
  *     This program is free software; you can redistribute it and/or modify
  *     it under the terms of the GNU General Public License as published by
@@ -34,6 +34,7 @@
 /** the output buffer size */
 #define AAC_OUTBUF_SIZE (32 * 1024)
 
+/** give up decoding after that many errors */
 #define MAX_ERRORS 20
 
 /**
@@ -42,13 +43,22 @@
  * \sa filter, filter_node
  */
 struct private_aacdec_data {
+	/** the return value of aac_open */
 	NeAACDecHandle handle;
+	/** info about the currently decoded frame */
 	NeAACDecFrameInfo frame_info;
-
+	/** whether this instance of the aac decoder is already initialized */
 	int initialized;
+	/**
+	 * return value of aac_find_esds(). Used to call the right aacdec
+	 * init function
+	 */
 	int decoder_length;
+	/** number of times the decoder returned an error */
 	unsigned error_count;
+	/** number of bytes already consumed from the imput stream */
 	size_t consumed_total;
+	/** return value of aac_find_entry_point */
 	size_t entry;
 };
 
@@ -179,6 +189,8 @@ static void aacdec_close(struct filter_node *fn)
 /**
  * the init function of the aacdec filter
  *
+ * \param f pointer to the filter struct to initialize
+ *
  * \sa filter::init
  */
 void aacdec_init(struct filter *f)
diff --git a/alsa_write.c b/alsa_write.c
index 8bac583a..526cffc1 100644
--- a/alsa_write.c
+++ b/alsa_write.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2005-2006 Andre Noll <maan@systemlinux.org>
+ * Copyright (C) 2005-2007 Andre Noll <maan@systemlinux.org>
  *
  *     This program is free software; you can redistribute it and/or modify
  *     it under the terms of the GNU General Public License as published by
diff --git a/audioc.c b/audioc.c
index 216afa2f..3cc5b0bd 100644
--- a/audioc.c
+++ b/audioc.c
@@ -27,8 +27,8 @@
 
 INIT_AUDIOC_ERRLISTS;
 
+/** the gengetopt structure containing command line args */
 struct audioc_args_info conf;
-char *tmpfifo;
 
 INIT_STDERR_LOGGING(conf.loglevel_arg);
 
@@ -59,6 +59,21 @@ static char *configfile_exists(void)
 	return NULL;
 }
 
+/**
+ * the client program to connect to para_audiod
+ *
+ * \param argc usual argument count
+ * \param argv usual argument vector
+ *
+ * It creates a temporary local socket in order to communicate with para_audiod.
+ * Authentication consists in sending a ucred buffer that contains the user id.
+ *
+ * Any output received through the local socket is sent to stdout.
+ *
+ * \return EXIT_SUCCESS or EXIT_FAILURE
+ *
+ * \sa send_cred_buffer(), para_audioc(1), para_audiod(1).
+ */
 int main(int argc, char *argv[])
 {
 	struct sockaddr_un unix_addr;
diff --git a/audiod_command.c b/audiod_command.c
index 349480ff..d1e36490 100644
--- a/audiod_command.c
+++ b/audiod_command.c
@@ -477,7 +477,9 @@ out:
 	}
 	return ret;
 }
-
+/**
+ * send the current audiod status to all connected stat clients
+ */
 void audiod_status_dump(void)
 {
 	struct timeval *t = wstime();
diff --git a/client.c b/client.c
index 12812c9f..95651027 100644
--- a/client.c
+++ b/client.c
@@ -63,8 +63,19 @@ static void client_event_handler(struct task *t)
 	register_task(&sot.task);
 }
 
-/*
- * MAIN
+/**
+ * the client program to connect to para_server
+ *
+ * \param argc usual argument count
+ * \param argv usual argument vector
+ *
+ * It registers two tasks: The client task that communicates with para_server
+ * and the standard out task that writes any output produced by the client task
+ * to standard out.
+ *
+ * \return EXIT_SUCCESS or EXIT_FAILURE
+ *
+ * \sa client_open(), stdout.c, stdout.h, para_client(1), para_server(1)
  */
 int main(int argc, char *argv[])
 {
diff --git a/client.h b/client.h
index ca50ee05..a4d2fe63 100644
--- a/client.h
+++ b/client.h
@@ -44,6 +44,7 @@ enum {
 	CL_RECEIVING,
 };
 
+/** size of the receiving buffer */
 #define CLIENT_BUFSIZE 8192
 
 /**
diff --git a/crypt.c b/crypt.c
index cf1cabec..c1a2d4e5 100644
--- a/crypt.c
+++ b/crypt.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2005-2006 Andre Noll <maan@systemlinux.org>
+ * Copyright (C) 2005-2007 Andre Noll <maan@systemlinux.org>
  *
  *     This program is free software; you can redistribute it and/or modify
  *     it under the terms of the GNU General Public License as published by
@@ -41,7 +41,17 @@ static EVP_PKEY *load_key(const char *file, int private)
 	return pkey;
 }
 
-
+/**
+ * read an RSA key from a file
+ *
+ * \param key_file the file containing the key
+ * \param rsa RSA structure is returned here
+ * \param private if non-zero, read the private key, otherwise the public key
+ *
+ * \return The size of the RSA key on success, negative on errors.
+ *
+ * \sa openssl(1), rsa(1).
+ */
 int get_rsa_key(char *key_file, RSA **rsa, int private)
 {
 	EVP_PKEY *key = load_key(key_file, private);
diff --git a/dccp_send.c b/dccp_send.c
index 128d45b7..c335e768 100644
--- a/dccp_send.c
+++ b/dccp_send.c
@@ -120,7 +120,8 @@ static void dccp_shutdown_client(struct dccp_client *dc)
 	free(dc);
 }
 
-#define DCCP_RETRIES 100
+/** give up if write would block that many times */
+#define DCCP_WRITE_RETRIES 100
 
 static int dccp_write(int fd, const char *buf, size_t len)
 {
@@ -130,7 +131,7 @@ again:
 	size = PARA_MIN(1024, len - written);
 	ret = write(fd, buf + written, size);
 	if (ret < 0) {
-		if (errno != EAGAIN || !retries++ > DCCP_RETRIES)
+		if (errno != EAGAIN || !retries++ > DCCP_WRITE_RETRIES)
 			goto err_out;
 		PARA_DEBUG_LOG("EAGAIN #%d@%zd/%zd\n", retries, written, len);
 		goto again;
diff --git a/filter.h b/filter.h
index 45ade8d3..321d763c 100644
--- a/filter.h
+++ b/filter.h
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2005-2006 Andre Noll <maan@systemlinux.org>
+ * Copyright (C) 2005-2007 Andre Noll <maan@systemlinux.org>
  *
  *     This program is free software; you can redistribute it and/or modify
  *     it under the terms of the GNU General Public License as published by
@@ -209,11 +209,9 @@ struct filter_callback {
 
 
 void close_filters(struct filter_chain *fc);
-int filter_io(struct filter_chain *fc);
 void filter_init(struct filter *all_filters);
 int check_filter_arg(char *filter_arg, void **conf);
-int del_filter_callback(struct filter_callback *fcb);
-void filter_pre_select(struct sched *s, struct task *t);
+void filter_pre_select(__a_unused struct sched *s, struct task *t);
 
 /**
  * the structure associated with a paraslash filter
@@ -340,15 +338,13 @@ DECLARE_EXTERN_FILTER_INIT(oggdec);
 #else
 #define OGGDEC_FILTER
 #endif
+/** \endcond */
 
-/*
- * a macro that defines an array of all available filters
- */
-#define DEFINE_FILTER_ARRAY(fa) struct filter fa[] = { \
+/** define an array of all available filters */
+#define DEFINE_FILTER_ARRAY(filters) struct filter filters[] = { \
 	FILTER_INIT(wav) \
 	FILTER_INIT(compress) \
 	MP3DEC_FILTER \
 	AACDEC_FILTER \
 	OGGDEC_FILTER \
 	{ .name = NULL } };
-/** \endcond */
diff --git a/filter_chain.c b/filter_chain.c
index 70c3d395..8a41beda 100644
--- a/filter_chain.c
+++ b/filter_chain.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2005-2006 Andre Noll <maan@systemlinux.org>
+ * Copyright (C) 2005-2007 Andre Noll <maan@systemlinux.org>
  *
  *     This program is free software; you can redistribute it and/or modify
  *     it under the terms of the GNU General Public License as published by
@@ -100,6 +100,9 @@ static void call_callbacks(struct filter_node *fn, char *inbuf, size_t inlen,
 /**
  * call the convert function of each filter
  *
+ * \param s unused
+ * \param t the task containing the filter chain
+ *
  * This is the core function of the filter subsystem. It loops over the list of
  * filter nodes determined by \a t and calls the filter's convert function if
  * there is input available for the filter node in question. If the convert
diff --git a/http.h b/http.h
index 2542cdc1..112053b6 100644
--- a/http.h
+++ b/http.h
@@ -1,3 +1,7 @@
 /** \file http.h macros used by http_send and http_recv */
+
+/** sent by the http sender to the client */
 #define HTTP_OK_MSG "HTTP/1.0 200 OK\r\n\r\n"
+
+/** sent by the connecting http client (http_recv, xmms, ...) */
 #define HTTP_GET_MSG "GET / HTTP/"
diff --git a/http_recv.c b/http_recv.c
index c418af12..65898338 100644
--- a/http_recv.c
+++ b/http_recv.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2005-2006 Andre Noll <maan@systemlinux.org>
+ * Copyright (C) 2005-2007 Andre Noll <maan@systemlinux.org>
  *
  *     This program is free software; you can redistribute it and/or modify
  *     it under the terms of the GNU General Public License as published by
@@ -51,7 +51,7 @@ struct private_http_recv_data {
  *
  * the current status of the http receiver node
  *
- * It gets initialized to #HTTP_CONNECTED by the open function of the
+ * It gets initialized to \p HTTP_CONNECTED by the open function of the
  * http receiver.
  *
  * \sa receiver::open, receiver_node.
@@ -69,11 +69,11 @@ struct private_http_recv_data {
  *
  * The post_select function of the http receiver uses \a fd, if ready, to
  * establish the http connection, and updates \a status according to the new
- * state of the connection.  As soon as \a status is #HTTP_STREAMING, \a fd is
+ * state of the connection.  As soon as \a status is \p HTTP_STREAMING, \a fd is
  * going to be only checked for reading. If data is available, it is read into
  * the output buffer of the receiver node by post_select.
  *
- * \sa receiver::pre_select receiver::post_select receiver_node
+ * \sa receiver::pre_select receiver::post_select receiver_node, http_recv_status
  */
 	int fd;
 };
diff --git a/ipc.h b/ipc.h
index 733cba6d..c4dd1d7d 100644
--- a/ipc.h
+++ b/ipc.h
@@ -1,5 +1,6 @@
 /** \file ipc.h inter process communication and shared memory routines */
 
+/** possible values for shm_attach() */
 enum shm_attach_mode {ATTACH_RO, ATTACH_RW};
 
 int mutex_new(void);
diff --git a/list.h b/list.h
index 4b946c7c..ba6211ba 100644
--- a/list.h
+++ b/list.h
@@ -13,12 +13,15 @@
 	const typeof( ((type *)0)->member ) *__mptr = (ptr);    \
 	(type *)( (char *)__mptr - offsetof(type,member) );})
 
-/*
- * These are non-NULL pointers that will result in page faults
- * under normal circumstances, used to verify that nobody uses
- * non-initialized list entries.
+/**
+ * Non-NULL pointers that will result in page faults under normal
+ * circumstances, used to verify that nobody uses non-initialized list entries.
+ * Used for poisoning the \a next pointer of struct list_head.
  */
 #define LIST_POISON1  ((void *) 0x00100100)
+/** Non-null pointer, used for poisoning the \a prev pointer of struct
+ * list_head
+ */
 #define LIST_POISON2  ((void *) 0x00200200)
 
 /**
diff --git a/mp3_afh.c b/mp3_afh.c
index 530f36ff..a63e2e86 100644
--- a/mp3_afh.c
+++ b/mp3_afh.c
@@ -483,6 +483,12 @@ static void mp3_close_audio_file(void)
 }
 
 static const char* mp3_suffixes[] = {"mp3", NULL};
+
+/**
+ * the init function of the mp3 audio format handler
+ *
+ * \param p pointer to the struct to initialize
+ */
 void mp3_init(struct audio_format_handler *p)
 {
 	af = p;
diff --git a/mp3dec.c b/mp3dec.c
index 93181ef1..401a03c5 100644
--- a/mp3dec.c
+++ b/mp3dec.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2005-2006 Andre Noll <maan@systemlinux.org>
+ * Copyright (C) 2005-2007 Andre Noll <maan@systemlinux.org>
  *
  *     This program is free software; you can redistribute it and/or modify
  *     it under the terms of the GNU General Public License as published by
@@ -130,6 +130,8 @@ static void mp3dec_open(struct filter_node *fn)
 /**
  * the init function of the mp3dec filter
  *
+ * \param f pointer to the filter struct to initialize
+ *
  * \sa filter::init
  */
 void mp3dec_init(struct filter *f)
diff --git a/net.h b/net.h
index 4a89778b..5ff53987 100644
--- a/net.h
+++ b/net.h
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2006 Andre Noll <maan@systemlinux.org>
+ * Copyright (C) 2006-2007 Andre Noll <maan@systemlinux.org>
  *
  *     This program is free software; you can redistribute it and/or modify
  *     it under the terms of the GNU General Public License as published by
@@ -28,6 +28,7 @@
 #define UNIX_PATH_MAX 108
 #endif
 
+/** used to crypt the communication between para_server and para_client */
 typedef void crypt_function(unsigned long len,
 	const unsigned char *indata, unsigned char *outdata, void *private_data);
 
diff --git a/ogg_afh.c b/ogg_afh.c
index 14163fe6..d295f2d3 100644
--- a/ogg_afh.c
+++ b/ogg_afh.c
@@ -29,7 +29,7 @@
 #include "error.h"
 #include "string.h"
 
-/* must be big enough to hold header */
+/** must be big enough to hold header */
 #define CHUNK_SIZE 32768
 static double chunk_time = 0.25;
 
@@ -117,7 +117,7 @@ err2:
 err1:
 	ogg_sync_destroy(sync_in);
 	vorbis_info_clear(&vi);
-        vorbis_comment_clear(&vc);
+	vorbis_comment_clear(&vc);
 	return ret;
 }
 
@@ -142,7 +142,7 @@ static void tunetable(void)
 	lp = i;
 	for (i = 2; i < num_chunks - lp; i++)
 		chunk_table[i] = chunk_table[i + lp];
-#endif 
+#endif
 }
 
 
@@ -307,7 +307,7 @@ static ogg_int64_t get_chunk_size(long unsigned chunk_num)
 	return ret;
 }
 
-char *ogg_read_chunk(long unsigned current_chunk, ssize_t *len)
+static char *ogg_read_chunk(long unsigned current_chunk, ssize_t *len)
 {
 	int ret;
 	ogg_int64_t cs = get_chunk_size(current_chunk);
@@ -348,6 +348,12 @@ static char *ogg_get_header_info(int *len)
 }
 
 static const char* ogg_suffixes[] = {"ogg", NULL};
+
+/**
+ * the init function of the ogg vorbis audio format handler
+ *
+ * \param p pointer to the struct to initialize
+ */
 void ogg_init(struct audio_format_handler *p)
 {
 	af = p;
diff --git a/osx_write.c b/osx_write.c
index 95a84f2a..4ba173a7 100644
--- a/osx_write.c
+++ b/osx_write.c
@@ -44,7 +44,7 @@ struct osx_buffer {
 	float *buffer;
 	/** the size of this buffer */
 	long size;
-	/* current position in the buffer */
+	/** current position in the buffer */
 	float *ptr;
 	/** number of floats not yet consuned */
 	long remaining;
@@ -60,7 +60,7 @@ struct private_osx_write_data {
 	char play;
 	/** callback reads audio data from this buffer */
 	struct osx_buffer *from;
-	/* the post_select writes audio data here */
+	/** the post_select writes audio data here */
 	struct osx_buffer *to;
 	/** sample rate of the current audio stream */
 	unsigned samplerate;
diff --git a/recv.h b/recv.h
index 7fb45286..573dccc9 100644
--- a/recv.h
+++ b/recv.h
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2005-2006 Andre Noll <maan@systemlinux.org>
+ * Copyright (C) 2005-2007 Andre Noll <maan@systemlinux.org>
  *
  *     This program is free software; you can redistribute it and/or modify
  *     it under the terms of the GNU General Public License as published by
@@ -32,6 +32,7 @@ struct receiver_node {
 	void *private_data;
 	/** set to 1 if end of file is reached */
 	int eof;
+	/** pointer to the eof member of the consumer */
 	int *output_eof;
 	/** pointer to the configuration data for this instance */
 	void *conf;
@@ -150,17 +151,19 @@ extern void ortp_recv_init(struct receiver *r);
 #define ORTP_RECEIVER
 #endif
 
-void *check_receiver_arg(char *ra, int *receiver_num);
-
-
 extern struct receiver receivers[];
 extern void (*crypt_function_recv)(unsigned long len, const unsigned char *indata, unsigned char *outdata);
-extern void (*crypt_function_send)(unsigned long len, const unsigned char *indata, unsigned char *outdata);
+/** \endcond */
 
+/** define an array of all available receivers */
 #define DEFINE_RECEIVER_ARRAY struct receiver receivers[] = { \
 	HTTP_RECEIVER \
 	DCCP_RECEIVER \
 	ORTP_RECEIVER \
 	{.name = NULL}};
 
-/** \endcond */
+void *check_receiver_arg(char *ra, int *receiver_num);
+
+
+extern void (*crypt_function_send)(unsigned long len, const unsigned char *indata, unsigned char *outdata);
+
diff --git a/recv_common.c b/recv_common.c
index 0393d764..8f8f6369 100644
--- a/recv_common.c
+++ b/recv_common.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2006 Andre Noll <maan@systemlinux.org>
+ * Copyright (C) 2006-2007 Andre Noll <maan@systemlinux.org>
  *
  *     This program is free software; you can redistribute it and/or modify
  *     it under the terms of the GNU General Public License as published by
@@ -60,6 +60,21 @@ static void *parse_receiver_args(int receiver_num, char *options)
 	return conf;
 }
 
+/**
+ * check if given string is a valid command line for any receiver
+ *
+ * \param \ra string of the form receiver_name:options
+ * \param receiver_num contains the number of the receiver upon success
+ *
+ * This function checks whether \a ra starts with the name of a supported
+ * paraslash receiver, optinally followed by a colon and any options for that
+ * receiver. If a valid receiver name was found and further are present, the
+ * remaining part of \a ra is passed to that receiver's config parser.
+ *
+ * \return On success, a pointer to the gengetopt args info struct is returned
+ * and \a receiver_num contains the number of the receiver. Otherwise this function
+ * returns \p NULL.
+ */
 void *check_receiver_arg(char *ra, int *receiver_num)
 {
 	int j;
diff --git a/sched.c b/sched.c
index e122903e..2c49050c 100644
--- a/sched.c
+++ b/sched.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2006 Andre Noll <maan@systemlinux.org>
+ * Copyright (C) 2006-2007 Andre Noll <maan@systemlinux.org>
  *
  *     This program is free software; you can redistribute it and/or modify
  *     it under the terms of the GNU General Public License as published by
@@ -65,7 +65,9 @@ static void sched_post_select(struct sched *s)
 /**
  * the core function for all paraslash programs
  *
- * Short and sweet. It updates the global \a now pointer, calls all registered
+ * \param s pointer to the scheduler struct
+ *
+ * This function updates the global \a now pointer, calls all registered
  * pre_select hooks which may set the timeout and add any file descriptors to
  * the fd sets of \a s.  Next, it calls para_select() and makes the result available
  * to the registered tasks by calling their post_select hook.
diff --git a/server.c b/server.c
index f67efa6e..89f901f4 100644
--- a/server.c
+++ b/server.c
@@ -51,15 +51,23 @@ INIT_SERVER_ERRLISTS;
 /** shut down non-authorized connections after that many seconds */
 #define ALARM_TIMEOUT 10
 
-/* these are exported to vss.c. command.c and to all selectors */
+/**
+ * pointer to shared memory area for communication between para_server
+ * and its children. exported to vss.c. command.c and to all selectors.
+ */
 struct misc_meta_data *mmd;
-/** the configuration of para_server
+
+/**
+ * the configuration of para_server
  *
- * It also contains the options for all audio file selectors and all supported
- * senders.
-*/
+ * It also contains the options for all audio file selectors, audio format handler
+ * and all supported senders.
+ */
 struct server_args_info conf;
+
+/** the file containing user information (public key, permissions) */
 char *user_list_file = NULL;
+
 extern void dccp_send_init(struct sender *);
 extern void http_send_init(struct sender *);
 extern void ortp_send_init(struct sender *);
@@ -427,8 +435,14 @@ out:
 	}
 }
 
-/*
- * MAIN
+/**
+ * the main function of para_server
+ *
+ * \param argc usual argument count
+ * \param argv usual argument vector
+ *
+ * \return EXIT_SUCCESS or EXIT_FAILURE
+ *
  */
 int main(int argc, char *argv[])
 {
diff --git a/server.h b/server.h
index dd5184f4..9dee3e34 100644
--- a/server.h
+++ b/server.h
@@ -79,7 +79,7 @@ struct misc_meta_data{
 	char filename[_POSIX_PATH_MAX];
 /** the last modification file of the current audio file */
 	time_t mtime;
-/* the number of the current audio format */
+/** the number of the current audio format */
 	int audio_format;
 /** the "old" status flags -- commands may only read them */
 	unsigned int vss_status_flags;
diff --git a/signal.h b/signal.h
index f853d4cc..9860dd78 100644
--- a/signal.h
+++ b/signal.h
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2006 Andre Noll <maan@systemlinux.org>
+ * Copyright (C) 2007 Andre Noll <maan@systemlinux.org>
  *
  *     This program is free software; you can redistribute it and/or modify
  *     it under the terms of the GNU General Public License as published by
diff --git a/stat.c b/stat.c
index caf432d9..dc511192 100644
--- a/stat.c
+++ b/stat.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2005-2006 Andre Noll <maan@systemlinux.org>
+ * Copyright (C) 2005-2007 Andre Noll <maan@systemlinux.org>
  *
  *     This program is free software; you can redistribute it and/or modify
  *     it under the terms of the GNU General Public License as published by
@@ -103,8 +103,14 @@ static void dump_stat_client_list(void)
 /**
  * add a status client to the list
  *
+ * \param fd the file descriptor of the client
+ * \param mask bitfield of status items for this client
+ *
+ * Only those status items having the bit set in \a mask will be
+ * sent to the client.
+ *
  * \return Positive value on success, or -E_TOO_MANY_CLIENTS if
- * the number of connected clients exceeds #MAX_STAT_CLIENTS
+ * the number of connected clients exceeds #MAX_STAT_CLIENTS.
  */
 int stat_client_add(int fd, long unsigned mask)
 {
diff --git a/user_list.c b/user_list.c
index c3b10b1e..b7d739c1 100644
--- a/user_list.c
+++ b/user_list.c
@@ -93,6 +93,14 @@ out:
 	exit(EXIT_FAILURE);
 }
 
+/**
+ * initialize the list of users allowed to connecto to para_server
+ *
+ * \param user_list_file the file containing access information
+ *
+ * If this function is called a second time, the contents of the
+ * previous call are discarded.
+ */
 void init_user_list(char *user_list_file)
 {
 	struct user *u, *tmp;
diff --git a/vss.c b/vss.c
index f9e2d6c2..4a395593 100644
--- a/vss.c
+++ b/vss.c
@@ -82,6 +82,8 @@ static struct audio_format_handler afl[] = {
 		.name = NULL,
 	}
 };
+
+/** iterate over each supported audio format */
 #define FOR_EACH_AUDIO_FORMAT(i) for (i = 0; afl[i].name; i++)
 
 /**
@@ -406,6 +408,14 @@ char *vss_get_header(int *header_len)
 		return NULL;
 	return afl[mmd->audio_format].get_header_info(header_len);
 }
+
+/**
+ * get the list of all supported audio formats
+ *
+ * \return a space separated list of all supported audio formats
+ * It is not allocated at runtime, i.e. there is no need to free
+ * the returned string in the caller.
+ */
 const char *supported_audio_formats(void)
 {
 	return SUPPORTED_AUDIO_FORMATS;
diff --git a/vss.h b/vss.h
index 545647b7..0234296f 100644
--- a/vss.h
+++ b/vss.h
@@ -29,9 +29,14 @@ char *vss_get_header(int *header_len);
 struct timeval *vss_chunk_time(void);
 int guess_audio_format(const char *name);
 const char *supported_audio_formats(void);
-/* status flags */
+
+/** stop playing after current audio file */
 #define VSS_NOMORE 1
+/** skip remaining part of current audio file */
 #define VSS_NEXT 2
+/** a reposition request was sent by a client */
 #define VSS_REPOS 4
+/** currently playing */
 #define VSS_PLAYING 8
+/** a client requested to change the audio file selector */
 #define VSS_CHANGE 16
diff --git a/write.c b/write.c
index 683a91b0..3671633b 100644
--- a/write.c
+++ b/write.c
@@ -216,9 +216,13 @@ static void cwt_event_handler(struct task *t)
 /**
  * para_write's main function
  *
+ * \param argc the usual argument counter
+ * \param argv the usual argument vector
+ *
  * It registers the stdin task, the check_wav_task, the task for initial delay
  * and all tasks for actually writing out the stream.
  *
+ * \return \p EXIT_SUCCESS or EXIT_FAILURE
  */
 int main(int argc, char *argv[])
 {
diff --git a/write.h b/write.h
index 9f236634..52d6f5af 100644
--- a/write.h
+++ b/write.h
@@ -80,7 +80,7 @@ struct writer {
 	 * on errors.
 	 */
 	int (*pre_select)(struct sched *s, struct writer_node *wn);
-	/*
+	/**
 	 * Called from the post_select function of the wng task. It must keep
 	 * track of the the number of bytes consumed from the wng's buffer via
 	 * the wn->written variable (which may be modified by the wng handling
diff --git a/write_common.c b/write_common.c
index b1ab00cf..ac92bc1a 100644
--- a/write_common.c
+++ b/write_common.c
@@ -25,7 +25,10 @@
 #include "write.h"
 #include "error.h"
 
+/** the array containing the names of all supported writers */
 const char *writer_names[] ={WRITER_NAMES};
+
+/** the array of supported writers */
 struct writer writers[NUM_SUPPORTED_WRITERS] = {WRITER_ARRAY};
 
 static void wng_pre_select(__a_unused struct sched *s, struct task *t)
@@ -79,6 +82,16 @@ static void wng_post_select(struct sched *s, struct task *t)
 	}
 }
 
+/**
+ * call the open function of each writer in the group
+ *
+ * \param g the writer node group
+ *
+ * \return If at least one open function returned an error, all successful
+ * writer notes get closed and this error value is returned. Upon success, a
+ * task associated with \a g is registered to the scheduler and the function
+ * returnes a positive value.
+ * */
 int wng_open(struct writer_node_group *g)
 {
 	int i, ret = 1;
@@ -108,12 +121,25 @@ err_out:
 	return ret;
 }
 
+
+/**
+ * unregister a writer node group task
+ *
+ * \param g the group whose task is to be closed
+ */
 void wng_unregister(struct writer_node_group *g)
 {
 	unregister_task(&g->task);
 	g->eof = 1;
 }
 
+/**
+ * call the close function of each writer in the given group
+ *
+ * \param g the writer node group to close
+ *
+ * This function also frees all resources of the given group.
+ */
 void wng_close(struct writer_node_group *g)
 {
 	int i;
@@ -129,6 +155,13 @@ void wng_close(struct writer_node_group *g)
 	free(g);
 }
 
+/**
+ * allocate and initialize a new writer_node_group struct
+ *
+ * \param num_writers the number of writer nodes for the new group
+ *
+ * \return Pointer to the new writer node group
+ */
 struct writer_node_group *wng_new(unsigned num_writers)
 {
 	struct writer_node_group *g = para_calloc(sizeof(struct writer_node_group));
@@ -141,6 +174,9 @@ struct writer_node_group *wng_new(unsigned num_writers)
 	return g;
 }
 
+/**
+ * call the init function of each supported paraslash writer
+ */
 void init_supported_writers(void)
 {
 	int i;
@@ -148,7 +184,21 @@ void init_supported_writers(void)
 	FOR_EACH_WRITER(i)
 		writers[i].init(&writers[i]);
 }
-
+/**
+ * check if given string is a valid command line for any writer
+ *
+ * \param \wa string of the form writer_name:options
+ * \param writer_num contains the number of the writer upon success
+ *
+ * This function checks whether \a wa starts with the name of a supported
+ * paraslash writer, optinally followed by a colon and any options for that
+ * writer.  If a valid writer name was found and further are present, the
+ * remaining part of \a wa is passed to that writer's config parser.
+ *
+ * \return On success, a pointer to the gengetopt args info struct is returned
+ * and \a writer_num contains the number of the writer. Otherwise this function
+ * returns \p NULL.
+ */
 void *check_writer_arg(const char *wa, int *writer_num)
 {
 	int i;
@@ -175,6 +225,14 @@ void *check_writer_arg(const char *wa, int *writer_num)
 	return NULL;
 }
 
+/**
+ * setup a writer node group with only one writer, the default writer
+ *
+ * The writer which is set up depends on the OS. It defaults to alsa for Linux,
+ * osx_write for OS X, file writer if neither of these is supported.
+ *
+ * \return pointer to the allocated writer node group
+ */
 struct writer_node_group *setup_default_wng(void)
 {
 	struct writer_node_group *wng = wng_new(1);
diff --git a/write_common.h b/write_common.h
index cdc2b66c..ee162641 100644
--- a/write_common.h
+++ b/write_common.h
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2006 Andre Noll <maan@systemlinux.org>
+ * Copyright (C) 2006-2007 Andre Noll <maan@systemlinux.org>
  *
  *     This program is free software; you can redistribute it and/or modify
  *     it under the terms of the GNU General Public License as published by
@@ -18,11 +18,10 @@
 
 /** \file write_common.h exported symbols from write_common.c */
 
-int wng_write(struct writer_node_group *g, char *buf, size_t *loaded);
 int wng_open(struct writer_node_group *g);
 void wng_close(struct writer_node_group *g);
 struct writer_node_group *wng_new(unsigned num_writers);
 void wng_unregister(struct writer_node_group *g);
 void init_supported_writers(void);
-void *check_writer_arg(char *wa, int *writer_num);
+void *check_writer_arg(const char *wa, int *writer_num);
 struct writer_node_group *setup_default_wng(void);
-- 
2.39.5