add more missing documentation
authorAndre Noll <maan@systemlinux.org>
Sat, 10 Feb 2007 18:54:26 +0000 (19:54 +0100)
committerAndre Noll <maan@systemlinux.org>
Sat, 10 Feb 2007 18:54:26 +0000 (19:54 +0100)
34 files changed:
aac_afh.c
aacdec.c
alsa_write.c
audioc.c
audiod_command.c
client.c
client.h
crypt.c
dccp_send.c
filter.h
filter_chain.c
http.h
http_recv.c
ipc.h
list.h
mp3_afh.c
mp3dec.c
net.h
ogg_afh.c
osx_write.c
recv.h
recv_common.c
sched.c
server.c
server.h
signal.h
stat.c
user_list.c
vss.c
vss.h
write.c
write.h
write_common.c
write_common.h

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