Index: pjproject/trunk/pjmedia/src/pjmedia-codec/speex/speex_jitter.h
===================================================================
--- pjproject/trunk/pjmedia/src/pjmedia-codec/speex/speex_jitter.h	(revision 628)
+++ pjproject/trunk/pjmedia/src/pjmedia-codec/speex/speex_jitter.h	(revision 823)
@@ -36,4 +36,9 @@
 #ifndef SPEEX_JITTER_H
 #define SPEEX_JITTER_H
+/** @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.
+ *  @{
+ */
 
 #include "speex.h"
@@ -44,31 +49,49 @@
 #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
 
-/** 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);
 
@@ -85,15 +108,28 @@
 void jitter_buffer_tick(JitterBuffer *jitter);
 
+/* @} */
 
-/** Speex jitter-buffer state. */
+/** @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.
+ *  @{
+ */
+
+/** 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            */
-   int 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 */
+/** 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);
 
@@ -114,4 +150,4 @@
 #endif
 
-
+/* @} */
 #endif
