Merge branch 't/doc'

diff --git a/NEWS b/NEWS
index 4863abe4ddf4db3403067c0c8bd1d329020950e6..dfe779eed74299064a1f0648b364781244a2ccda 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -2,6 +2,7 @@
 0.4.11 (to be announced "mutual diversity")
 -------------------------------------------
 
+       - Documentation improvements.
 ------------------------------------------
 0.4.10 (2012-03-30) "heterogeneous vacuum"
 ------------------------------------------

diff --git a/audiod.c b/audiod.c
index d7765e21c4224d8ff2419f45521effb62cd50492..8e117e9277e7480cb92bd3e33ff9fe5fbd925b0f 100644 (file)
--- a/audiod.c
+++ b/audiod.c
@@ -77,6 +77,12 @@ enum vss_status_flags {
        VSS_STATUS_FLAG_PLAYING = 2,
 };
 
+/**
+ * The scheduler instance of para_audiod.
+ *
+ * This is needed also in audiod_command.c (for the tasks command), so it can
+ * not be made static.
+ */
 struct sched sched = {.max_fileno = 0};
 
 /**

diff --git a/bitstream.c b/bitstream.c
index 1139edc0d01dfe3668906f747809e0bfb055c18e..ddad67bb177211b3909f88d3be9dcb3d5c381238 100644 (file)
--- a/bitstream.c
+++ b/bitstream.c
@@ -27,6 +27,7 @@
 #include "wma.h"
 #include "bitstream.h"
 
+/** Read an 8, 16, or 32 bit entity from a VLC table. */
 #define GET_DATA(v, table, i, size) \
 {\
        const uint8_t *ptr = (const uint8_t *)table + i * size; \
@@ -160,6 +161,14 @@ void init_vlc(struct vlc *vlc, int nb_bits, int nb_codes, const void *bits,
        build_table(vlc, nb_bits, nb_codes, bits, codes, codes_size, 0, 0);
 }
 
+/**
+ * Deallocate all resources of a VLC table.
+ *
+ * \param vlc Pointer to an initialized vlc structure.
+ *
+ * The table given by \a vlc must have been initialized earlier via \ref
+ * init_vlc().
+ */
 void free_vlc(struct vlc *vlc)
 {
        freep(&vlc->table);

diff --git a/daemon.c b/daemon.c
index c47aa954fd8a1bfc94cd3a3c379500ddc8a22a93..7f71017540455d716574ce831cf6b02773b5e71a 100644 (file)
--- a/daemon.c
+++ b/daemon.c
@@ -65,8 +65,6 @@ void daemon_set_default_log_colors(void)
  * \param arg The loglevel/color specifier.
  *
  * \a arg must be of the form "ll:[fg [bg]] [attr]".
- *
- * \return 1 On success, -1 on errors.
  */
 void daemon_set_log_color_or_die(char const *arg)
 {

diff --git a/ggo.h b/ggo.h
index d1105ef893716ccddfcf7e5e821d343061fb0d58..936fb1079ba07e5bd9cb36ff38b6c6afe242be53 100644 (file)
--- a/ggo.h
+++ b/ggo.h
@@ -7,7 +7,7 @@
 /** \file ggo.h Functions and structures for help text handling. */
 
 /**
- * Used by exexutables that can not use gengetopt's generated help function.
+ * Used by executables that can not use gengetopt's generated help function.
  */
 struct ggo_help {
        /** The lines of the short help text. */

diff --git a/para.h b/para.h
index 3b9559e1beb93062c7cd7cb1cd0daace402b85ae..0a14b99a51f0096e979983c9954f9617ea669097 100644 (file)
--- a/para.h
+++ b/para.h
@@ -71,6 +71,11 @@ extern __printf_2_3 void (*para_log)(int, const char*, ...);
                vfprintf(stderr, fmt, argp); \
                va_end(argp); \
        }
+/**
+ * Define the standard log function and activate it.
+ *
+ * \param loglevel_barrier See \ref DEFINE_STDERR_LOGGER.
+ */
 #define INIT_STDERR_LOGGING(loglevel_barrier) \
        DEFINE_STDERR_LOGGER(stderr_log, loglevel_barrier); \
        __printf_2_3 void (*para_log)(int, const char*, ...) = stderr_log;

diff --git a/recv.h b/recv.h
index ef2a596bacf9c1d59d8d616577c8f7cf5e83f614..c69520e402905524ebcb120bc44221f371d29371 100644 (file)
--- a/recv.h
+++ b/recv.h
@@ -108,9 +108,9 @@ struct receiver {
         * Evaluate the result from select().
         *
         * This hook gets called after the call to select(). It should check
-        * all file descriptors which were added to any of the the fd sets
-        * during the previous call to pre_select. According to the result, it
-        * may then use any non-blocking I/O to establish a connection or to
+        * all file descriptors which were added to any of the fd sets during
+        * the previous call to pre_select. According to the result, it may
+        * then use any non-blocking I/O to establish a connection or to
         * receive the audio data.
         *
         * \sa select(2), struct receiver.

diff --git a/sched.c b/sched.c
index 74f6a1b8a5effa6e13996771f4492fdee47d4bc0..2b54ce194fae897842ac94b39ff597828c8de8c4 100644 (file)
--- a/sched.c
+++ b/sched.c
@@ -192,6 +192,8 @@ void register_task(struct sched *s, struct task *t)
 /**
  * Unregister all tasks.
  *
+ * \param s The scheduler instance to shut down.
+ *
  * This will cause \a schedule() to return immediately because both the
  * \a pre_select_list and the \a post_select_list are empty. This function
  * must be called from the post_select (rather than the pre_select) method.
@@ -213,6 +215,8 @@ void sched_shutdown(struct sched *s)
 /**
  * Get the list of all registered tasks.
  *
+ * \param s The scheduler instance to get the task list from.
+ *
  * \return The task list.
  *
  * Each entry of the list contains an identifier which is simply a hex number.

diff --git a/server.c b/server.c
index d3a9a5ae63eecdc202a9261568b6ccc21785377e..8e8cb5fdcdd31e012137a83a4661e2728ac345e4 100644 (file)
--- a/server.c
+++ b/server.c
@@ -17,7 +17,8 @@
  *       \ref audioc.c, \ref afh.c
  *     - Server: \ref server_command, \ref sender,
  *     - Audio file selector: \ref audio_format_handler, \ref afs_table,
- *     - Client: \ref receiver, \ref receiver_node, \ref filter, \ref filter_node.
+ *     - Client: \ref receiver, \ref receiver_node, \ref filter,
+ *       \ref filter_node, \ref writer_node.
  *
  *
  * The gory details, listed by topic:
@@ -26,6 +27,7 @@
  *       \ref ogg_afh.c, \ref aac_afh.c, \ref wma_afh.c, \ref spx_afh.c
  *     - Decoders: \ref mp3dec_filter.c, \ref oggdec_filter.c,
  *       \ref aacdec_filter.c, \ref wmadec_filter.c, spxdec_filter.c,
+ *       \ref flacdec_filter.c,
  *     - Volume normalizer: \ref compress_filter.c,
  *     - Output: \ref alsa_write.c, \ref osx_write.c, \ref oss_write.c,
  *     - http: \ref http_recv.c, \ref http_send.c,
@@ -50,9 +52,10 @@
  *     - Spawning processes: \ref exec.c,
  *     - Inter process communication: \ref ipc.c,
  *     - Blob tables: \ref blob.c,
- *     - The error subssystem: \ref error.h.
+ *     - The error subsystem: \ref error.h.
  *     - Access control for paraslash senders: \ref acl.c, \ref acl.h.
  *     - Internal crypto API: \ref crypt.h.
+ *     - interactive sessions (libreadline): \ref interactive.c.
  *
  * Low-level data structures:
  *