Updated doxygen documentation. Now everything's part of a module.
authorjm <jm@0101bb08-14d6-0310-b084-bc0e0c8e3800>
Mon, 13 Nov 2006 09:19:29 +0000 (09:19 +0000)
committerjm <jm@0101bb08-14d6-0310-b084-bc0e0c8e3800>
Mon, 13 Nov 2006 09:19:29 +0000 (09:19 +0000)
git-svn-id: http://svn.xiph.org/trunk/speex@12100 0101bb08-14d6-0310-b084-bc0e0c8e3800

include/speex/speex_bits.h
include/speex/speex_callbacks.h
include/speex/speex_echo.h
include/speex/speex_header.h
include/speex/speex_jitter.h
include/speex/speex_preprocess.h
include/speex/speex_stereo.h

index 4b624cb..88334c4 100644 (file)
@@ -35,7 +35,7 @@
 
 #ifndef BITS_H
 #define BITS_H
-/** @defgroup SpeexBits Bit-stream manipulations
+/** @defgroup SpeexBits 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.
  *  @{
@@ -86,8 +86,9 @@ void speex_bits_read_whole_bytes(SpeexBits *bits, char *bytes, int len);
 
 /** Write the content of a bit-stream to an area of memory
  * 
+ * @param bits Bit-stream to operate on
  * @param bytes Memory location where to write the bits
- * @param len Maximum number of bytes to write (i.e. size of the "bytes" buffer)
+ * @param max_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);
index f6334f2..7892e2f 100644 (file)
@@ -35,6 +35,9 @@
 
 #ifndef SPEEX_CALLBACKS_H
 #define SPEEX_CALLBACKS_H
+/** @defgroup SpeexCallbacks Various definitions for Speex callbacks supported by the decoder.
+ *  @{
+ */
 
 #include "speex.h"
 
@@ -110,13 +113,16 @@ int speex_default_user_handler(SpeexBits *bits, void *state, void *data);
 
 
 
-
+/** Standard handler for low mode request (change low mode, no questions asked) */
 int speex_std_low_mode_request_handler(SpeexBits *bits, void *state, void *data);
 
+/** Standard handler for VBR request (Set VBR, no questions asked) */
 int speex_std_vbr_request_handler(SpeexBits *bits, void *state, void *data);
 
+/** Standard handler for enhancer request (Turn ehnancer on/off, no questions asked) */
 int speex_std_enh_request_handler(SpeexBits *bits, void *state, void *data);
 
+/** Standard handler for VBR quality request (Set VBR quality, no questions asked) */
 int speex_std_vbr_quality_request_handler(SpeexBits *bits, void *state, void *data);
 
 
@@ -124,5 +130,5 @@ int speex_std_vbr_quality_request_handler(SpeexBits *bits, void *state, void *da
 }
 #endif
 
-
+/** @} */
 #endif
index 506c897..44358c7 100644 (file)
@@ -33,7 +33,7 @@
 
 #ifndef SPEEX_ECHO_H
 #define SPEEX_ECHO_H
-/** @defgroup SpeexEchoState Acoustic echo canceller
+/** @defgroup SpeexEchoState SpeexEchoState: Acoustic echo canceller
  *  This is the acoustic echo canceller module.
  *  @{
  */
@@ -58,6 +58,7 @@ struct SpeexEchoState_;
  * This holds the state of the echo canceller. You need one per channel. 
 */
 
+/** Internal echo canceller state. Should never be accessed directly. */
 typedef struct SpeexEchoState_ SpeexEchoState;
 
 /** Creates a new echo canceller state
index 32fb81f..5416459 100644 (file)
 
 #ifndef SPEEX_HEADER_H
 #define SPEEX_HEADER_H
+/** @defgroup SpeexHeader SpeexHeader: Makes it easy to write/parse an Ogg/Speex header
+ *  This is the Speex header for the Ogg encapsulation. You don't need that if you just use RTP.
+ *  @{
+ */
 
 #include "speex/speex_types.h"
 
@@ -45,6 +49,7 @@ extern "C" {
 
 struct SpeexMode;
 
+/** Length of the Speex header identifier */
 #define SPEEX_HEADER_STRING_LENGTH 8
 
 /** Maximum number of characters for encoding the Speex version number in the header */
@@ -82,5 +87,5 @@ SpeexHeader *speex_packet_to_header(char *packet, int size);
 }
 #endif
 
-
+/** @} */
 #endif
index 1b75a2c..f42def8 100644 (file)
@@ -35,7 +35,7 @@
 
 #ifndef SPEEX_JITTER_H
 #define SPEEX_JITTER_H
-/** @defgroup JitterBuffer Adaptive jitter buffer
+/** @defgroup JitterBuffer 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.
  *  @{
 extern "C" {
 #endif
 
+/** Generic adaptive jitter buffer state */
 struct JitterBuffer_;
 
+/** Generic adaptive jitter buffer state */
 typedef struct JitterBuffer_ JitterBuffer;
 
+/** Definition of an incoming packet */
 typedef struct _JitterBufferPacket JitterBufferPacket;
 
+/** Definition of an incoming packet */
 struct _JitterBufferPacket {
-   char        *data;
-   spx_uint32_t len;
-   spx_uint32_t timestamp;
-   spx_uint32_t span;
+   char        *data;       /**< Data bytes contained in the packet */
+   spx_uint32_t len;        /**< Length of the packet in bytes */
+   spx_uint32_t timestamp;  /**< Timestamp for the packet */
+   spx_uint32_t span;       /**< Time covered by the packet (same units as timestamp) */
 };
 
-
+/** Packet has been retrieved */
 #define JITTER_BUFFER_OK 0
+/** Packet is missing */
 #define JITTER_BUFFER_MISSING 1
+/** Packet is incomplete (does not cover the entive tick */
 #define JITTER_BUFFER_INCOMPLETE 2
+/** There was an error in the jitter buffer */
 #define JITTER_BUFFER_INTERNAL_ERROR -1
+/** Invalid argument */
 #define JITTER_BUFFER_BAD_ARGUMENT -2
 
 /** Initialises jitter buffer 
@@ -101,7 +109,7 @@ void jitter_buffer_tick(JitterBuffer *jitter);
 
 /* @} */
 
-/** @defgroup SpeexJitter Adaptive jitter buffer specifically for Speex
+/** @defgroup SpeexJitter 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.
@@ -110,16 +118,18 @@ void jitter_buffer_tick(JitterBuffer *jitter);
 
 /** 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        */
-   JitterBuffer *packets;
-   void *dec;                                                             /**< Pointer to Speex decoder            */
-   spx_int32_t frame_size;                                                        /**< Frame size of Speex decoder         */
+   SpeexBits current_packet;         /**< Current Speex packet */
+   int valid_bits;                   /**< True if Speex bits are valid */
+   JitterBuffer *packets;            /**< Generic jitter buffer state */
+   void *dec;                        /**< Pointer to Speex decoder */
+   spx_int32_t frame_size;           /**< Frame size of Speex decoder */
 } SpeexJitter;
 
 /** Initialise jitter buffer 
  * 
  * @param jitter State of the Speex jitter buffer
+ * @param decoder Speex decoder to call
+ * @param sampling_rate Sampling rate used by the decoder
 */
 void speex_jitter_init(SpeexJitter *jitter, void *decoder, int sampling_rate);
 
index c134b33..a6845b4 100644 (file)
@@ -36,7 +36,7 @@
 
 #ifndef SPEEX_PREPROCESS_H
 #define SPEEX_PREPROCESS_H
-/** @defgroup SpeexPreprocessState Preprocessor
+/** @defgroup SpeexPreprocessState SpeexPreprocessState: The Speex preprocessor
  *  This is the Speex preprocessor. The preprocess can do noise suppression, 
  * residual echo suppression (after using the echo canceller), automatic
  * gain control (AGC) and voice activity detection (VAD).
 #ifdef __cplusplus
 extern "C" {
 #endif
-
+   
+/** State of the preprocessor (one per channel). Should never be accessed directly. */
 struct SpeexPreprocessState_;
 
+/** State of the preprocessor (one per channel). Should never be accessed directly. */
 typedef struct SpeexPreprocessState_ SpeexPreprocessState;
 
 
@@ -128,10 +130,14 @@ int speex_preprocess_ctl(SpeexPreprocessState *st, int request, void *ptr);
 /** Get preprocessor dereverb decay */
 #define SPEEX_PREPROCESS_GET_DEREVERB_DECAY 13
 
+/** Set probability required for the VAD to go from silence to voice */
 #define SPEEX_PREPROCESS_SET_PROB_START 14
+/** Get probability required for the VAD to go from silence to voice */
 #define SPEEX_PREPROCESS_GET_PROB_START 15
 
+/** Set probability required for the VAD to stay in the voice state (integer percent) */
 #define SPEEX_PREPROCESS_SET_PROB_CONTINUE 16
+/** Get probability required for the VAD to stay in the voice state (integer percent) */
 #define SPEEX_PREPROCESS_GET_PROB_CONTINUE 17
 
 /** Set maximum attenuation of the noise in dB (negative number) */
index 6ccaa31..45da338 100644 (file)
 
 #ifndef STEREO_H
 #define STEREO_H
+/** @defgroup SpeexStereoState SpeexStereoState: Handling Speex stereo files
+ *  This describes the Speex intensity stereo encoding/decoding
+ *  @{
+ */
 
 #include "speex/speex_types.h"
 #include "speex/speex_bits.h"
@@ -74,5 +78,5 @@ int speex_std_stereo_request_handler(SpeexBits *bits, void *state, void *data);
 }
 #endif
 
-
+/** @} */
 #endif