add more missing documentation

diff --git a/aac_afh.c b/aac_afh.c
index a2347065613983238c9e2cb5803b7398607656bd..d5ec442b9bdce9b6507ea9d3c1559d2eee73da22 100644 (file)
--- a/aac_afh.c
+++ b/aac_afh.c
@@ -31,19 +31,19 @@
 #include "aac.h"
 #include "fd.h"
 
 #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;
 #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;
 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)
 {
 
 static void aac_close_audio_file(void)
 {


@@ -116,7 +116,7 @@ static int read_chunk_table(size_t skip)
        return 1;
 }
 
        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;
 {
        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 edbe2637521f59bc1f7403bf06e110a7a85d15df..9ed120120de7af297a0760ad237135ae535a72af 100644 (file)
--- 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
  *
  *     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)
 
 /** the output buffer size */
 #define AAC_OUTBUF_SIZE (32 * 1024)
 

+/** give up decoding after that many errors */

 #define MAX_ERRORS 20
 
 /**
 #define MAX_ERRORS 20
 
 /**


@@ -42,13 +43,22 @@
  * \sa filter, filter_node
  */
 struct private_aacdec_data {
  * \sa filter, filter_node
  */
 struct private_aacdec_data {

+       /** the return value of aac_open */

        NeAACDecHandle handle;
        NeAACDecHandle handle;

+       /** info about the currently decoded frame */

        NeAACDecFrameInfo frame_info;
        NeAACDecFrameInfo frame_info;

-
+       /** whether this instance of the aac decoder is already initialized */

        int initialized;
        int initialized;

+       /**
+        * return value of aac_find_esds(). Used to call the right aacdec
+        * init function
+        */

        int decoder_length;
        int decoder_length;

+       /** number of times the decoder returned an error */

        unsigned error_count;
        unsigned error_count;

+       /** number of bytes already consumed from the imput stream */

        size_t consumed_total;
        size_t consumed_total;

+       /** return value of aac_find_entry_point */

        size_t entry;
 };
 
        size_t entry;
 };
 


@@ -179,6 +189,8 @@ static void aacdec_close(struct filter_node *fn)
 /**
  * the init function of the aacdec filter
  *
 /**
  * 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)
  * \sa filter::init
  */
 void aacdec_init(struct filter *f)

diff --git a/alsa_write.c b/alsa_write.c
index 8bac583a92306b097f0982447e62cdfc946d51d1..526cffc1aeaede74968d0f5e1ec89057dd8933b1 100644 (file)
--- 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
  *
  *     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 216afa2f11aeebc132d23ad2a96664daf9e384cd..3cc5b0bd7b4d2e385a902f1b241abe779d8207fa 100644 (file)
--- a/audioc.c
+++ b/audioc.c
@@ -27,8 +27,8 @@
 
 INIT_AUDIOC_ERRLISTS;
 
 
 INIT_AUDIOC_ERRLISTS;
 

+/** the gengetopt structure containing command line args */

 struct audioc_args_info conf;
 struct audioc_args_info conf;

-char *tmpfifo;

 
 INIT_STDERR_LOGGING(conf.loglevel_arg);
 
 
 INIT_STDERR_LOGGING(conf.loglevel_arg);
 


@@ -59,6 +59,21 @@ static char *configfile_exists(void)
        return NULL;
 }
 
        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;
 int main(int argc, char *argv[])
 {
        struct sockaddr_un unix_addr;

diff --git a/audiod_command.c b/audiod_command.c
index 349480ff1f34f5a9bfebe57f26ddad6f0aef93ce..d1e36490822c216da260003457a1fecfc3c02941 100644 (file)
--- a/audiod_command.c
+++ b/audiod_command.c
@@ -477,7 +477,9 @@ out:
        }
        return ret;
 }
        }
        return ret;
 }

-
+/**
+ * send the current audiod status to all connected stat clients
+ */

 void audiod_status_dump(void)
 {
        struct timeval *t = wstime();
 void audiod_status_dump(void)
 {
        struct timeval *t = wstime();

diff --git a/client.c b/client.c
index 12812c9f79ecd0a4b5b88707c88572f709ea3fdd..9565102709f53446e7ebf5e978fd9bae733f4dc0 100644 (file)
--- a/client.c
+++ b/client.c
@@ -63,8 +63,19 @@ static void client_event_handler(struct task *t)
        register_task(&sot.task);
 }
 
        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[])
 {
  */
 int main(int argc, char *argv[])
 {

diff --git a/client.h b/client.h
index ca50ee05da1c4d0fde86d93f9222ad7d37c0a704..a4d2fe63f473aeb96432dcee1d9b362b77f95f45 100644 (file)
--- a/client.h
+++ b/client.h
@@ -44,6 +44,7 @@ enum {
        CL_RECEIVING,
 };
 
        CL_RECEIVING,
 };
 

+/** size of the receiving buffer */

 #define CLIENT_BUFSIZE 8192
 
 /**
 #define CLIENT_BUFSIZE 8192
 
 /**

diff --git a/crypt.c b/crypt.c
index cf1cabecbad80cdca6d69cf2bbc2165427a84ed8..c1a2d4e5c8ccd67007ab96bf751ef9d35eaf465b 100644 (file)
--- 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
  *
  *     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;
 }
 
        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);
 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 128d45b74c271aaeca10abacb5ef50ef197b55a6..c335e768a0b66182d171188e757d6475acb055cd 100644 (file)
--- a/dccp_send.c
+++ b/dccp_send.c
@@ -120,7 +120,8 @@ static void dccp_shutdown_client(struct dccp_client *dc)
        free(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)
 {
 
 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) {
        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;
                        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 45ade8d3697f86001c900ea3c7fe6541a44d48f1..321d763c1f9cb5b743db1cbbbf3f95f2f68774cb 100644 (file)
--- 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
  *
  *     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);
 
 
 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);
 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
 
 /**
  * the structure associated with a paraslash filter


@@ -340,15 +338,13 @@ DECLARE_EXTERN_FILTER_INIT(oggdec);
 #else
 #define OGGDEC_FILTER
 #endif
 #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 } };
        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 70c3d39554a8b2414b37a515a3977d428b6173b2..8a41beda94acc29f3f9650d6d0afee7d265f6095 100644 (file)
--- 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
  *
  *     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
  *
 /**
  * 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
  * 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 2542cdc113bb6f19c63d3ce36eacaf274ba03719..112053b65791fabaed869dc7f04ca700eb9c3cb1 100644 (file)
--- a/http.h
+++ b/http.h
@@ -1,3 +1,7 @@
 /** \file http.h macros used by http_send and http_recv */
 /** \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"
 #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/"
 #define HTTP_GET_MSG "GET / HTTP/"

diff --git a/http_recv.c b/http_recv.c
index c418af129a0560fdb09e2aa2cf32e1c7b68146ed..65898338cd30b0b2ba4a503a913c44a0fca2d449 100644 (file)
--- 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
  *
  *     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
  *
  *
  * 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.
  * 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
  *
  * 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.
  *
  * 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;
 };
  */
        int fd;
 };

diff --git a/ipc.h b/ipc.h
index 733cba6d83fd4b01e13ccf720013f56f9c2a3b3c..c4dd1d7d620ca17d40371d712aa91ab764176c8c 100644 (file)
--- a/ipc.h
+++ b/ipc.h
@@ -1,5 +1,6 @@
 /** \file ipc.h inter process communication and shared memory routines */
 
 /** \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);
 enum shm_attach_mode {ATTACH_RO, ATTACH_RW};
 
 int mutex_new(void);

diff --git a/list.h b/list.h
index 4b946c7c24e037925c924b76df76c23c0a109196..ba6211ba191395e40fd63d526ab9ddacc2b7f697 100644 (file)
--- a/list.h
+++ b/list.h
@@ -13,12 +13,15 @@
        const typeof( ((type *)0)->member ) *__mptr = (ptr);    \
        (type *)( (char *)__mptr - offsetof(type,member) );})
 
        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)
  */
 #define LIST_POISON1  ((void *) 0x00100100)

+/** Non-null pointer, used for poisoning the \a prev pointer of struct
+ * list_head
+ */

 #define LIST_POISON2  ((void *) 0x00200200)
 
 /**
 #define LIST_POISON2  ((void *) 0x00200200)
 
 /**

diff --git a/mp3_afh.c b/mp3_afh.c
index 530f36ff1a91921cf32ea2dbe9e1dd39e73c80b1..a63e2e861b27e0f5ae0582037dcc862e804ca0f0 100644 (file)
--- 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};
 }
 
 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;
 void mp3_init(struct audio_format_handler *p)
 {
        af = p;

diff --git a/mp3dec.c b/mp3dec.c
index 93181ef1421c75879b26156f5ecdbb8103b71f3e..401a03c582f418d6590a7fc27007becdfab6d73d 100644 (file)
--- 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
  *
  *     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
  *
 /**
  * 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)
  * \sa filter::init
  */
 void mp3dec_init(struct filter *f)

diff --git a/net.h b/net.h
index 4a89778b87495136ca046813c3af274201097b19..5ff53987af6591e6192ae034fe6270fbb29df01b 100644 (file)
--- 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
  *
  *     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
 
 #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);
 
 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 14163fe61ae643f673113c6ca435d003315d9110..d295f2d31ba1a482f7c67a0d0663a1efc5c82867 100644 (file)
--- a/ogg_afh.c
+++ b/ogg_afh.c
@@ -29,7 +29,7 @@
 #include "error.h"
 #include "string.h"
 
 #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;
 
 #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);
 err1:
        ogg_sync_destroy(sync_in);
        vorbis_info_clear(&vi);

-        vorbis_comment_clear(&vc);
+       vorbis_comment_clear(&vc);

        return ret;
 }
 
        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];
        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;
 }
 
        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);
 {
        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};
 }
 
 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;
 void ogg_init(struct audio_format_handler *p)
 {
        af = p;

diff --git a/osx_write.c b/osx_write.c
index 95a84f2a548cbe153cff31f1ae831ecb1cebae6a..4ba173a70200ebd269e2b3602e6b9d609be9df8b 100644 (file)
--- a/osx_write.c
+++ b/osx_write.c
@@ -44,7 +44,7 @@ struct osx_buffer {
        float *buffer;
        /** the size of this buffer */
        long size;
        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;
        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;
        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;
        struct osx_buffer *to;
        /** sample rate of the current audio stream */
        unsigned samplerate;

diff --git a/recv.h b/recv.h
index 7fb45286cd61b93fb88f3ac2a0936cbfea5a6dfd..573dccc9dfcb112e737d81a410973ea8abd0a326 100644 (file)
--- 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
  *
  *     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;
        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;
        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
 
 #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 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}};
 
 #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 0393d7641abbae85e9645e260417551d4e7fea8b..8f8f63697714904c1d6c871c1e8e3df197e0298e 100644 (file)
--- 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
  *
  *     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;
 }
 
        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;
 void *check_receiver_arg(char *ra, int *receiver_num)
 {
        int j;

diff --git a/sched.c b/sched.c
index e122903e8e46823ed2a4b987cf3264782ca3040e..2c49050cb6408085c02951b170d49d34d11169b2 100644 (file)
--- 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
  *
  *     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
  *
 /**
  * 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.
  * 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 f67efa6e233e6bc1bcdd2716f29b94027f3a1b41..89f901f4d8e13a5bc73100945dc3cffa1b81091f 100644 (file)
--- 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
 
 /** 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;
 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;
 struct server_args_info conf;

+
+/** the file containing user information (public key, permissions) */

 char *user_list_file = NULL;
 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 *);
 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[])
 {
  */
 int main(int argc, char *argv[])
 {

diff --git a/server.h b/server.h
index dd5184f4ca5beb3d6fbdeeaec6f2000a5409a80b..9dee3e3495ae11f24412b2ab19ded2313ed2c16f 100644 (file)
--- 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;
        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;
        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 f853d4ccdaec0301cb042e002c4d8172850f2774..9860dd785779641df897eb9177fbd057423f3a25 100644 (file)
--- 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
  *
  *     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 caf432d9748ca3b5e293657359a17ca98f5b8559..dc51119267c0d18c870240898588a9fdcf0f1637 100644 (file)
--- 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
  *
  *     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
  *
 /**
  * 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
  * \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)
 {
  */
 int stat_client_add(int fd, long unsigned mask)
 {

diff --git a/user_list.c b/user_list.c
index c3b10b1e1d8ca8a915b92a7b4f3080500233210a..b7d739c130fc08d5d69c159be3c46d927f894df2 100644 (file)
--- a/user_list.c
+++ b/user_list.c
@@ -93,6 +93,14 @@ out:
        exit(EXIT_FAILURE);
 }
 
        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;
 void init_user_list(char *user_list_file)
 {
        struct user *u, *tmp;

diff --git a/vss.c b/vss.c
index f9e2d6c2aef98a29d1bc0aecc1680b22851e7e00..4a395593f3aa1a6a5038b3d3c23330c6b0ea5610 100644 (file)
--- a/vss.c
+++ b/vss.c
@@ -82,6 +82,8 @@ static struct audio_format_handler afl[] = {
                .name = NULL,
        }
 };
                .name = NULL,
        }
 };

+
+/** iterate over each supported audio format */

 #define FOR_EACH_AUDIO_FORMAT(i) for (i = 0; afl[i].name; i++)
 
 /**
 #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);
 }
                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;
 const char *supported_audio_formats(void)
 {
        return SUPPORTED_AUDIO_FORMATS;

diff --git a/vss.h b/vss.h
index 545647b7fda1806b042fb4d9dcad29acbe762197..0234296fd599569c44738929987a913bf050a8bb 100644 (file)
--- 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);
 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
 #define VSS_NOMORE 1

+/** skip remaining part of current audio file */

 #define VSS_NEXT 2
 #define VSS_NEXT 2

+/** a reposition request was sent by a client */

 #define VSS_REPOS 4
 #define VSS_REPOS 4

+/** currently playing */

 #define VSS_PLAYING 8
 #define VSS_PLAYING 8

+/** a client requested to change the audio file selector */

 #define VSS_CHANGE 16
 #define VSS_CHANGE 16

diff --git a/write.c b/write.c
index 683a91b0a78c6f93d19dae229a3fbf510a0fb2e8..3671633b2d3032d5041693f15eaa558df085acdc 100644 (file)
--- a/write.c
+++ b/write.c
@@ -216,9 +216,13 @@ static void cwt_event_handler(struct task *t)
 /**
  * para_write's main function
  *
 /**
  * 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.
  *
  * 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[])
 {
  */
 int main(int argc, char *argv[])
 {

diff --git a/write.h b/write.h
index 9f23663413603d67b7b147763116dc77f2bd210d..52d6f5af0c65a057ba528fb1c9c07bfb1943d41a 100644 (file)
--- a/write.h
+++ b/write.h
@@ -80,7 +80,7 @@ struct writer {
         * on errors.
         */
        int (*pre_select)(struct sched *s, struct writer_node *wn);
         * 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
         * 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 b1ab00cfa97ca9c991396a76a4fc4964eb169232..ac92bc1a1740d1eeefa50551d03744a6018fce41 100644 (file)
--- a/write_common.c
+++ b/write_common.c
@@ -25,7 +25,10 @@
 #include "write.h"
 #include "error.h"
 
 #include "write.h"
 #include "error.h"
 

+/** the array containing the names of all supported writers */

 const char *writer_names[] ={WRITER_NAMES};
 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)
 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;
 int wng_open(struct writer_node_group *g)
 {
        int i, ret = 1;


@@ -108,12 +121,25 @@ err_out:
        return ret;
 }
 
        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;
 }
 
 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;
 void wng_close(struct writer_node_group *g)
 {
        int i;


@@ -129,6 +155,13 @@ void wng_close(struct writer_node_group *g)
        free(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));
 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;
 }
 
        return g;
 }
 

+/**
+ * call the init function of each supported paraslash writer
+ */

 void init_supported_writers(void)
 {
        int i;
 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]);
 }
        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;
 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;
 }
 
        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);
 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 cdc2b66c802c2de37379701c0422dfc165dd4dd0..ee162641303df2ce99eee1b86883096a18ee921d 100644 (file)
--- 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
  *
  *     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 */
 
 
 /** \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);
 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);
 struct writer_node_group *setup_default_wng(void);