From ab0b69badbf2cf070a8c32070389fb878bac7571 Mon Sep 17 00:00:00 2001
From: Paul Brossier <piem@altern.org>
Date: Wed, 17 May 2006 19:43:27 +0000
Subject: [PATCH] add doc to biquad and filter add doc to biquad and filter

---
 src/biquad.h | 39 +++++++++++++++++++++++++++++++-----
 src/filter.h | 56 +++++++++++++++++++++++++++++++++++++++++++++++-----
 2 files changed, 85 insertions(+), 10 deletions(-)

diff --git a/src/biquad.h b/src/biquad.h
index ffe6ac35..84b0bfbd 100644
--- a/src/biquad.h
+++ b/src/biquad.h
@@ -21,20 +21,49 @@
 #define BIQUAD_H
 
 /** \file 
- * biquad filter
- *
- * \f$ y[n] = b_1 x[n] + b_2 x[n-1] + b_3 x[n-2] -
- *      a_2 y[n-1] - a_3 y[n-2] \f$
- */
+
+  Second order Infinite Impulse Response filter
+
+  This file implements a normalised biquad filter (second order IIR):
+ 
+  \f$ y[n] = b_1 x[n] + b_2 x[n-1] + b_3 x[n-2] - a_2 y[n-1] - a_3 y[n-2] \f$
+
+  The filtfilt version runs the filter twice, forward and backward, to
+  compensate the phase shifting of the forward operation.
+
+*/
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/** biquad filter object */
 typedef struct _aubio_biquad_t aubio_biquad_t;
 
+/** filter input vector
+
+  \param b biquad object as returned by new_aubio_biquad
+  \param in input vector to filter
+
+*/
 void aubio_biquad_do(aubio_biquad_t * b, fvec_t * in);
+/** filter input vector forward and backward
+
+  \param b biquad object as returned by new_aubio_biquad
+  \param in input vector to filter
+  \param tmp memory space to use for computation
+
+*/
 void aubio_biquad_do_filtfilt(aubio_biquad_t * b, fvec_t * in, fvec_t * tmp);
+/** create new biquad filter
+
+  \param b1 forward filter coefficient
+  \param b2 forward filter coefficient
+  \param b3 forward filter coefficient
+  \param a2 feedback filter coefficient
+  \param a3 feedback filter coefficient
+
+*/
 aubio_biquad_t * new_aubio_biquad(lsmp_t b1, lsmp_t b2, lsmp_t b3, lsmp_t a2, lsmp_t a3);
 
 #ifdef __cplusplus
diff --git a/src/filter.h b/src/filter.h
index 5ee2ac20..c6aaad0c 100644
--- a/src/filter.h
+++ b/src/filter.h
@@ -21,22 +21,68 @@
 #define FILTER_H
 
 /** \file 
- * filter
- *
- * \f$ y[n] = b_1 x[n] + ... + b_{order} x[n-order] -
- *      a_2 y[n-1] - ... - a_{order} y[n-order]\f$
- */
+
+  Infinite Impulse Response filter
+
+  This file implements IIR filters of any order:
+ 
+  \f$ y[n] = b_1 x[n] + ... + b_{order} x[n-order] -
+       a_2 y[n-1] - ... - a_{order} y[n-order]\f$
+
+  The filtfilt version runs the filter twice, forward and backward, to
+  compensate the phase shifting of the forward operation.
+
+*/
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/** IIR filter object */
 typedef struct _aubio_filter_t aubio_filter_t;
+
+/** filter input vector (in-place)
+
+  \param b biquad object as returned by new_aubio_biquad
+  \param in input vector to filter
+
+*/
 void aubio_filter_do(aubio_filter_t * b, fvec_t * in);
+/** filter input vector (out-of-place)
+
+  \param b biquad object as returned by new_aubio_biquad
+  \param in input vector to filter
+  \param out output vector to store filtered input
+
+*/
 void aubio_filter_do_outplace(aubio_filter_t * b, fvec_t * in, fvec_t * out);
+/** filter input vector forward and backward
+
+  \param b biquad object as returned by new_aubio_biquad
+  \param in input vector to filter
+  \param tmp memory space to use for computation
+
+*/
 void aubio_filter_do_filtfilt(aubio_filter_t * b, fvec_t * in, fvec_t * tmp);
+/** create new IIR filter
+
+  \param b vector of forward coefficients 
+  \param a vector of feedback coefficients
+  \param order order of the filter (number of coefficients)
+
+*/
 aubio_filter_t * new_aubio_filter(uint_t samplerate, uint_t order);
+/** create a new A-design filter 
+
+  \param samplerate sampling-rate of the signal to filter 
+
+*/
 aubio_filter_t * new_aubio_adsgn_filter(uint_t samplerate);
+/** create a new C-design filter 
+
+  \param samplerate sampling-rate of the signal to filter 
+
+*/
 aubio_filter_t * new_aubio_cdsgn_filter(uint_t samplerate);
 
 #ifdef __cplusplus
-- 
2.26.2