A bunch of Doxygen comments
authorjm <jm@0101bb08-14d6-0310-b084-bc0e0c8e3800>
Sun, 12 Nov 2006 22:52:01 +0000 (22:52 +0000)
committerjm <jm@0101bb08-14d6-0310-b084-bc0e0c8e3800>
Sun, 12 Nov 2006 22:52:01 +0000 (22:52 +0000)
git-svn-id: http://svn.xiph.org/trunk/speex@12097 0101bb08-14d6-0310-b084-bc0e0c8e3800

include/speex/speex_bits.h
include/speex/speex_jitter.h

index b77202f..4b624cb 100644 (file)
 
 #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_rewind(SpeexBits *bits);
 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 @@ unsigned int speex_bits_unpack_unsigned(SpeexBits *bits, int nbBits);
  */
 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 @@ void speex_bits_advance(SpeexBits *bits, int n);
 /** 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 @@ void speex_bits_insert_terminator(SpeexBits *bits);
 }
 #endif
 
+/* @} */
 #endif
index 22f5e14..1b75a2c 100644 (file)
 
 #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 @@ struct _JitterBufferPacket {
 #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 @@ int jitter_buffer_get_pointer_timestamp(JitterBuffer *jitter);
 /** Advance by one tick */
 void jitter_buffer_tick(JitterBuffer *jitter);
 
+/* @} */
+
+/** @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. */
+/** 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 @@ typedef struct SpeexJitter {
    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 @@ int speex_jitter_get_pointer_timestamp(SpeexJitter *jitter);
 }
 #endif
 
-
+/* @} */
 #endif