1 files changed, 46 insertions, 11 deletions
diff --git a/pjmedia/src/pjmedia-codec/speex/speex_echo.h b/pjmedia/src/pjmedia-codec/speex/speex_echo.h
index 4813b5a0..44358c73 100644
--- a/pjmedia/src/pjmedia-codec/speex/speex_echo.h
+++ b/pjmedia/src/pjmedia-codec/speex/speex_echo.h
@@ -33,7 +33,10 @@
 
 #ifndef SPEEX_ECHO_H
 #define SPEEX_ECHO_H
-
+/** @defgroup SpeexEchoState SpeexEchoState: Acoustic echo canceller
+ *  This is the acoustic echo canceller module.
+ *  @{
+ */
 #include "speex/speex_types.h"
 
 #ifdef __cplusplus
@@ -48,33 +51,63 @@ extern "C" {
 /** Get sampling rate */
 #define SPEEX_ECHO_GET_SAMPLING_RATE 25
 
-
-/*struct drft_lookup;*/
+/** Internal echo canceller state. Should never be accessed directly. */
 struct SpeexEchoState_;
 
+/** @class 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 */
+/** Creates a new echo canceller state
+ * @param frame_size Number of samples to process at one time (should correspond to 10-20 ms)
+ * @param filter_length Number of samples of echo to cancel (should generally correspond to 100-500 ms)
+ * @return Newly-created echo canceller state
+ */
 SpeexEchoState *speex_echo_state_init(int frame_size, int filter_length);
 
-/** Destroys an echo canceller state */
+/** Destroys an echo canceller state 
+ * @param st Echo canceller state
+*/
 void speex_echo_state_destroy(SpeexEchoState *st);
 
-/** Performs echo cancellation a frame */
+/** Performs echo cancellation a frame, based on the audio sent to the speaker (no delay is added
+ * to playback ni this form)
+ *
+ * @param st Echo canceller state
+ * @param rec signal from the microphone (near end + far end echo)
+ * @param play Signal played to the speaker (received from far end)
+ * @param out Returns near-end signal with echo removed
+ */
+void speex_echo_cancellation(SpeexEchoState *st, const spx_int16_t *rec, const spx_int16_t *play, spx_int16_t *out);
+
+/** Performs echo cancellation a frame (deprecated) */
 void speex_echo_cancel(SpeexEchoState *st, const spx_int16_t *rec, const spx_int16_t *play, spx_int16_t *out, spx_int32_t *Yout);
 
-/** Perform echo cancellation using internal playback buffer */
-void speex_echo_capture(SpeexEchoState *st, const spx_int16_t *rec, spx_int16_t *out, spx_int32_t *Yout);
+/** Perform echo cancellation using internal playback buffer, which is delayed by two frames
+ * to account for the delay introduced by most soundcards (but it could be off!)
+ * @param st Echo canceller state
+ * @param rec signal from the microphone (near end + far end echo)
+ * @param out Returns near-end signal with echo removed
+*/
+void speex_echo_capture(SpeexEchoState *st, const spx_int16_t *rec, spx_int16_t *out);
 
-/** Let the echo canceller know that a frame was just played */
+/** Let the echo canceller know that a frame was just queued to the soundcard
+ * @param st Echo canceller state
+ * @param play Signal played to the speaker (received from far end)
+*/
 void speex_echo_playback(SpeexEchoState *st, const spx_int16_t *play);
 
-/** Reset the echo canceller state */
+/** Reset the echo canceller to its original state 
+ * @param st Echo canceller state
+ */
 void speex_echo_state_reset(SpeexEchoState *st);
 
 /** Used like the ioctl function to control the echo canceller parameters
  *
- * @param state Encoder state
+ * @param st Echo canceller state
  * @param request ioctl-type request (one of the SPEEX_ECHO_* macros)
  * @param ptr Data exchanged to-from function
  * @return 0 if no error, -1 if request in unknown
@@ -85,4 +118,6 @@ int speex_echo_ctl(SpeexEchoState *st, int request, void *ptr);
 }
 #endif
 
+
+/** @}*/
 #endif