[xiph-commits] r12097 - trunk/speex/include/speex

[jm at svn.xiph.org]

Author: jm
Date: 2006-11-12 14:52:01 -0800 (Sun, 12 Nov 2006)
New Revision: 12097

Modified:
   trunk/speex/include/speex/speex_bits.h
   trunk/speex/include/speex/speex_jitter.h
Log:
A bunch of Doxygen comments


Modified: trunk/speex/include/speex/speex_bits.h
===================================================================
--- trunk/speex/include/speex/speex_bits.h	2006-11-12 22:30:13 UTC (rev 12096)
+++ trunk/speex/include/speex/speex_bits.h	2006-11-12 22:52:01 UTC (rev 12097)
@@ -35,6 +35,11 @@
 
 #ifndef BITS_H
 #define BITS_H
+/** @defgroup SpeexBits Bit-stream manipulations
+ *  This is the structure that holds the bit-stream when encoding or decoding
+ * with Speex. It allows some manipulations as well.
+ *  @{
+ */
 
 #ifdef __cplusplus
 extern "C" {
@@ -72,13 +77,19 @@
 void speex_bits_read_from(SpeexBits *bits, char *bytes, int len);
 
 /** Append bytes to the bit-stream
+ * 
  * @param bits Bit-stream to operate on
  * @param bytes pointer to the bytes what will be appended
  * @param len Number of bytes of append
  */
 void speex_bits_read_whole_bytes(SpeexBits *bits, char *bytes, int len);
 
-/** Write the content of a bit-stream to an area of memory */
+/** Write the content of a bit-stream to an area of memory
+ * 
+ * @param bytes Memory location where to write the bits
+ * @param len Maximum number of bytes to write (i.e. size of the "bytes" buffer)
+ * @return Number of bytes written to the "bytes" buffer
+*/
 int speex_bits_write(SpeexBits *bits, char *bytes, int max_len);
 
 /** Like speex_bits_write, but writes only the complete bytes in the stream. Also removes the written bytes from the stream */
@@ -114,13 +125,19 @@
  */
 int speex_bits_nbytes(SpeexBits *bits);
 
-/** Same as speex_bits_unpack_unsigned, but without modifying the cursor position */
+/** Same as speex_bits_unpack_unsigned, but without modifying the cursor position 
+ * 
+ * @param bits Bit-stream to operate on
+ * @param nbBits Number of bits to look for
+ * @return Value of the bits peeked, interpreted as unsigned
+ */
 unsigned int speex_bits_peek_unsigned(SpeexBits *bits, int nbBits);
 
 /** Get the value of the next bit in the stream, without modifying the
  * "cursor" position 
  * 
  * @param bits Bit-stream to operate on
+ * @return Value of the bit peeked (one bit only)
  */
 int speex_bits_peek(SpeexBits *bits);
 
@@ -134,6 +151,7 @@
 /** Returns the number of bits remaining to be read in a stream
  *
  * @param bits Bit-stream to operate on
+ * @return Number of bits that can still be read from the stream
  */
 int speex_bits_remaining(SpeexBits *bits);
 
@@ -148,4 +166,5 @@
 }
 #endif
 
+/* @} */
 #endif

Modified: trunk/speex/include/speex/speex_jitter.h
===================================================================
--- trunk/speex/include/speex/speex_jitter.h	2006-11-12 22:30:13 UTC (rev 12096)
+++ trunk/speex/include/speex/speex_jitter.h	2006-11-12 22:52:01 UTC (rev 12097)
@@ -35,6 +35,11 @@
 
 #ifndef SPEEX_JITTER_H
 #define SPEEX_JITTER_H
+/** @defgroup JitterBuffer Adaptive jitter buffer
+ *  This is the jitter buffer that reorders UDP/RTP packets and adjusts the buffer size
+ * to maintain good quality and low latency.
+ *  @{
+ */
 
 #include "speex.h"
 #include "speex_bits.h"
@@ -63,13 +68,23 @@
 #define JITTER_BUFFER_INTERNAL_ERROR -1
 #define JITTER_BUFFER_BAD_ARGUMENT -2
 
-/** Initialise jitter buffer */
+/** Initialises jitter buffer 
+ * 
+ * @param tick Number of samples per "tick", i.e. the time period of the elements that will be retrieved
+ * @return Newly created jitter buffer state
+ */
 JitterBuffer *jitter_buffer_init(int tick);
 
-/** Reset jitter buffer */
+/** Restores jitter buffer to its original state 
+ * 
+ * @param jitter Jitter buffer state
+ */
 void jitter_buffer_reset(JitterBuffer *jitter);
 
-/** Destroy jitter buffer */
+/** Destroys jitter buffer 
+ * 
+ * @param jitter Jitter buffer state
+ */
 void jitter_buffer_destroy(JitterBuffer *jitter);
 
 /** Put one packet into the jitter buffer */
@@ -84,8 +99,16 @@
 /** Advance by one tick */
 void jitter_buffer_tick(JitterBuffer *jitter);
 
+/* @} */
 
-/** Speex jitter-buffer state. */
+/** @defgroup SpeexJitter Adaptive jitter buffer specifically for Speex
+ *  This is the jitter buffer that reorders UDP/RTP packets and adjusts the buffer size
+ * to maintain good quality and low latency. This is a simplified version that works only
+ * with Speex, but is much easier to use.
+ *  @{
+ */
+
+/** Speex jitter-buffer state. Never use it directly! */
 typedef struct SpeexJitter {
    SpeexBits current_packet;                                              /**< Current Speex packet                */
    int valid_bits;                                                        /**< True if Speex bits are valid        */
@@ -94,7 +117,10 @@
    spx_int32_t frame_size;                                                        /**< Frame size of Speex decoder         */
 } SpeexJitter;
 
-/** Initialise jitter buffer */
+/** Initialise jitter buffer 
+ * 
+ * @param jitter State of the Speex jitter buffer
+*/
 void speex_jitter_init(SpeexJitter *jitter, void *decoder, int sampling_rate);
 
 /** Destroy jitter buffer */
@@ -113,5 +139,5 @@
 }
 #endif
 
-
+/* @} */
 #endif