Merge branch 't/doc'

Simple enough and cooking since 2013-05-05.

	e82be0 manual: Add a new paragraph for installing dependencies.
	1d6f5f manual: Add missing references of two optional packages.
	4a6061 check_wav.c: Fix documentation of check_wav_post_select().
	f9c625 Add two missing Copyright headers and file annotations.
	16af9d Add documentation of public functions in check_wav.c.

diff --git a/check_wav.c b/check_wav.c
index 80265472635d70b24be13b6723c0c26f56374fbe..11459e08c375c62285664637125c599f0e5b02be 100644 (file)
--- a/check_wav.c
+++ b/check_wav.c
@@ -19,9 +19,13 @@
 /** Length of a standard wav header. */
 #define WAV_HEADER_LEN 44
 
+/** The possible states of a check_wav instance. */
 enum check_wav_state {
+       /** Initial state, less than \p WAV_HEADER_LEN bytes available. */
        CWS_NEED_HEADER,
+       /** Wav hader was detected. */
        CWS_HAVE_HEADER,
+       /** First part of the stream did not look like a wav header. */
        CWS_NO_HEADER,
 };
 
@@ -37,6 +41,15 @@ struct check_wav_context {
        unsigned sample_rate;
 };
 
+/**
+ * Set select timeout according to the given context.
+ *
+ * \param s Contains the timeval that should be set.
+ * \param cwc Contains a pointer to the buffer tree node.
+ *
+ * This requests a minimal timeout from the scheduler if btrn of \a cwc is not
+ * idle.
+ */
 void check_wav_pre_select(struct sched *s, struct check_wav_context *cwc)
 {
        int ret = btr_node_status(cwc->btrn, cwc->min_iqs, BTR_NT_INTERNAL);
@@ -95,6 +108,22 @@ out:
        return 1;
 }
 
+/**
+ * Filter out the wav header, pushdown everything else.
+ *
+ * \param cwc The context of this instance.
+ *
+ * This function looks at the first \p WAV_HEADER_SIZE bytes of the input queue
+ * of the btrn of \a cwc. If they look like a wav header, the function extracts
+ * the information of interest and swallows this part of the stream. Otherwise
+ * it is pushed down to all children. In either case the rest of the input is
+ * pushed down as well.
+ *
+ * Once the first part has been processed this way, the state of the instance
+ * changes from \p CWS_NEED_HEADER to \p CWS_HAVE_HEADER or \p CWS_NO_HEADER.
+ *
+ * \return Standard.
+ */
 int check_wav_post_select(struct check_wav_context *cwc)
 {
        struct btr_node *btrn = cwc->btrn;
@@ -160,6 +189,23 @@ out:
        return ret;
 }
 
+/**
+ * Allocate and set up a new check_wav instance.
+ *
+ * \param parent This buffer tree node will be the parent of the new node.
+ * \param child The child of the new node.
+ * \param params Default values and options.
+ * \param cw_btrn A pointer to the check wav node is returned here.
+ *
+ * This function also sets up the ->execute handler of the btrn so that all
+ * children of this node can figure out channel count, sample rate, etc.
+ *
+ * \return The (opaque) handle of the newly created check_wav instance. It is
+ * supposed to be passed to \ref check_wav_pre_select() and \ref
+ * check_wav_post_select().
+ *
+ * \sa \ref btr_new_node.
+ */
 struct check_wav_context *check_wav_init(struct btr_node *parent,
                struct btr_node *child, struct wav_params *params,
                struct btr_node **cw_btrn)
@@ -177,6 +223,14 @@ struct check_wav_context *check_wav_init(struct btr_node *parent,
        return cwc;
 }
 
+/**
+ * Dellocate all ressources of a check_wav instance.
+ *
+ * \param cwc Determines the instance to shut down.
+ *
+ * This function may only be called after check_wav_post_select() has returned
+ * negative.
+ */
 void check_wav_shutdown(struct check_wav_context *cwc)
 {
        free(cwc);

diff --git a/check_wav.h b/check_wav.h
index 6a9577658f9743f116a7ec314387131e1522505e..ba1a8eca48f2bf9407c7f3efbbdbd74e7414b2c7 100644 (file)
--- a/check_wav.h
+++ b/check_wav.h
@@ -1,3 +1,11 @@
+/*
+ * Copyright (C) 2012-2013 Andre Noll <maan@systemlinux.org>
+ *
+ * Licensed under the GPL v2. For licencing details see COPYING.
+ */
+
+/** \file check_wav.h Detect, process and cut a wav header. */
+
 struct check_wav_context;
 
 /**

diff --git a/mix.h b/mix.h
index a4105544daf526c857e86d9ff6a1ab2dab47cd9c..427a84f559c8f67369c24e9f4910f9cccdb83e8a 100644 (file)
--- a/mix.h
+++ b/mix.h
@@ -1,3 +1,11 @@
+/*
+ * Copyright (C) 2012-2013 Andre Noll <maan@systemlinux.org>
+ *
+ * Licensed under the GPL v2. For licencing details see COPYING.
+ */
+
+/** \file mix.h Mixer API (used by para_fade). */
+
 /**
  * Opaque structure which corresponds to an instance of a mixer.
  *

diff --git a/web/manual.m4 b/web/manual.m4
index bedc170a68ba6f95d0ce379599acc19de3728a80..3f5f148fba7819ac03395792ebabec54d84ed6a4 100644 (file)
--- a/web/manual.m4
+++ b/web/manual.m4
@@ -202,8 +202,16 @@ REFERENCE(Quick start, set up) a typical server and client.
 
 Requirements
 ~~~~~~~~~~~~
+For the impatient:
 
-In any case you'll need
+       git clone git://git.tuebingen.mpg.de/osl
+       cd osl && make && sudo make install && sudo ldconfig
+       sudo apt-get install autoconf libssl-dev help2man gengetopt \
+              libmad0-dev libid3tag0-dev libasound2-dev libvorbis-dev \
+              libfaad-dev libspeex-dev libFLAC-dev libsamplerate-dev \
+              libasound2-dev libao-dev libreadline-dev libncurses-dev
+
+Detailed description: In any case you'll need
 
        - XREFERENCE(http://systemlinux.org/~maan/osl/, libosl).
        The _object storage layer_ library is used by para_server. To
@@ -267,6 +275,10 @@ Optional:
        or decode files encoded with the _Free Lossless Audio Codec_,
        libFLAC (libFLAC-dev) must be installed.
 
+       - XREFERENCE(http://www.mega-nerd.com/SRC/index.html,
+       libsamplerate). The resample filter will only be compiled if
+       this library is installed. Debian package: libsamplerate-dev.
+
        - XREFERENCE(ftp://ftp.alsa-project.org/pub/lib/, alsa-lib). On
        Linux, you'll need to have ALSA's development package
        libasound2-dev installed.
@@ -275,6 +287,9 @@ Optional:
        libao). Needed to build the ao writer (ESD, PulseAudio,...).
        Debian package: libao-dev.
 
+       - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/ncurses, curses). Needed
+       for para_gui. Debian package: libncurses-dev.
+
        - XREFERENCE(http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html,
        GNU Readline). If this library (libreadline-dev) is installed,
        para_client, para_audioc and para_play support interactive