[Commit-gnuradio] [gnuradio] 05/16: docs: adding better docs for using IIR kernels.

[git]

This is an automated email from the git hooks/post-receive script.

jcorgan pushed a commit to branch master
in repository gnuradio.

commit e1257b6f6caf569bd8fdcf27cb46109122383260
Author: Tom Rondeau <address@hidden>
Date:   Sun Mar 22 09:13:35 2015 -0400

    docs: adding better docs for using IIR kernels.
---
 gr-filter/include/gnuradio/filter/iir_filter.h | 46 ++++++++++++++++++++++++--
 1 file changed, 44 insertions(+), 2 deletions(-)

diff --git a/gr-filter/include/gnuradio/filter/iir_filter.h 
b/gr-filter/include/gnuradio/filter/iir_filter.h
index 5b1e5ee..d0cefc3 100644
--- a/gr-filter/include/gnuradio/filter/iir_filter.h
+++ b/gr-filter/include/gnuradio/filter/iir_filter.h
@@ -33,7 +33,50 @@ namespace gr {
     namespace kernel {
 
       /*!
-       * \brief base class template for Infinite Impulse Response filter (IIR)
+       * \brief Base class template for Infinite Impulse Response filter (IIR)
+       *
+       * \details
+       *
+       * This class provides a templated kernel for IIR filters. These
+       * iir_filters can be instantiated with a set of feed-forward
+       * and feed-back taps in the constructor. We then call the
+       * iir_filter::filter function to add a new sample to the
+       * filter, or iir_filter::filter_n to add a vector of samples to
+       * be filtered.
+       *
+       * Instantiating a filter means defining the templates for the
+       * data types being processed by the filter. There are four templates:
+       *
+       * \li i_type the data type of the input data (i.e., float).
+       * \li o_type the data type of the output data (i.e., float).
+       * \li tap_type the data type of the filter taps (i.e., double).
+       * \li acc_type the data type of the internal accumulator (i.e., double).
+       *
+       * The acc_type is specified to control how data is handled
+       * internally in the filter. This should always be the highest
+       * precision data type of any of the first three. Often, IIR
+       * filters require double-precision values in the taps for
+       * stability, and so the internal accumulator should also be
+       * double precision.
+       *
+       * Example:
+       *
+       * \code
+       * gr::filter::kernel::iir_filter<float,float,double,double> 
iir_filt(fftaps, fbtaps);
+       * ...
+       * float y = iir_filt.filter(x);
+       *
+       * <or>
+       *
+       * iir_filt.filter(y, x, N); // y and x are float arrays
+       * \endcode
+       *
+       * Another example for handling complex samples with
+       * double-precision taps (see filter::iir_filter_ccz):
+       *
+       * \code
+       * gr:;filter::kernel::iir_filter<gr_complex, gr_complex, gr_complexd, 
gr_complexd> iir_filt(fftaps, fbtaps);
+       * \endcode
        */
       template<class i_type, class o_type, class tap_type, class acc_type>
       class iir_filter
@@ -208,4 +251,3 @@ namespace gr {
 } /* namespace gr */
 
 #endif /* INCLUDED_IIR_FILTER_H */
-