more documentation updates

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

11 files changed, 106 insertions, 63 deletions

diff --git a/src/polyp/channelmap.h b/src/polyp/channelmap.h
index 99020583..bb9f78b1 100644
--- a/src/polyp/channelmap.h
+++ b/src/polyp/channelmap.h
@@ -25,7 +25,7 @@
 #include <polyp/sample.h>
 #include <polyp/cdecl.h>
 
-/** \page channelmap Channel maps
+/** \page channelmap Channel Maps
  *
  * \section overv_sec Overview
  *
@@ -48,7 +48,7 @@
  * \li pa_channel_map_init_auto() - Create a standard channel map for up to
  *                                  six channels.
  *
- * \section conv_sec Convenience functions
+ * \section conv_sec Convenience Functions
  *
  * The library contains a number of convenience functions for dealing with
  * channel maps:
diff --git a/src/polyp/context.h b/src/polyp/context.h
index 84830811..01c1b76a 100644
--- a/src/polyp/context.h
+++ b/src/polyp/context.h
@@ -36,7 +36,7 @@
  * It allows full access to all available functions. This also means that
  * it is rather complex and can take some time to fully master.
  *
- * \section mainloop_sec Main loop abstraction
+ * \section mainloop_sec Main Loop Abstraction
  *
  * The API is based around an asynchronous event loop, or main loop,
  * abstraction. This abstraction contains three basic elements:
@@ -63,7 +63,7 @@
  * \ref mainloop-signal.h. These rely only on the main loop abstraction
  * and can therefore be used with any of the implementations.
  *
- * \section refcnt_sec Reference counting
+ * \section refcnt_sec Reference Counting
  *
  * Almost all objects in polypaudio are reference counted. What that means
  * is that you rarely malloc() or free() any objects. Instead you increase
diff --git a/src/polyp/def.h b/src/polyp/def.h
index 432bd8ce..80e3092b 100644
--- a/src/polyp/def.h
+++ b/src/polyp/def.h
@@ -119,7 +119,7 @@ typedef enum pa_stream_flags {
                                       * ahead can be corrected
                                       * quickly, without the need to
                                       * wait. */
-    PA_STREAM_AUTO_TIMING_UPDATE = 8 /** If set timing update requests
+    PA_STREAM_AUTO_TIMING_UPDATE = 8 /**< If set timing update requests
                                        * are issued periodically
                                        * automatically. Combined with
                                        * PA_STREAM_INTERPOLATE_TIMING
diff --git a/src/polyp/glib-mainloop.h b/src/polyp/glib-mainloop.h
index bc66409b..ce885e13 100644
--- a/src/polyp/glib-mainloop.h
+++ b/src/polyp/glib-mainloop.h
@@ -27,7 +27,7 @@
 #include <polyp/mainloop-api.h>
 #include <polyp/cdecl.h>
 
-/** \page glib-mainloop GLIB main loop bindings
+/** \page glib-mainloop GLIB Main Loop Bindings
  *
  * \section overv_sec Overview
  *
diff --git a/src/polyp/introspect.h b/src/polyp/introspect.h
index a8292ba1..9a0edb79 100644
--- a/src/polyp/introspect.h
+++ b/src/polyp/introspect.h
@@ -30,7 +30,7 @@
 #include <polyp/channelmap.h>
 #include <polyp/volume.h>
 
-/** \page introspect Server query and control
+/** \page introspect Server Query and Control
  *
  * \section overv_sec Overview
  *
@@ -62,19 +62,19 @@
  * duration of the callback. If they are required after the callback is
  * finished, a deep copy must be performed.
  *
- * \subsection server_subsec Server information
+ * \subsection server_subsec Server Information
  *
  * The server can be queried about its name, the environment it's running on
  * and the currently active global defaults. Calling
  * pa_context_get_server_info() will get access to a pa_server_info structure
  * containing all of these.
  *
- * \subsection memstat_subsec Memory usage
+ * \subsection memstat_subsec Memory Usage
  *
  * Statistics about memory usage can be fetched using pa_context_stat(),
  * giving a pa_stat_info structure.
  *
- * \subsection sinksrc_subsec Sinks and sources
+ * \subsection sinksrc_subsec Sinks and Sources
  *
  * The server can have an arbitrary number of sinks and sources. Each sink
  * and source have both an index and a name associated with it. As such
@@ -90,7 +90,7 @@
  * All three method use the same callback and will provide a pa_sink_info or
  * pa_source_info structure.
  *
- * \subsection siso_subsec Sink inputs and source outputs
+ * \subsection siso_subsec Sink Inputs and Source Outputs
  *
  * Sink inputs and source outputs are the representations of the client ends
  * of streams inside the server. I.e. they connect a client stream to one of
@@ -119,13 +119,13 @@
  * Note that this only retrieves information about the sample, not the sample
  * data itself.
  *
- * \subsection module_subsec Modules
+ * \subsection module_subsec Driver Modules
  *
- * Polypaudio modules are identified by index and are retrieved using either
+ * Polypaudio driver modules are identified by index and are retrieved using either
  * pa_context_get_module_info() or pa_context_get_module_info_list(). The
  * information structure is called pa_module_info.
  *
- * \subsection autoload_subsec Autoload entries
+ * \subsection autoload_subsec Autoload Entries
  *
  * Modules can be autoloaded as a result of a client requesting a certain
  * sink or source. This mapping between sink/source names and modules can be
@@ -147,7 +147,7 @@
  * modified in different ways. Note that these changes will affect all
  * connected clients and not just the one issuing the request.
  *
- * \subsection sinksrc_subsec Sinks and sources
+ * \subsection sinksrc_subsec Sinks and Sources
  *
  * The most common change one would want to do to sinks and sources is to
  * modify the volume of the audio. Identical to how sinks and sources can
@@ -165,7 +165,7 @@
  * \li By name - pa_context_set_sink_mute_by_name() /
  *               pa_context_set_source_mute_by_name()
  *
- * \subsection siso_subsec Sink inputs and source outputs
+ * \subsection siso_subsec Sink Inputs and Source Outputs
  *
  * If an application desires to modify the volume of just a single stream
  * (commonly one of its own streams), this can be done by setting the volume
@@ -184,7 +184,7 @@
  * Server modules can be remotely loaded and unloaded using
  * pa_context_load_module() and pa_context_unload_module().
  *
- * \subsection autoload_subsec Autoload entries
+ * \subsection autoload_subsec Autoload Entries
  *
  * New module autoloading rules can be added, and existing can be removed
  * using pa_context_add_autoload() and pa_context_remove_autoload_by_index()
diff --git a/src/polyp/mainloop.h b/src/polyp/mainloop.h
index 6fb2a96c..fe2b4c5b 100644
--- a/src/polyp/mainloop.h
+++ b/src/polyp/mainloop.h
@@ -27,7 +27,7 @@
 
 PA_C_DECL_BEGIN
 
-/** \page mainloop Mainloop
+/** \page mainloop Main Loop
  *
  * \section overv_sec Overview
  *
@@ -81,15 +81,13 @@ void pa_mainloop_free(pa_mainloop* m);
 
 /** Prepare for a single iteration of the main loop. Returns a negative value
 on error or exit request. timeout specifies a maximum timeout for the subsequent
-poll, or -1 for blocking behaviour. Defer events are also dispatched when this
-function is called. On success returns the number of source dispatched in this
-iteration.*/
+poll, or -1 for blocking behaviour. .*/
 int pa_mainloop_prepare(pa_mainloop *m, int timeout);
 
 /** Execute the previously prepared poll. Returns a negative value on error.*/
 int pa_mainloop_poll(pa_mainloop *m);
 
-/** Dispatch timeout and io events from the previously executed poll. Returns
+/** Dispatch timeout, io and deferred events from the previously executed poll. Returns
 a negative value on error. On success returns the number of source dispatched. */
 int pa_mainloop_dispatch(pa_mainloop *m);
 
@@ -101,7 +99,7 @@ for pa_mainloop_prepare(), pa_mainloop_poll() and pa_mainloop_dispatch().
 Returns a negative value on error or exit request. If block is nonzero,
 block for events if none are queued. Optionally return the return value as
 specified with the main loop's quit() routine in the integer variable retval points
-to. On success returns the number of source dispatched in this iteration. */
+to. On success returns the number of sources dispatched in this iteration. */
 int pa_mainloop_iterate(pa_mainloop *m, int block, int *retval);
 
 /** Run unlimited iterations of the main loop object until the main loop's quit() routine is called. */
diff --git a/src/polyp/sample.h b/src/polyp/sample.h
index 0706be5a..4de84301 100644
--- a/src/polyp/sample.h
+++ b/src/polyp/sample.h
@@ -28,14 +28,14 @@
 
 #include <polyp/cdecl.h>
 
-/** \page sample Sample format specifications
+/** \page sample Sample Format Specifications
  *
  * \section overv_sec Overview
  *
  * Polypaudio is capable of handling a multitude of sample formats, rates
  * and channels, transparently converting and mixing them as needed.
  *
- * \section format_sec Sample format
+ * \section format_sec Sample Format
  *
  * Polypaudio supports the following sample formats:
  *
@@ -52,7 +52,7 @@
  * The sample formats that are sensitive to endianness have convenience
  * macros for native endian (NE), and reverse endian (RE).
  *
- * \section rate_sec Sample rates
+ * \section rate_sec Sample Rates
  *
  * Polypaudio supports any sample rate between 1 Hz and 4 GHz. There is no
  * point trying to exceed the sample rate of the output device though as the
@@ -78,7 +78,7 @@
  * \li pa_bytes_to_usec() - Calculate the time it would take to play a buffer
  *                          of a certain size.
  *
- * \section util_sec Convenience functions
+ * \section util_sec Convenience Functions
  *
  * The library also contains a couple of other convenience functions:
  *
diff --git a/src/polyp/scache.h b/src/polyp/scache.h
index a6b312f5..91890673 100644
--- a/src/polyp/scache.h
+++ b/src/polyp/scache.h
@@ -28,7 +28,7 @@
 #include <polyp/stream.h>
 #include <polyp/cdecl.h>
 
-/** \page scache Sample cache
+/** \page scache Sample Cache
  *
  * \section overv_sec Overview
  *
diff --git a/src/polyp/stream.h b/src/polyp/stream.h
index 6367e868..a832fc66 100644
--- a/src/polyp/stream.h
+++ b/src/polyp/stream.h
@@ -31,7 +31,7 @@
 #include <polyp/cdecl.h>
 #include <polyp/operation.h>
 
-/** \page streams Audio streams
+/** \page streams Audio Streams
  *
  * \section overv_sec Overview
  *
@@ -67,14 +67,16 @@
  * pa_stream_set_state_callback(), and wait for the stream to enter an active
  * state.
  *
- * \subsection bufattr_subsec Buffer attributes
+ * \subsection bufattr_subsec Buffer Attributes
  *
- * Playback and record streams always have a server side buffer as part of the data flow.
- * The size of this buffer strikes a compromise between low latency and
- * sensitivity for buffer overflows/underruns.
+ * Playback and record streams always have a server side buffer as
+ * part of the data flow.  The size of this buffer strikes a
+ * compromise between low latency and sensitivity for buffer
+ * overflows/underruns.
  *
- * The buffer is described with a pa_buffer_attr structure which contains a
- * number of field:
+ * The buffer metrics may be controlled by the application. They are
+ * described with a pa_buffer_attr structure which contains a number
+ * of fields:
  *
  * \li maxlength - The absolute maximum number of bytes that can be stored in
  *                 the buffer. If this value is exceeded then data will be
@@ -82,16 +84,37 @@
  * \li tlength - The target length of a playback buffer. The server will only
  *               send requests for more data as long as the buffer has less
  *               than this number of bytes of data.
- * \li prebuf - Number of bytes that need to be in the buffer before playback
- *              will commence. Start of playback can be forced using
- *              pa_stream_trigger() even though the prebuffer size hasn't been
- *              reached.
+ * \li prebuf - Number of bytes that need to be in the buffer before
+ * playback will commence. Start of playback can be forced using
+ * pa_stream_trigger() even though the prebuffer size hasn't been
+ * reached. If a buffer underrun occurs, this prebuffering will be
+ * again enabled. If the playback shall never stop in case of a buffer
+ * underrun, this value should be set to 0. In that case the read
+ * index of the output buffer overtakes the write index, and hence the
+ * fill level of the buffer is negative.
  * \li minreq - Minimum free number of the bytes in the playback buffer before
  *              the server will request more data.
  * \li fragsize - Maximum number of bytes that the server will push in one
  *                chunk for record streams.
  *
- * \section transfer_sec Transferring data
+ * The server side playback buffers are indexed by a write and a read
+ * index. The application writes to the write index and the sound
+ * device reads from the read index. The read index is increased
+ * monotonically, while the write index may be freely controlled by
+ * the application. Substracting the read index from the write index
+ * will give you the current fill level of the buffer. The read/write
+ * indexes are 64bit values and measured in bytes, they will never
+ * wrap. The current read/write index may be queried using
+ * pa_stream_get_timing_info() (see below for more information). In
+ * case of a buffer underrun the read index is equal or larger than
+ * the write index. Unless the prebuf value is 0, Polypaudio will
+ * temporarily pause playback in such a case, and wait until the
+ * buffer is filled up to prebuf bytes again. If prebuf is 0, the
+ * read index may be larger than the write index, in which case
+ * silence is played. If the application writes data to indexes lower
+ * than the read index, the data is immediately lost.
+ *                
+ * \section transfer_sec Transferring Data
  *
  * Once the stream is up, data can start flowing between the client and the
  * server. Two different access models can be used to transfer the data:
@@ -112,7 +135,7 @@
  * record. Make sure you do not overflow the playback buffers as data will be
  * dropped.
  *
- * \section bufctl_sec Buffer control
+ * \section bufctl_sec Buffer Control
  *
  * The transfer buffers can be controlled through a number of operations:
  *
@@ -126,6 +149,23 @@
  * \li pa_stream_flush() - Drop all data from the playback buffer and do not
  *                         wait for it to finish playing.
  *
+ * \section seek_modes Seeking in the Playback Buffer
+ *
+ * A client application may freely seek in the playback buffer. To
+ * accomplish that the pa_stream_write() function takes a seek mode
+ * and an offset argument. The seek mode is one of:
+ *
+ * \li PA_SEEK_RELATIVE - seek relative to the current write index
+ * \li PA_SEEK_ABSOLUTE - seek relative to the beginning of the playback buffer, (i.e. the first that was ever played in the stream)
+ * \li PA_SEEK_RELATIVE_ON_READ - seek relative to the current read index. Use this to write data to the output buffer that should be played as soon as possible
+ * \li PA_SEEK_RELATIVE_END - seek relative to the last byte ever written.
+ * 
+ * If an application just wants to append some data to the output
+ * buffer, PA_SEEK_RELATIVE and an offset of 0 should be used.
+ *
+ * After a call to pa_stream_write() the write index will be left at
+ * the position right after the last byte of the written data.
+ *                         
  * \section latency_sec Latency
  *
  * A major problem with networked audio is the increased latency caused by
@@ -134,8 +174,10 @@
  *
  * To get the raw data needed to calculate latencies, call
  * pa_stream_get_timing_info(). This will give you a pa_timing_info
- * structure that contains everything that is known about buffers,
- * transport delays and the backend active in the server.
+ * structure that contains everything that is known about the server
+ * side buffer transport delays and the backend active in the
+ * server. (Besides other things it contains the write and read index
+ * values mentioned above.)
  *
  * This structure is updated every time a
  * pa_stream_update_timing_info() operation is executed. (i.e. before
@@ -157,32 +199,38 @@
  * you can call pa_stream_get_time() or pa_stream_get_latency(). The
  * former will return the current playback time of the hardware since
  * the stream has been started. The latter returns the time a sample
- * that you write now takes to be played by the hardware.
+ * that you write now takes to be played by the hardware. These two
+ * functions base their calculations on the same data that is returned
+ * by pa_stream_get_timing_info(). Hence the same rules for keeping
+ * the timing data up-to-date apply here. In case the write or read
+ * index is corrupted, these two functions will fail with
+ * PA_ERR_NODATA set.
  *
  * Since updating the timing info structure usually requires a full
- * round trip and some applications monitor the timing very often
- * Polypaudio offers a timing interpolation system. If
+ * network round trip and some applications monitor the timing very
+ * often Polypaudio offers a timing interpolation system. If
  * PA_STREAM_INTERPOLATE_TIMING is passed when connecting the stream,
  * pa_stream_get_time() and pa_stream_get_latency() will try to
  * interpolate the current playback time/latency by estimating the
  * number of samples that have been played back by the hardware since
  * the last regular timing update. It is espcially useful to combine
  * this option with PA_STREAM_AUTO_TIMING_UPDATE, which will enable
- * you to monitor the current playback time/latency very precisely
- * without requiring a network round trip every time.
+ * you to monitor the current playback time/latency very precisely and
+ * very frequently without requiring a network round trip every time.
  * 
  * \section flow_sec Overflow and underflow
  *
- * Even with the best precautions, buffers will sometime over - or underflow.
- * To handle this gracefully, the application can be notified when this
- * happens. Callbacks are registered using pa_stream_set_overflow_callback()
- * and pa_stream_set_underflow_callback().
+ * Even with the best precautions, buffers will sometime over - or
+ * underflow.  To handle this gracefully, the application can be
+ * notified when this happens. Callbacks are registered using
+ * pa_stream_set_overflow_callback() and
+ * pa_stream_set_underflow_callback().
  *
- * \section sync_streams Sychronizing Multiple Playback Streams.
+ * \section sync_streams Sychronizing Multiple Playback Streams
  *
- * Polypaudio allows applications to fully synchronize multiple playback
- * streams that are connected to the same output device. That means
- * the streams will always be played back sample-by-sample
+ * Polypaudio allows applications to fully synchronize multiple
+ * playback streams that are connected to the same output device. That
+ * means the streams will always be played back sample-by-sample
  * synchronously. If stream operations like pa_stream_cork() are
  * issued on one of the synchronized streams, they are simultaneously
  * issued on the others.
@@ -199,9 +247,6 @@
  * synchronized streams continue playing and hence deviate you need to
  * pass a "prebuf" pa_buffer_attr of 0 when connecting it.
  *
- * \section seek_modes Seeking in the Playback Buffer
- *
- * T.B.D
  * \section disc_sec Disconnecting
  *
  * When a stream has served is purpose it must be disconnected with
@@ -297,7 +342,7 @@ int pa_stream_peek(
         const void **data            /**< Pointer to pointer that will point to data */,
         size_t *length              /**< The length of the data read */);
 
-/** Remove the current fragment. It is invalid to do this without first
+/** Remove the current fragment on record streams. It is invalid to do this without first
  * calling pa_stream_peek(). \since 0.8 */
 int pa_stream_drop(pa_stream *p);
 
diff --git a/src/polyp/subscribe.h b/src/polyp/subscribe.h
index 75b4696f..d8326e1c 100644
--- a/src/polyp/subscribe.h
+++ b/src/polyp/subscribe.h
@@ -28,7 +28,7 @@
 #include <polyp/context.h>
 #include <polyp/cdecl.h>
 
-/** \page subscribe Event subscription
+/** \page subscribe Event Subscription
  *
  * \section overv_sec Overview
  *
diff --git a/src/polyp/volume.h b/src/polyp/volume.h
index a72069eb..0da5f54f 100644
--- a/src/polyp/volume.h
+++ b/src/polyp/volume.h
@@ -26,7 +26,7 @@
 #include <polyp/cdecl.h>
 #include <polyp/sample.h>
 
-/** \page volume Volume control
+/** \page volume Volume Control
  *
  * \section overv_sec Overview
  *
@@ -62,7 +62,7 @@
  * PA_VOLUME_NORM (100%) and to refrain from any calculations with
  * them.
  *
- * \section conv_sec Convenience functions
+ * \section conv_sec Convenience Functions
  *
  * To handle the pa_cvolume structure, the Polypaudio library provides a
  * number of convenienc functions: