Comment some more files

git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@309 fefdeb5f-60dc-0310-8127-8f9354f1896f

45 files changed, 428 insertions, 81 deletions

diff --git a/doc/README.html.in b/doc/README.html.in
index 742ea3d1..31511886 100644
--- a/doc/README.html.in
+++ b/doc/README.html.in
@@ -40,10 +40,20 @@ Lesser General Public License for more details.</p>
 along with this program; if not, write to the Free Software
 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.</p>
 
-<p><i>Exception: The client libraries are licensed under LGPL, the Lesser GNU General Plublic License.</i></p>
-
 <h2><a name="news">News</a></h2>
 
+<div class="news-date">Sun Nov 21 2004: </div> <p class="news-text"><a
+href="@PACKAGE_URL@polypaudio-0.7.tar.gz">Version 0.7</a> released;
+changes include: TCP wrappers support; don't load the complete sound
+file into memory when playing back using <tt>pa_play_file()</tt>;
+autoload API change; don't load all sound files as FLOAT32; shorten
+default buffers; client-side latency interpolation; add new user
+volume metrics; add <tt>module-tunnel</tt>, <tt>module-null-sink</tt>,
+<tt>module-match</tt> and new tool <tt>paplay</tt>; new API version
+macros; many client API improvements; correctly lock cookie file
+generation; correctly lock daemon autospawning; print daemon layout to
+STDERR on SIGHUP; new options for <tt>pacat</tt>: allow sample type specification.</p>
+
 <div class="news-date">Thu Oct 28 2004: </div> <p class="news-text"><a
 href="@PACKAGE_URL@polypaudio-0.6.tar.gz">Version 0.6</a> released;
 changes include: TCP wrappers support; don't load the complete sound
diff --git a/polyp/authkey-prop.h b/polyp/authkey-prop.h
index 1a668117..1b1948c7 100644
--- a/polyp/authkey-prop.h
+++ b/polyp/authkey-prop.h
@@ -24,6 +24,10 @@
 
 #include "core.h"
 
+/* The authkey-prop uses a central property to store a previously
+ * loaded cookie in memory. Useful for sharing the same cookie between
+ * several modules. */
+
 /* Return the data of the specified authorization key property. Doesn't alter the refernce count of the key */
 int pa_authkey_prop_get(struct pa_core *c, const char *name, void *data, size_t len);
 
diff --git a/polyp/authkey.c b/polyp/authkey.c
index 05324a61..1355c8d9 100644
--- a/polyp/authkey.c
+++ b/polyp/authkey.c
@@ -41,6 +41,7 @@
 
 #define RANDOM_DEVICE "/dev/urandom"
 
+/* Generate a new authorization key, store it in file fd and return it in *data  */
 static int generate(int fd, void *data, size_t length) {
     int random_fd, ret = -1;
     ssize_t r;
@@ -66,6 +67,7 @@ static int generate(int fd, void *data, size_t length) {
     }
 
     lseek(fd, 0, SEEK_SET);
+    ftruncate(fd, 0);
 
     if ((r = pa_loop_write(fd, data, length)) < 0 || (size_t) r != length) {
         pa_log(__FILE__": failed to write cookie file: %s\n", strerror(errno));
@@ -82,6 +84,8 @@ finish:
     return ret;
 }
 
+/* Load an euthorization cookie from file fn and store it in data. If
+ * the cookie file doesn't exist, create it */
 static int load(const char *fn, void *data, size_t length) {
     int fd = -1;
     int writable = 1;
@@ -130,6 +134,7 @@ finish:
     return ret;
 }
 
+/* Load a cookie from a cookie file. If the file doesn't exist, create it. */
 int pa_authkey_load(const char *path, void *data, size_t length) {
     int ret;
 
@@ -144,6 +149,8 @@ int pa_authkey_load(const char *path, void *data, size_t length) {
     return ret;
 }
 
+/* If the specified file path starts with / return it, otherwise
+ * return path prepended with home directory */
 static const char *normalize_path(const char *fn, char *s, size_t l) {
     assert(fn && s && l > 0);
 
@@ -159,7 +166,9 @@ static const char *normalize_path(const char *fn, char *s, size_t l) {
     return fn;
 }
 
-int pa_authkey_load_from_home(const char *fn, void *data, size_t length) {
+/* Load a cookie from a file in the home directory. If the specified
+ * path starts with /, use it as absolute path instead. */
+int pa_authkey_load_auto(const char *fn, void *data, size_t length) {
     char path[PATH_MAX];
     const char *p;
     assert(fn && data && length);
@@ -170,15 +179,7 @@ int pa_authkey_load_from_home(const char *fn, void *data, size_t length) {
     return pa_authkey_load(p, data, length);
 }
 
-int pa_authkey_load_auto(const char *fn, void *data, size_t length) {
-    assert(fn && data && length);
-
-    if (*fn == '/')
-        return pa_authkey_load(fn, data, length);
-    else
-        return pa_authkey_load_from_home(fn, data, length);
-}
-
+/* Store the specified cookie in the speicified cookie file */
 int pa_authkey_save(const char *fn, const void *data, size_t length) {
     int fd = -1;
     int unlock = 0, ret = -1;
diff --git a/polyp/authkey.h b/polyp/authkey.h
index a6006dfc..81b1a578 100644
--- a/polyp/authkey.h
+++ b/polyp/authkey.h
@@ -25,7 +25,6 @@
 #include <sys/types.h>
 
 int pa_authkey_load(const char *path, void *data, size_t len);
-int pa_authkey_load_from_home(const char *fn, void *data, size_t length);
 int pa_authkey_load_auto(const char *fn, void *data, size_t length);
 
 int pa_authkey_save(const char *path, const void *data, size_t length);
diff --git a/polyp/autoload.h b/polyp/autoload.h
index 8537173c..23475684 100644
--- a/polyp/autoload.h
+++ b/polyp/autoload.h
@@ -24,19 +24,32 @@
 
 #include "namereg.h"
 
+/* Using the autoloading facility, modules by be loaded on-demand and
+ * synchronously. The user may register a "ghost sink" or "ghost
+ * source". Whenever this sink/source is requested but not available a
+ * specified module is loaded. */
+
+/* An autoload entry, or "ghost" sink/source */
 struct pa_autoload_entry {
     struct pa_core *core;
     uint32_t index;
     char *name;
-    enum pa_namereg_type type;
-    int in_action;
+    enum pa_namereg_type type; /* Type of the autoload entry */
+    int in_action; /* Currently loaded */
     char *module, *argument;   
 };
 
+/* Add a new autoload entry of the given time, with the speicified
+ * sink/source name, module name and argument. Return the entry's
+ * index in *index */
 int pa_autoload_add(struct pa_core *c, const char*name, enum pa_namereg_type type, const char*module, const char *argument, uint32_t *index);
+
+/* Free all autoload entries */
 void pa_autoload_free(struct pa_core *c);
 int pa_autoload_remove_by_name(struct pa_core *c, const char*name, enum pa_namereg_type type);
 int pa_autoload_remove_by_index(struct pa_core *c, uint32_t index);
+
+/* Request an autoload entry by its name, effectively causing a module to be loaded */
 void pa_autoload_request(struct pa_core *c, const char *name, enum pa_namereg_type type);
 
 const struct pa_autoload_entry* pa_autoload_get_by_name(struct pa_core *c, const char*name, enum pa_namereg_type type);
diff --git a/polyp/caps.c b/polyp/caps.c
index e2f4573a..34d97eb5 100644
--- a/polyp/caps.c
+++ b/polyp/caps.c
@@ -45,6 +45,7 @@ void pa_drop_root(void) {
 /*     pa_log(__FILE__": dropping root rights.\n"); */
     
     setreuid(uid, uid);
+
 /*    setuid(uid);
     seteuid(uid);*/
 }
diff --git a/polyp/cli-command.c b/polyp/cli-command.c
index c11647fc..72e04bf8 100644
--- a/polyp/cli-command.c
+++ b/polyp/cli-command.c
@@ -56,6 +56,7 @@ struct command {
     unsigned args;
 };
 
+/* Prototypes for all available commands */
 static int pa_cli_command_exit(struct pa_core *c, struct pa_tokenizer *t, struct pa_strbuf *buf, int *fail, int *verbose);
 static int pa_cli_command_help(struct pa_core *c, struct pa_tokenizer *t, struct pa_strbuf *buf, int *fail, int *verbose);
 static int pa_cli_command_modules(struct pa_core *c, struct pa_tokenizer *t, struct pa_strbuf *buf, int *fail, int *verbose);
@@ -87,6 +88,9 @@ static int pa_cli_command_autoload_remove(struct pa_core *c, struct pa_tokenizer
 static int pa_cli_command_dump(struct pa_core *c, struct pa_tokenizer *t, struct pa_strbuf *buf, int *fail, int *verbose);
 static int pa_cli_command_list_props(struct pa_core *c, struct pa_tokenizer *t, struct pa_strbuf *buf, int *fail, int *verbose);
 
+
+/* A method table for all available commands */
+
 static const struct command commands[] = {
     { "exit",                    pa_cli_command_exit,               "Terminate the daemon",         1 },
     { "help",                    pa_cli_command_help,               "Show this help",               1 },
diff --git a/polyp/cli-command.h b/polyp/cli-command.h
index 0f089f61..4887c55e 100644
--- a/polyp/cli-command.h
+++ b/polyp/cli-command.h
@@ -25,8 +25,17 @@
 #include "strbuf.h"
 #include "core.h"
 
+/* Execute a single CLI command. Write the results to the string
+ * buffer *buf. If *fail is non-zero the function will return -1 when
+ * one or more of the executed commands failed. If *verbose is
+ * non-zero the command is executed verbosely. Both *verbose and *fail
+ * may be modified by the function call. */
 int pa_cli_command_execute_line(struct pa_core *c, const char *s, struct pa_strbuf *buf, int *fail, int *verbose);
+
+/* Execute a whole file of CLI commands */
 int pa_cli_command_execute_file(struct pa_core *c, const char *fn, struct pa_strbuf *buf, int *fail, int *verbose);
+
+/* Split the specified string into lines and run pa_cli_command_execute_line() for each. */
 int pa_cli_command_execute(struct pa_core *c, const char *s, struct pa_strbuf *buf, int *fail, int *verbose);
 
 #endif
diff --git a/polyp/cli-text.h b/polyp/cli-text.h
index 1457d055..65607e94 100644
--- a/polyp/cli-text.h
+++ b/polyp/cli-text.h
@@ -24,6 +24,9 @@
 
 #include "core.h"
 
+/* Some functions to generate pretty formatted listings of
+ * entities. The returned strings have to be freed manually. */
+
 char *pa_sink_input_list_to_string(struct pa_core *c);
 char *pa_source_output_list_to_string(struct pa_core *c);
 char *pa_sink_list_to_string(struct pa_core *core);
diff --git a/polyp/cli.h b/polyp/cli.h
index bfe0c4f8..44ed706c 100644
--- a/polyp/cli.h
+++ b/polyp/cli.h
@@ -28,9 +28,11 @@
 
 struct pa_cli;
 
+/* Create a new command line session on the specified io channel owned by the specified module */
 struct pa_cli* pa_cli_new(struct pa_core *core, struct pa_iochannel *io, struct pa_module *m);
 void pa_cli_free(struct pa_cli *cli);
 
+/* Set a callback function that is called whenever the command line session is terminated */
 void pa_cli_set_eof_callback(struct pa_cli *cli, void (*cb)(struct pa_cli*c, void *userdata), void *userdata);
 
 #endif
diff --git a/polyp/client-conf-x11.h b/polyp/client-conf-x11.h
index 951ef0b1..e65e8202 100644
--- a/polyp/client-conf-x11.h
+++ b/polyp/client-conf-x11.h
@@ -24,6 +24,8 @@
 
 #include "client-conf.h"
 
+/* Load client configuration data from the specified X11 display,
+ * overwriting the current settings in *c */
 int pa_client_conf_from_x11(struct pa_client_conf *c, const char *display);
 
 #endif
diff --git a/polyp/client-conf.c b/polyp/client-conf.c
index 21e0acab..4906383d 100644
--- a/polyp/client-conf.c
+++ b/polyp/client-conf.c
@@ -82,6 +82,7 @@ int pa_client_conf_load(struct pa_client_conf *c, const char *filename) {
     char *fn = NULL;
     int r = -1;
 
+    /* Prepare the configuration parse table */
     struct pa_config_item table[] = {
         { "daemon-binary",          pa_config_parse_string,  NULL },
         { "extra-arguments",        pa_config_parse_string,  NULL },
diff --git a/polyp/client-conf.h b/polyp/client-conf.h
index cf7dd095..b4625039 100644
--- a/polyp/client-conf.h
+++ b/polyp/client-conf.h
@@ -24,19 +24,29 @@
 
 #include "native-common.h"
 
+/* A structure containing configuration data for polypaudio clients. */
+
 struct pa_client_conf {
     char *daemon_binary, *extra_arguments, *default_sink, *default_source, *default_server, *cookie_file;
     int autospawn;
     uint8_t cookie[PA_NATIVE_COOKIE_LENGTH];
-    int cookie_valid;
+    int cookie_valid; /* non-zero, when cookie is valid */
 };
 
+/* Create a new configuration data object and reset it to defaults */
 struct pa_client_conf *pa_client_conf_new(void);
 void pa_client_conf_free(struct pa_client_conf *c);
 
+/* Load the configuration data from the speicified file, overwriting
+ * the current settings in *c. When the filename is NULL, the
+ * default client configuration file name is used. */
 int pa_client_conf_load(struct pa_client_conf *c, const char *filename);
+
+/* Load the configuration data from the environment of the current
+   process, overwriting the current settings in *c. */
 int pa_client_conf_env(struct pa_client_conf *c);
 
+/* Load cookie data from c->cookie_file into c->cookie */
 int pa_client_conf_load_cookie(struct pa_client_conf* c);
 
 #endif
diff --git a/polyp/client.c b/polyp/client.c
index b525fe6b..22c7197a 100644
--- a/polyp/client.c
+++ b/polyp/client.c
@@ -42,7 +42,7 @@ struct pa_client *pa_client_new(struct pa_core *core, const char *protocol_name,
     c->name = pa_xstrdup(name);
     c->owner = NULL;
     c->core = core;
-    c->protocol_name = protocol_name;
+    c->protocol_name = pa_xstrdup(protocol_name);
 
     c->kill = NULL;
     c->userdata = NULL;
@@ -68,6 +68,7 @@ void pa_client_free(struct pa_client *c) {
     pa_log(__FILE__": freed %u \"%s\"\n", c->index, c->name);
     pa_subscription_post(c->core, PA_SUBSCRIPTION_EVENT_CLIENT|PA_SUBSCRIPTION_EVENT_REMOVE, c->index);
     pa_xfree(c->name);
+    pa_xfree(c->protocol_name);
     pa_xfree(c);
 
 }
diff --git a/polyp/client.h b/polyp/client.h
index 2518011e..58c5ee31 100644
--- a/polyp/client.h
+++ b/polyp/client.h
@@ -25,6 +25,10 @@
 #include "core.h"
 #include "module.h"
 
+/* Every connection to the server should have a pa_client
+ * attached. That way the user may generate a listing of all connected
+ * clients easily and kill them if he wants.*/
+
 struct pa_client {
     uint32_t index;
 
@@ -37,6 +41,7 @@ struct pa_client {
     void *userdata;
 };
 
+/* Protocol name should be something like "ESOUND", "NATIVE", ... */
 struct pa_client *pa_client_new(struct pa_core *c, const char *protocol_name, char *name);
 
 /* This function should be called only by the code that created the client */
@@ -46,6 +51,7 @@ void pa_client_free(struct pa_client *c);
  * request destruction of the client */
 void pa_client_kill(struct pa_client *c);
 
+/* Rename the client */
 void pa_client_set_name(struct pa_client *c, const char *name);
 
 #endif
diff --git a/polyp/cmdline.c b/polyp/cmdline.c
index e11d8aad..a39f6ca6 100644
--- a/polyp/cmdline.c
+++ b/polyp/cmdline.c
@@ -35,6 +35,7 @@
 #include "strbuf.h"
 #include "xmalloc.h"
 
+/* Argument codes for getopt_long() */
 enum {
     ARG_HELP = 256,
     ARG_VERSION,
@@ -58,6 +59,7 @@ enum {
     ARG_CHECK
 };
 
+/* Tabel for getopt_long() */
 static struct option long_options[] = {
     {"help",                        0, 0, ARG_HELP},
     {"version",                     0, 0, ARG_VERSION},
diff --git a/polyp/cmdline.h b/polyp/cmdline.h
index 28e7bdbc..ca100d1d 100644
--- a/polyp/cmdline.h
+++ b/polyp/cmdline.h
@@ -24,8 +24,12 @@
 
 #include "daemon-conf.h"
 
+/* Parese the command line and store its data in *c. Return the index
+ * of the first unparsed argument in *d. */
 int pa_cmdline_parse(struct pa_daemon_conf*c, int argc, char *const argv [], int *d);
 
+/* Show the command line help. The command name is extracted from
+ * argv[0] which should be passed in argv0. */
 void pa_cmdline_help(const char *argv0);
 
 #endif
diff --git a/polyp/conf-parser.c b/polyp/conf-parser.c
index 40b00cda..35c4766e 100644
--- a/polyp/conf-parser.c
+++ b/polyp/conf-parser.c
@@ -32,6 +32,7 @@
 #define WHITESPACE " \t\n"
 #define COMMENTS "#;\n"
 
+/* Run the user supplied parser for an assignment */
 static int next_assignment(const char *filename, unsigned line, const struct pa_config_item *t, const char *lvalue, const char *rvalue, void *userdata) {
     assert(filename && t && lvalue && rvalue);
     
@@ -44,6 +45,7 @@ static int next_assignment(const char *filename, unsigned line, const struct pa_
     return -1;
 }
 
+/* Returns non-zero when c is contained in s */
 static int in_string(char c, const char *s) {
     assert(s);
     
@@ -54,6 +56,8 @@ static int in_string(char c, const char *s) {
     return 0;
 }
 
+/* Remove all whitepsapce from the beginning and the end of *s. *s may
+ * be modified. */
 static char *strip(char *s) {
     char *b = s+strspn(s, WHITESPACE);
     char *e, *l = NULL;
@@ -68,6 +72,7 @@ static char *strip(char *s) {
     return b;
 }
 
+/* Parse a variable assignment line */
 static int parse_line(const char *filename, unsigned line, const struct pa_config_item *t, char *l, void *userdata) {
     char *e, *c, *b = l+strspn(l, WHITESPACE);
 
@@ -88,7 +93,7 @@ static int parse_line(const char *filename, unsigned line, const struct pa_confi
     return next_assignment(filename, line, t, strip(b), strip(e), userdata);
 }
 
-
+/* Go through the file and parse each line */
 int pa_config_parse(const char *filename, FILE *f, const struct pa_config_item *t, void *userdata) {
     int r = -1;
     unsigned line = 0;
diff --git a/polyp/conf-parser.h b/polyp/conf-parser.h
index 48cfbc14..9add0be0 100644
--- a/polyp/conf-parser.h
+++ b/polyp/conf-parser.h
@@ -24,14 +24,22 @@
 
 #include <stdio.h>
 
+/* An abstract parser for simple, line based, shallow configuration
+ * files consisting of variable assignments only. */
+
+/* Wraps info for parsing a specific configuration variable */
 struct pa_config_item {
-    const char *lvalue;
-    int (*parse)(const char *filename, unsigned line, const char *lvalue, const char *rvalue, void *data, void *userdata);
-    void *data;
+    const char *lvalue; /* name of the variable */
+    int (*parse)(const char *filename, unsigned line, const char *lvalue, const char *rvalue, void *data, void *userdata); /* Function that is called to parse the variable's value */
+    void *data; /* Where to store the variable's data */
 };
 
+/* The configuration file parsing routine. Expects a table of
+ * pa_config_items in *t that is terminated by an item where lvalue is
+ * NULL */
 int pa_config_parse(const char *filename, FILE *f, const struct pa_config_item *t, void *userdata);
 
+/* Generic parsers for integers, booleans and strings */
 int pa_config_parse_int(const char *filename, unsigned line, const char *lvalue, const char *rvalue, void *data, void *userdata);
 int pa_config_parse_bool(const char *filename, unsigned line, const char *lvalue, const char *rvalue, void *data, void *userdata);
 int pa_config_parse_string(const char *filename, unsigned line, const char *lvalue, const char *rvalue, void *data, void *userdata);
diff --git a/polyp/core.h b/polyp/core.h
index 09e58b46..6c6070b1 100644
--- a/polyp/core.h
+++ b/polyp/core.h
@@ -29,13 +29,20 @@
 #include "memblock.h"
 #include "resampler.h"
 
+/* The core structure of polypaudio. Every polypaudio daemon contains
+ * exactly one of these. It is used for storing kind of global
+ * variables for the daemon. */
+
 struct pa_core {
     struct pa_mainloop_api *mainloop;
 
+    /* idxset of all kinds of entities */
     struct pa_idxset *clients, *sinks, *sources, *sink_inputs, *source_outputs, *modules, *scache, *autoload_idxset;
 
+    /* Some hashmaps for all sorts of entities */
     struct pa_hashmap *namereg, *autoload_hashmap, *properties;
 
+    /* The name of the default sink/source */
     char *default_source_name, *default_sink_name;
 
     struct pa_sample_spec default_sample_spec;
@@ -60,6 +67,8 @@ struct pa_core {
 
 struct pa_core* pa_core_new(struct pa_mainloop_api *m);
 void pa_core_free(struct pa_core*c);
+
+/* Check whether noone is connected to this core */
 void pa_core_check_quit(struct pa_core *c);
 
 #endif
diff --git a/polyp/cpulimit-test.c b/polyp/cpulimit-test.c
index 83d403f5..de5e20ad 100644
--- a/polyp/cpulimit-test.c
+++ b/polyp/cpulimit-test.c
@@ -4,21 +4,25 @@
   This file is part of polypaudio.
  
   polypaudio is free software; you can redistribute it and/or modify
-  it under the terms of the GNU Lesser General Public License as published
-  by the Free Software Foundation; either version 2 of the License,
-  or (at your option) any later version.
+  it under the terms of the GNU Lesser General Public License as
+  published by the Free Software Foundation; either version 2 of the
+  License, or (at your option) any later version.
  
   polypaudio is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
   General Public License for more details.
  
-  You should have received a copy of the GNU Lesser General Public License
-  along with polypaudio; if not, write to the Free Software
+  You should have received a copy of the GNU Lesser General Public
+  License along with polypaudio; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
   USA.
 ***/
 
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+#endif
+
 #include <assert.h>
 #include <sys/time.h>
 #include <stdlib.h>
@@ -32,6 +36,8 @@
 #include "mainloop-signal.h"
 #endif
 
+/* A simple example for testing the cpulimit subsystem */
+
 static time_t start;
 
 #ifdef TEST2
diff --git a/polyp/cpulimit.c b/polyp/cpulimit.c
index 78dc5e1f..0fab98a0 100644
--- a/polyp/cpulimit.c
+++ b/polyp/cpulimit.c
@@ -4,21 +4,25 @@
   This file is part of polypaudio.
  
   polypaudio is free software; you can redistribute it and/or modify
-  it under the terms of the GNU Lesser General Public License as published
-  by the Free Software Foundation; either version 2 of the License,
-  or (at your option) any later version.
+  it under the terms of the GNU Lesser General Public License as
+  published by the Free Software Foundation; either version 2 of the
+  License, or (at your option) any later version.
  
   polypaudio is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
   General Public License for more details.
  
-  You should have received a copy of the GNU Lesser General Public License
-  along with polypaudio; if not, write to the Free Software
+  You should have received a copy of the GNU Lesser General Public
+  License along with polypaudio; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
   USA.
 ***/
 
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+#endif
+
 #include <errno.h>
 #include <stdio.h>
 #include <string.h>
diff --git a/polyp/daemon-conf.h b/polyp/daemon-conf.h
index 8a574272..f163400f 100644
--- a/polyp/daemon-conf.h
+++ b/polyp/daemon-conf.h
@@ -24,16 +24,18 @@
 
 #include "log.h"
 
+/* The actual command to execute */
 enum pa_daemon_conf_cmd {
-	PA_CMD_DAEMON,
-	PA_CMD_HELP,
-        PA_CMD_VERSION,
-	PA_CMD_DUMP_CONF,
-	PA_CMD_DUMP_MODULES,
-        PA_CMD_KILL,
-        PA_CMD_CHECK
+    PA_CMD_DAEMON,  /* the default */
+    PA_CMD_HELP,
+    PA_CMD_VERSION,
+    PA_CMD_DUMP_CONF,
+    PA_CMD_DUMP_MODULES,
+    PA_CMD_KILL,
+    PA_CMD_CHECK
 };
 
+/* A structure containing configuration data for the Polypaudio server . */
 struct pa_daemon_conf {
     enum pa_daemon_conf_cmd cmd;
     int daemonize,
@@ -52,13 +54,25 @@ struct pa_daemon_conf {
     char *config_file;
 };
 
+/* Allocate a new structure and fill it with sane defaults */
 struct pa_daemon_conf* pa_daemon_conf_new(void);
 void pa_daemon_conf_free(struct pa_daemon_conf*c);
 
+/* Load configuration data from the specified file overwriting the
+ * current settings in *c. If filename is NULL load the default daemon
+ * configuration file */
 int pa_daemon_conf_load(struct pa_daemon_conf *c, const char *filename);
+
+/* Pretty print the current configuration data of the daemon. The
+ * returned string has to be freed manually. The output of this
+ * function may be parsed with pa_daemon_conf_load(). */
 char *pa_daemon_conf_dump(struct pa_daemon_conf *c);
+
+/* Load the configuration data from the process' environment
+ * overwriting the current settings in *c. */
 int pa_daemon_conf_env(struct pa_daemon_conf *c);
 
+/* Set these configuration variables in the structure by passing a string */
 int pa_daemon_conf_set_log_target(struct pa_daemon_conf *c, const char *string);
 int pa_daemon_conf_set_resample_method(struct pa_daemon_conf *c, const char *string);
 
diff --git a/polyp/daemon.conf.in b/polyp/daemon.conf.in
index ddc4955c..d5373018 100644
--- a/polyp/daemon.conf.in
+++ b/polyp/daemon.conf.in
@@ -60,8 +60,18 @@
 ## true, otherwise to "stderr".
 ; log-target = auto
 
-## The resampling algorithm to use. Use one of sinc-best-quality,
-## sinc-medium-quality, sinc-fastest, zero-order-hold, linear.  See
-## the documentation of libsamplerate for an explanation fot the
-## different methods.
+## The resampling algorithm to use. Use one of src-sinc-best-quality,
+## src-sinc-medium-quality, src-sinc-fastest, src-zero-order-hold,
+## src-linear, trivial. See the documentation of libsamplerate for an
+## explanation for the different methods. The method 'trivial' is the
+## only algorithm implemented without usage of floating point
+## numbers. If you're tight on CPU consider using this. On the other
+## hand it has the worst quality of all.
 ; resample-method = sinc-fastest
+
+## Create a PID file in /tmp/polypaudio-$USER/pid. Of this is enabled
+## you may use commands like "polypaudio --kill" or "polypaudio
+## --check". If you are planning to start more than one polypaudio
+## process per user, you better disable this option since it
+## effectively disables multiple instances.
+; use-pid-file = 1
diff --git a/polyp/default.pa.in b/polyp/default.pa.in
index 07ff373c..3aaeeaf0 100755
--- a/polyp/default.pa.in
+++ b/polyp/default.pa.in
@@ -21,8 +21,8 @@
 # Load audio drivers statically
 
 #load-module module-alsa-sink
-load-module module-alsa-source device=plughw:1,0
-load-module module-oss device="/dev/dsp" sink_name=output source_name=input record=0
+# load-module module-alsa-source device=plughw:1,0
+load-module module-oss device="/dev/dsp" sink_name=output source_name=input
 #load-module module-oss-mmap device="/dev/dsp" sink_name=output source_name=input
 load-module module-null-sink
 #load-module module-pipe-sink
@@ -37,11 +37,11 @@ load-module module-null-sink
 #add-autoload-source input module-alsa-source source_name=input
 
 # Load several protocols
-load-module module-esound-protocol-tcp
-#load-module module-simple-protocol-tcp
+load-module module-esound-protocol-unix
+#load-module module-esound-protocol-tcp
 load-module module-native-protocol-unix
+#load-module module-simple-protocol-tcp
 #load-module module-cli-protocol-unix
-#load-module module-esound-protocol-unix
 
 # Load the CLI module
 load-module module-cli
@@ -54,10 +54,13 @@ set-default-source input
 
 # Load something to the sample cache
 load-sample x11-bell /usr/share/sounds/KDE_Notify.wav
+load-sample-dir-lazy /usr/share/sounds/*.wav
 
 # Load X11 bell module
 load-module module-x11-bell sample=x11-bell sink=output
 
+# Publish connection data in the X11 root window
+load-module module-x11-publish
+
 #load-module module-pipe-source
 #load-module module-pipe-sink
-
diff --git a/polyp/dumpmodules.h b/polyp/dumpmodules.h
index c56d5abc..fadc571f 100644
--- a/polyp/dumpmodules.h
+++ b/polyp/dumpmodules.h
@@ -24,6 +24,8 @@
 
 #include "daemon-conf.h"
 
+/* Dump all available modules to STDOUT. If argc > 0 print information
+ * about the modules specified in argv[] instead. */
 void pa_dump_modules(struct pa_daemon_conf *c, int argc, char * const argv[]);
 
 #endif
diff --git a/polyp/gcc-printf.h b/polyp/gcc-printf.h
index 224552af..70679df9 100644
--- a/polyp/gcc-printf.h
+++ b/polyp/gcc-printf.h
@@ -1,6 +1,29 @@
 #ifndef foogccprintfhfoo
 #define foogccprintfhfoo
 
+/* $Id$ */
+
+/***
+  This file is part of polypaudio.
+ 
+  polypaudio is free software; you can redistribute it and/or modify
+  it under the terms of the GNU Lesser General Public License as published
+  by the Free Software Foundation; either version 2 of the License,
+  or (at your option) any later version.
+ 
+  polypaudio is distributed in the hope that it will be useful, but
+  WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+  General Public License for more details.
+ 
+  You should have received a copy of the GNU Lesser General Public License
+  along with polypaudio; if not, write to the Free Software
+  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
+  USA.
+***/
+
+/* If we're in GNU C, use some magic for detecting invalid format strings */
+
 #ifdef __GNUC__
 #define PA_GCC_PRINTF_ATTR(a,b) __attribute__ ((format (printf, a, b)))
 #else
diff --git a/polyp/glib-mainloop.c b/polyp/glib-mainloop.c
index aa81f82d..809c0b0f 100644
--- a/polyp/glib-mainloop.c
+++ b/polyp/glib-mainloop.c
@@ -106,6 +106,7 @@ static struct pa_io_event* glib_io_new(struct pa_mainloop_api*m, int fd, enum pa
     return e;
 }
 
+/* The callback GLIB calls whenever an IO condition is met */
 static gboolean io_cb(GIOChannel *source, GIOCondition condition, gpointer data) {
     struct pa_io_event *e = data;
     enum pa_io_event_flags f;
diff --git a/polyp/glib12-mainloop.c b/polyp/glib12-mainloop.c
index 2073c01d..5f037347 100644
--- a/polyp/glib12-mainloop.c
+++ b/polyp/glib12-mainloop.c
@@ -29,6 +29,8 @@
 #include "idxset.h"
 #include "xmalloc.h"
 
+/* A mainloop implementation based on GLIB 1.2 */
+
 struct pa_io_event {
     struct pa_glib_mainloop *mainloop;
     int dead;
diff --git a/polyp/idxset.h b/polyp/idxset.h
index 66689fd4..4c89eea1 100644
--- a/polyp/idxset.h
+++ b/polyp/idxset.h
@@ -24,41 +24,67 @@
 
 #include <inttypes.h>
 
-/* A combination of a hashtable and a dynamic array. Entries are both
- * indexiable through a numeric automaticly generated index and an
- * opaque key. As usual, memory management is the user's job. */
+/* A combination of a set and a dynamic array. Entries are indexable
+ * both through a numeric automatically generated index and the entry's
+ * data pointer. As usual, memory management is the user's job. */
 
+/* A special index value denoting the invalid index. */
 #define PA_IDXSET_INVALID ((uint32_t) -1)
 
+/* Generic implementations for hash and comparison functions. Just
+ * compares the pointer or calculates the hash value directly from the
+ * pointer value. */
 unsigned pa_idxset_trivial_hash_func(const void *p);
 int pa_idxset_trivial_compare_func(const void *a, const void *b);
 
+/* Generic implementations for hash and comparison functions for strings. */
 unsigned pa_idxset_string_hash_func(const void *p);
 int pa_idxset_string_compare_func(const void *a, const void *b);
 
 struct pa_idxset;
 
+/* Instantiate a new idxset with the specified hash and comparison functions */
 struct pa_idxset* pa_idxset_new(unsigned (*hash_func) (const void *p), int (*compare_func) (const void*a, const void*b));
+
+/* Free the idxset. When the idxset is not empty the specified function is called for every entry contained */
 void pa_idxset_free(struct pa_idxset *s, void (*free_func) (void *p, void *userdata), void *userdata);
 
+/* Store a new item in the idxset. The index of the item is returned in *index */
 int pa_idxset_put(struct pa_idxset*s, void *p, uint32_t *index);
 
+/* Get the entry by its index */
 void* pa_idxset_get_by_index(struct pa_idxset*s, uint32_t index);
+
+/* Get the entry by its data. The index is returned in *index */
 void* pa_idxset_get_by_data(struct pa_idxset*s, const void *p, uint32_t *index);
 
+/* Similar to pa_idxset_get_by_index(), but removes the entry from the idxset. */
 void* pa_idxset_remove_by_index(struct pa_idxset*s, uint32_t index);
+
+/* Similar to pa_idxset_get_by_data(), but removes the entry from the idxset */
 void* pa_idxset_remove_by_data(struct pa_idxset*s, const void *p, uint32_t *index);
 
 /* This may be used to iterate through all entries. When called with
    an invalid index value it returns the first entry, otherwise the
    next following. The function is best called with *index =
-   PA_IDXSET_VALID first. */
+   PA_IDXSET_VALID first. It is safe to manipulate the idxset between
+   the calls. It is not guaranteed that all entries have already been
+   returned before the an entry is returned the second time.*/
 void* pa_idxset_rrobin(struct pa_idxset *s, uint32_t *index);
 
-/* Return the oldest entry in the idxset */
+/* Return the oldest entry in the idxset. Fill in its index in *index. */
 void* pa_idxset_first(struct pa_idxset *s, uint32_t *index);
+
+/* Return the entry following the entry indexed by *index.  After the
+ * call *index contains the index of the returned
+ * object. pa_idxset_first() and pa_idxset_next() may be used to
+ * iterate through the set.*/
 void *pa_idxset_next(struct pa_idxset *s, uint32_t *index);
 
+/* Call a function for every item in the set. If the callback function
+   returns -1, the loop is terminated. If *del is set to non-zero that
+   specific item is removed. It is not safe to call any other
+   functions on the idxset while pa_idxset_foreach is executed. */
 int pa_idxset_foreach(struct pa_idxset*s, int (*func)(void *p, uint32_t index, int *del, void*userdata), void *userdata);
 
 unsigned pa_idxset_ncontents(struct pa_idxset*s);
diff --git a/polyp/iochannel.h b/polyp/iochannel.h
index f8efc928..2a1ba370 100644
--- a/polyp/iochannel.h
+++ b/polyp/iochannel.h
@@ -25,10 +25,23 @@
 #include <sys/types.h>
 #include "mainloop-api.h"
 
-/* It is safe to destroy the calling iochannel object from the callback */
+/* A wrapper around UNIX file descriptors for attaching them to the a
+   main event loop. Everytime new data may be read or be written to
+   the channel a callback function is called. It is safe to destroy
+   the calling iochannel object from the callback */
+
+/* When pa_iochannel_is_readable() returns non-zero, the user has to
+ * call this function in a loop until it is no longer set or EOF
+ * reached. Otherwise strange things may happen when an EOF is
+ * reached. */
 
 struct pa_iochannel;
 
+/* Create a new IO channel for the specified file descriptors for
+input resp. output. It is safe to pass the same file descriptor for
+both parameters (in case of full-duplex channels). For a simplex
+channel specify -1 for the other direction. */
+
 struct pa_iochannel* pa_iochannel_new(struct pa_mainloop_api*m, int ifd, int ofd);
 void pa_iochannel_free(struct pa_iochannel*io);
 
@@ -39,11 +52,17 @@ int pa_iochannel_is_readable(struct pa_iochannel*io);
 int pa_iochannel_is_writable(struct pa_iochannel*io);
 int pa_iochannel_is_hungup(struct pa_iochannel*io);
 
+/* Don't close the file descirptors when the io channel is freed. By
+ * default the file descriptors are closed. */
 void pa_iochannel_set_noclose(struct pa_iochannel*io, int b);
 
+/* Set the callback function that is called whenever data becomes available for read or write */
 void pa_iochannel_set_callback(struct pa_iochannel*io, void (*callback)(struct pa_iochannel*io, void *userdata), void *userdata);
 
+/* In case the file descriptor is a socket, return a pretty-printed string in *s which describes the peer connected */
 void pa_iochannel_socket_peer_to_string(struct pa_iochannel*io, char*s, size_t l);
+
+/* Use setsockopt() to tune the recieve and send buffers of TCP sockets */
 int pa_iochannel_socket_set_rcvbuf(struct pa_iochannel*io, size_t l);
 int pa_iochannel_socket_set_sndbuf(struct pa_iochannel*io, size_t l);
 
diff --git a/polyp/ioline.h b/polyp/ioline.h
index 5adc0560..f652dddb 100644
--- a/polyp/ioline.h
+++ b/polyp/ioline.h
@@ -24,6 +24,10 @@
 
 #include "iochannel.h"
 
+/* An ioline wraps an iochannel for line based communication. A
+ * callback function is called whenever a new line has been recieved
+ * from the client */
+
 struct pa_ioline;
 
 struct pa_ioline* pa_ioline_new(struct pa_iochannel *io);
@@ -31,7 +35,10 @@ void pa_ioline_unref(struct pa_ioline *l);
 struct pa_ioline* pa_ioline_ref(struct pa_ioline *l);
 void pa_ioline_close(struct pa_ioline *l);
 
+/* Write a string to the channel */
 void pa_ioline_puts(struct pa_ioline *s, const char *c);
+
+/* Set the callback function that is called for every recieved line */
 void pa_ioline_set_callback(struct pa_ioline*io, void (*callback)(struct pa_ioline*io, const char *s, void *userdata), void *userdata);
 
 #endif
diff --git a/polyp/llist.h b/polyp/llist.h
index c48c5c6e..eb8cd017 100644
--- a/polyp/llist.h
+++ b/polyp/llist.h
@@ -7,33 +7,41 @@
   This file is part of polypaudio.
  
   polypaudio is free software; you can redistribute it and/or modify
-  it under the terms of the GNU Lesser General Public License as published
-  by the Free Software Foundation; either version 2 of the License,
-  or (at your option) any later version.
+  it under the terms of the GNU Lesser General Public License as
+  published by the Free Software Foundation; either version 2 of the
+  License, or (at your option) any later version.
  
   polypaudio is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
   General Public License for more details.
  
-  You should have received a copy of the GNU Lesser General Public License
-  along with polypaudio; if not, write to the Free Software
+  You should have received a copy of the GNU Lesser General Public
+  License along with polypaudio; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
   USA.
 ***/
 
+/* Some macros for maintaining doubly linked lists */
+
+/* The head of the linked list. Use this in the structure that shall
+ * contain the head of the linked list */
 #define PA_LLIST_HEAD(t,name) t *name
 
+/* The pointers in the linked list's items. Use this in the item structure */
 #define PA_LLIST_FIELDS(t) t *next, *prev
 
+/* Initialize the list's head */
 #define PA_LLIST_HEAD_INIT(t,item) do { (item) = NULL; } while(0)
 
+/* Initialize a list item */
 #define PA_LLIST_INIT(t,item) do { \
                                t *_item = (item); \
                                assert(_item); \
                                _item->prev = _item->next = NULL; \
                                } while(0)
 
+/* Prepend an item to the list */
 #define PA_LLIST_PREPEND(t,head,item) do { \
                                         t **_head = &(head), *_item = (item); \
                                         assert(_item); \
@@ -43,6 +51,7 @@
                                         *_head = _item; \
                                         } while (0)
 
+/* Remove an item from the list */
 #define PA_LLIST_REMOVE(t,head,item) do { \
                                     t **_head = &(head), *_item = (item); \
                                     assert(_item); \
diff --git a/polyp/log.c b/polyp/log.c
index 516cd2b0..dc41dcd2 100644
--- a/polyp/log.c
+++ b/polyp/log.c
@@ -1,3 +1,28 @@
+/* $Id$ */
+
+/***
+  This file is part of polypaudio.
+ 
+  polypaudio is free software; you can redistribute it and/or modify
+  it under the terms of the GNU Lesser General Public License as
+  published by the Free Software Foundation; either version 2 of the
+  License, or (at your option) any later version.
+ 
+  polypaudio is distributed in the hope that it will be useful, but
+  WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+  General Public License for more details.
+ 
+  You should have received a copy of the GNU Lesser General Public
+  License along with polypaudio; if not, write to the Free Software
+  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
+  USA.
+***/
+
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+#endif
+
 #include <assert.h>
 #include <stdarg.h>
 #include <syslog.h>
@@ -43,6 +68,8 @@ void pa_log(const char *format, ...) {
             user_log_func(t);
 	    pa_xfree(t);
         }
+        case PA_LOG_NULL:
+            break;
     }
 
     va_end(ap);
diff --git a/polyp/log.h b/polyp/log.h
index 46a86491..cf55386c 100644
--- a/polyp/log.h
+++ b/polyp/log.h
@@ -1,17 +1,46 @@
 #ifndef foologhfoo
 #define foologhfoo
 
+/* $Id$ */
+
+/***
+  This file is part of polypaudio.
+ 
+  polypaudio is free software; you can redistribute it and/or modify
+  it under the terms of the GNU Lesser General Public License as published
+  by the Free Software Foundation; either version 2 of the License,
+  or (at your option) any later version.
+ 
+  polypaudio is distributed in the hope that it will be useful, but
+  WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+  General Public License for more details.
+ 
+  You should have received a copy of the GNU Lesser General Public License
+  along with polypaudio; if not, write to the Free Software
+  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
+  USA.
+***/
+
 #include "gcc-printf.h"
 
+/* A simple logging subsystem */
+
+/* Where to log to */
 enum pa_log_target {
+    PA_LOG_STDERR,  /* default */
     PA_LOG_SYSLOG,
-    PA_LOG_STDERR,
-    PA_LOG_USER
+    PA_LOG_USER,    /* to user specified function */
+    PA_LOG_NULL     /* to /dev/null */
 };
 
+/* Set an identifcation for the current daemon. Used when logging to syslog. */
 void pa_log_set_ident(const char *p);
+
+/* Set another log target. If t is PA_LOG_USER you may specify a function that is called every log string */
 void pa_log_set_target(enum pa_log_target t, void (*func)(const char*s));
-                       
+
+/* Do a log line */
 void pa_log(const char *format, ...)  PA_GCC_PRINTF_ATTR(1,2);
 
 #endif
diff --git a/polyp/mcalign-test.c b/polyp/mcalign-test.c
index ab1f9aed..f8af4f9f 100644
--- a/polyp/mcalign-test.c
+++ b/polyp/mcalign-test.c
@@ -1,3 +1,28 @@
+/* $Id$ */
+
+/***
+  This file is part of polypaudio.
+ 
+  polypaudio is free software; you can redistribute it and/or modify
+  it under the terms of the GNU Lesser General Public License as
+  published by the Free Software Foundation; either version 2.1 of the
+  License, or (at your option) any later version.
+ 
+  polypaudio is distributed in the hope that it will be useful, but
+  WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+  Lesser General Public License for more details.
+ 
+  You should have received a copy of the GNU Lesser General Public
+  License along with polypaudio; if not, write to the Free Software
+  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
+  USA.
+***/
+
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+#endif
+
 #include <assert.h>
 #include <unistd.h>
 #include <sys/types.h>
@@ -9,6 +34,8 @@
 #include "util.h"
 #include "mcalign.h"
 
+/* A simple program for testing pa_mcalign */
+
 int main(int argc, char *argv[]) {
     struct pa_mcalign *a = pa_mcalign_new(11, NULL);
     struct pa_memchunk c;
diff --git a/polyp/memblock.h b/polyp/memblock.h
index 91612ac9..8555954c 100644
--- a/polyp/memblock.h
+++ b/polyp/memblock.h
@@ -25,30 +25,54 @@
 #include <sys/types.h>
 #include <inttypes.h>
 
-enum pa_memblock_type { PA_MEMBLOCK_FIXED, PA_MEMBLOCK_APPENDED, PA_MEMBLOCK_DYNAMIC, PA_MEMBLOCK_USER };
+/* A pa_memblock is a reference counted memory block. Polypaudio
+ * passed references to pa_memblocks around instead of copying
+ * data. See pa_memchunk for a structure that describes parts of
+ * memory blocks. */
 
+/* The type of memory this block points to */
+enum pa_memblock_type {
+    PA_MEMBLOCK_FIXED,     /* data is a pointer to fixed memory that needs not to be freed */
+    PA_MEMBLOCK_APPENDED,  /* The most common kind: the data is appended to the memory block */ 
+    PA_MEMBLOCK_DYNAMIC,   /* data is a pointer to some memory allocated with pa_xmalloc() */
+    PA_MEMBLOCK_USER       /* User supplied memory, to be freed with free_cb */
+};
+
+/* A structure of keeping memory block statistics */
 struct pa_memblock_stat;
 
 struct pa_memblock {
     enum pa_memblock_type type;
-    unsigned ref;
-    int read_only;
+    unsigned ref;  /* the reference counter */
+    int read_only; /* boolean */
     size_t length;
     void *data;
-    void (*free_cb)(void *p);
+    void (*free_cb)(void *p);  /* If type == PA_MEMBLOCK_USER this points to a function for freeing this memory block */
     struct pa_memblock_stat *stat;
 };
 
+/* Allocate a new memory block of type PA_MEMBLOCK_APPENDED */
 struct pa_memblock *pa_memblock_new(size_t length, struct pa_memblock_stat*s);
+
+/* Allocate a new memory block of type PA_MEMBLOCK_DYNAMIC. The pointer data is to be maintained be the memory block */
 struct pa_memblock *pa_memblock_new_dynamic(void *data, size_t length, struct pa_memblock_stat*s);
+
+/* Allocate a new memory block of type PA_MEMBLOCK_FIXED */
 struct pa_memblock *pa_memblock_new_fixed(void *data, size_t length, int read_only, struct pa_memblock_stat*s);
+
+/* Allocate a new memory block of type PA_MEMBLOCK_USER */
 struct pa_memblock *pa_memblock_new_user(void *data, size_t length, void (*free_cb)(void *p), int read_only, struct pa_memblock_stat*s);
 
 void pa_memblock_unref(struct pa_memblock*b);
 struct pa_memblock* pa_memblock_ref(struct pa_memblock*b);
 
+/* This special unref function has to be called by the owner of the
+memory of a static memory block when he wants to release all
+references to the memory. This causes the memory to be copied and
+converted into a PA_MEMBLOCK_DYNAMIC type memory block */
 void pa_memblock_unref_fixed(struct pa_memblock*b);
 
+/* Matinatins statistics about memory blocks */
 struct pa_memblock_stat {
     int ref;
     unsigned total;
diff --git a/polyp/memblockq.h b/polyp/memblockq.h
index 95e5c533..2c762bf4 100644
--- a/polyp/memblockq.h
+++ b/polyp/memblockq.h
@@ -7,17 +7,17 @@
   This file is part of polypaudio.
  
   polypaudio is free software; you can redistribute it and/or modify
-  it under the terms of the GNU Lesser General Public License as published
-  by the Free Software Foundation; either version 2 of the License,
-  or (at your option) any later version.
+  it under the terms of the GNU Lesser General Public License as
+  published by the Free Software Foundation; either version 2 of the
+  License, or (at your option) any later version.
  
   polypaudio is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
   General Public License for more details.
  
-  You should have received a copy of the GNU Lesser General Public License
-  along with polypaudio; if not, write to the Free Software
+  You should have received a copy of the GNU Lesser General Public
+  License along with polypaudio; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
   USA.
 ***/
@@ -27,6 +27,12 @@
 #include "memblock.h"
 #include "memchunk.h"
 
+/* A memblockq is a queue of pa_memchunks (yepp, the name is not
+ * perfect). It is similar to the ring buffers used by most other
+ * audio software. In contrast to a ring buffer this memblockq data
+ * type doesn't need to copy any data around, it just maintains
+ * references to reference counted memory blocks. */
+
 struct pa_memblockq;
 
 /* Parameters:
diff --git a/polyp/modargs.c b/polyp/modargs.c
index 01a694cf..406f610f 100644
--- a/polyp/modargs.c
+++ b/polyp/modargs.c
@@ -44,7 +44,7 @@ struct entry {
     char *key, *value;
 };
 
-static int add_key_value(struct pa_hashmap *map, char *key, char *value, const char* const* valid_keys) {
+static int add_key_value(struct pa_hashmap *map, char *key, char *value, const char* const valid_keys[]) {
     struct entry *e;
     assert(map && key && value);
 
diff --git a/polyp/modargs.h b/polyp/modargs.h
index 53753ba7..07db6ae5 100644
--- a/polyp/modargs.h
+++ b/polyp/modargs.h
@@ -28,14 +28,22 @@
 
 struct pa_modargs;
 
-struct pa_modargs *pa_modargs_new(const char *args, const char* const* keys);
+/* A generic parser for module arguments */
+
+/* Parse the string args. The NULL-terminated array keys contains all valid arguments. */
+struct pa_modargs *pa_modargs_new(const char *args, const char* const keys[]);
 void pa_modargs_free(struct pa_modargs*ma);
 
+/* Return the module argument for the specified name as a string. If
+ * the argument was not specified, return def instead.*/
 const char *pa_modargs_get_value(struct pa_modargs *ma, const char *key, const char *def);
+
+/* Return a module argument as unsigned 32bit value in *value */
 int pa_modargs_get_value_u32(struct pa_modargs *ma, const char *key, uint32_t *value);
 int pa_modargs_get_value_s32(struct pa_modargs *ma, const char *key, int32_t *value);
 int pa_modargs_get_value_boolean(struct pa_modargs *ma, const char *key, int *value);
 
+/* Return sample spec data from the three arguments "rate", "format" and "channels" */
 int pa_modargs_get_sample_spec(struct pa_modargs *ma, struct pa_sample_spec *ss);
 
 #endif
diff --git a/polyp/modinfo.c b/polyp/modinfo.c
index a1328be6..a96bb17e 100644
--- a/polyp/modinfo.c
+++ b/polyp/modinfo.c
@@ -4,17 +4,17 @@
   This file is part of polypaudio.
  
   polypaudio is free software; you can redistribute it and/or modify
-  it under the terms of the GNU Lesser General Public License as published
-  by the Free Software Foundation; either version 2 of the License,
-  or (at your option) any later version.
+  it under the terms of the GNU Lesser General Public License as
+  published by the Free Software Foundation; either version 2 of the
+  License, or (at your option) any later version.
  
   polypaudio is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
   General Public License for more details.
  
-  You should have received a copy of the GNU Lesser General Public License
-  along with polypaudio; if not, write to the Free Software
+  You should have received a copy of the GNU Lesser General Public
+  License along with polypaudio; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
   USA.
 ***/
diff --git a/polyp/modinfo.h b/polyp/modinfo.h
index d6f7c6de..9da9dc4e 100644
--- a/polyp/modinfo.h
+++ b/polyp/modinfo.h
@@ -22,6 +22,8 @@
   USA.
 ***/
 
+/* Some functions for reading module meta data from Polypaudio modules */
+
 struct pa_modinfo {
     char *author;
     char *description;
@@ -29,9 +31,13 @@ struct pa_modinfo {
     char *version;
 };
 
+/* Read meta data from an libtool handle */
 struct pa_modinfo *pa_modinfo_get_by_handle(lt_dlhandle dl);
+
+/* Read meta data from a module file */
 struct pa_modinfo *pa_modinfo_get_by_name(const char *name);
 
+/* Free meta data */
 void pa_modinfo_free(struct pa_modinfo *i);
 
 #endif
diff --git a/polyp/module-tunnel.c b/polyp/module-tunnel.c
index 2b36ce27..39aaab57 100644
--- a/polyp/module-tunnel.c
+++ b/polyp/module-tunnel.c
@@ -554,7 +554,7 @@ static int load_key(struct userdata *u, const char*fn) {
     if (!fn)
         fn = PA_NATIVE_COOKIE_FILE;
 
-    if (pa_authkey_load_from_home(fn, u->auth_cookie, sizeof(u->auth_cookie)) < 0)
+    if (pa_authkey_load_auto(fn, u->auth_cookie, sizeof(u->auth_cookie)) < 0)
         return -1;
 
     pa_log(__FILE__": loading cookie from disk.\n");
diff --git a/polyp/module-x11-publish.c b/polyp/module-x11-publish.c
index acf37759..598fe5b5 100644
--- a/polyp/module-x11-publish.c
+++ b/polyp/module-x11-publish.c
@@ -86,7 +86,7 @@ static int load_key(struct userdata *u, const char*fn) {
     if (!fn)
         fn = PA_NATIVE_COOKIE_FILE;
 
-    if (pa_authkey_load_from_home(fn, u->auth_cookie, sizeof(u->auth_cookie)) < 0)
+    if (pa_authkey_load_auto(fn, u->auth_cookie, sizeof(u->auth_cookie)) < 0)
         return -1;
 
     pa_log(__FILE__": loading cookie from disk.\n");
diff --git a/polyp/protocol-native.c b/polyp/protocol-native.c
index e4831e4d..84d4efe8 100644
--- a/polyp/protocol-native.c
+++ b/polyp/protocol-native.c
@@ -2066,7 +2066,7 @@ static int load_key(struct pa_protocol_native*p, const char*fn) {
     if (!fn)
         fn = PA_NATIVE_COOKIE_FILE;
 
-    if (pa_authkey_load_from_home(fn, p->auth_cookie, sizeof(p->auth_cookie)) < 0)
+    if (pa_authkey_load_auto(fn, p->auth_cookie, sizeof(p->auth_cookie)) < 0)
         return -1;
 
     pa_log(__FILE__": loading cookie from disk.\n");