Escape IIR in Doxygen strings for upcoming C++ library

src/docs/MainPage.dox

@@ -1,16 +1,16 @@
 /* libiir/src/docs/MainPage.dox
  *
- *  Copyright: ©2010, Laurence Withers.
+ *  Copyright: ©2010–2014, Laurence Withers.
  *  Author: Laurence Withers <l@lwithers.me.uk>
  *  License: GPLv3
 */
 
 /*! \mainpage
 
-This library allows the implementation of arbitrary IIR filters in C. It has
+This library allows the implementation of arbitrary %IIR filters in C. It has
 functions for generating and manipulating filters in terms of coefficients, for
 chaining arbitrary filters together, and for generating coefficients for some
-common types of filter. See \ref iir_structure for a definition of the IIR
+common types of filter. See \ref iir_structure for a definition of the %IIR
 filter equation.
 
 \section creation Filter creation
@@ -47,6 +47,11 @@ installed) which will generate a Bode plot for a given filter chain. Note the
 phase response can be a little rough due to the simplistic time-domain analysis
 of the output signal's phase.
 
+\section cpp C++
+
+Two C++ wrapper objects, \ref IIR::Coeff and \ref IIR::Filter, are supplied which provide
+a true object-oriented interface on top of the C implementation.
+
 */
 
 /* options for text editors

src/docs/iir_structure.dox

@@ -1,6 +1,6 @@
 /* libiir/src/docs/iir_structure.dox
  * 
- *  Copyright: ©2010–2011, Laurence Withers.
+ *  Copyright: ©2010–2014, Laurence Withers.
  *  Author: Laurence Withers <l@lwithers.me.uk>
  *  License: GPLv3
 */
@@ -14,7 +14,7 @@ For the purposes of this library, the following notation is used:
 \li <code>c[n]</code>: array of \c x(t) coefficients
 \li <code>d[n]</code>: array of \c y(t) coefficients
 
-This leads to a general IIR filter equation:
+This leads to a general %IIR filter equation:
 
 <code>y(t) = x(t).c[0] + x(t-1).c[1] + … + x(t-N).c[N] - y(t-1).d[0] - y(t-2).d[1] - … - y(t-1-M).d[M]</code>
 

src/docs/string_desc.dox

@@ -1,17 +1,17 @@
 /* libiir/src/docs/string_desc.dox
  *
- *  Copyright: ©2010, Laurence Withers.
+ *  Copyright: ©2010–2014, Laurence Withers.
  *  Author: Laurence Withers <l@lwithers.me.uk>
  *  License: GPLv3
 */
 
 /*! \page string_desc Describing IIR filters as strings
 
-This library allows the user to describe an IIR filter chain as a string, which
+This library allows the user to describe an %IIR filter chain as a string, which
 is useful to allow configurable filtering using e.g. a configuration file. This
 page describes the format of such strings.
 
-The string is first split into individual IIR filters. Each filter is written as
+The string is first split into individual %IIR filters. Each filter is written as
 \c type(params) and separated by whitespace. The string must contain at least
 one filter but may contain an arbitrary number.
 
@@ -23,7 +23,7 @@ one filter but may contain an arbitrary number.
 
 \subsection string_desc_coeff Raw coefficients
 
-An IIR filter may be specified as raw coefficients, in which case the \c type
+An %IIR filter may be specified as raw coefficients, in which case the \c type
 is \c raw and the \c params consists of a string:
 
 <code>c[0],c[1],…,c[n]/d[0],d[1]…d[n]</code>

src/libiir/100_coeff.h

@@ -12,10 +12,10 @@
 \ingroup libiir
 
 The functions in this module present an interface for managing the set of
-coefficients of a single IIR filter instance. See \ref iir_structure for
+coefficients of a single %IIR filter instance. See \ref iir_structure for
 the definition of a coefficient set. The coefficient sets form the
-basic building block of an IIR filter instance (see \ref libiir_filter),
+basic building block of an %IIR filter instance (see \ref libiir_filter),
-which may chain several IIR filters in sequence.
+which may chain several %IIR filters in sequence.
 
 */
 /*!@{*/
@@ -27,15 +27,15 @@ struct iir_coeff_t;
 
 
 
-/*! \brief Create IIR coefficient set
+/*! \brief Create %IIR coefficient set
 
 \param nc Number of \a c coefficients.
 \param c Array of \a c coefficients.
 \param nd Number of \a d coefficients.
 \param d Array of \a d coefficients.
-\returns Pointer to new general IIR filter object.
+\returns Pointer to new general %IIR filter object.
 
-This function creates a new set of IIR filter coefficients which may be used to
+This function creates a new set of %IIR filter coefficients which may be used to
 create filter instances through \ref iir_filter_new() or chained on to existing
 instances through \ref iir_filter().
 
@@ -51,23 +51,23 @@ struct iir_coeff_t* iir_coeff_new(int nc, const double* c, int nd,
 
 
 
-/*! \brief Create copy of a set of IIR coefficients
+/*! \brief Create copy of a set of %IIR coefficients
 
-\param other Set of IIR filter coefficients to copy.
+\param other Set of %IIR filter coefficients to copy.
-\returns Pointer to new general IIR filter object.
+\returns Pointer to new general %IIR filter object.
 
-Performs a deep copy of the set of IIR coefficients contained within \a other.
+Performs a deep copy of the set of %IIR coefficients contained within \a other.
 
 */
 struct iir_coeff_t* iir_coeff_copy(const struct iir_coeff_t* other);
 
 
 
-/*! \brief Free IIR coefficient set
+/*! \brief Free %IIR coefficient set
 
-\param coeff Pointer to IIR coefficient object. May be 0.
+\param coeff Pointer to %IIR coefficient object. May be 0.
 
-Frees a set of IIR filter coefficients previously allocated through
+Frees a set of %IIR filter coefficients previously allocated through
 \ref iir_coeff_new(). Can be called on a null pointer without consequences.
 Note that \ref iir_filter_new() and \ref iir_filter_chain() actually store a
 copy of the coefficients, so it is possible to free \a coeff even if existing
@@ -80,7 +80,7 @@ void iir_coeff_free(struct iir_coeff_t* coeff);
 
 /*! \brief Query number of C coefficients.
 
-\param coeff Pointer to IIR coefficient object.
+\param coeff Pointer to %IIR coefficient object.
 \returns Number of C coefficients (≥1).
 
 */
@@ -90,7 +90,7 @@ int iir_coeff_get_nc(const struct iir_coeff_t* coeff);
 
 /*! \brief Query number of D coefficients.
 
-\param coeff Pointer to IIR coefficient object.
+\param coeff Pointer to %IIR coefficient object.
 \returns Number of D coefficients (≥1).
 
 */
@@ -100,7 +100,7 @@ int iir_coeff_get_nd(const struct iir_coeff_t* coeff);
 
 /*! \brief Get value of C coefficient.
 
-\param coeff Pointer to IIR coefficient object.
+\param coeff Pointer to %IIR coefficient object.
 \param idx Index of coefficient (≥0, < \ref iir_coeff_get_nc()).
 \returns C coefficient value.
 
@@ -111,7 +111,7 @@ double iir_coeff_get_c(const struct iir_coeff_t* coeff, int idx);
 
 /*! \brief Get value of D coefficient.
 
-\param coeff Pointer to IIR coefficient object.
+\param coeff Pointer to %IIR coefficient object.
 \param idx Index of coefficient (≥0, < \ref iir_coeff_get_nd()).
 \returns D coefficient value.
 

src/libiir/200_filter.h

@@ -11,15 +11,15 @@
 
 \ingroup libiir
 
-The functions in this module present a basic interface for representing IIR
+The functions in this module present a basic interface for representing %IIR
-filters, creating instances of (possibly chained) IIR filters, and filtering an
+filters, creating instances of (possibly chained) %IIR filters, and filtering an
 input sample.
 
-A general IIR filter consists of a set of coefficients, and may be created
+A general %IIR filter consists of a set of coefficients, and may be created
 through \ref iir_coeff_new(). The filter object (the opaque <code>struct
 iir_coeff_t</code>) is then used to instantiate specific filters (the opaque
 <code>struct iir_filter_t</code>) through \ref iir_filter_new(). Each filter
-instance may have an arbitrary further number of IIR filters chained on to it
+instance may have an arbitrary further number of %IIR filters chained on to it
 through \ref iir_filter_chain(). The filter processes one sample at a time
 through \ref iir_filter().
 
@@ -33,12 +33,12 @@ struct iir_filter_t;
 
 
 
-/*! \brief Create IIR filter instance
+/*! \brief Create %IIR filter instance
 
 \param coeff Filter coefficients to use.
-\returns Pointer to new instance of IIR filter.
+\returns Pointer to new instance of %IIR filter.
 
-Creates a new instance of a general IIR filter. The set of coefficients \a coeff
+Creates a new instance of a general %IIR filter. The set of coefficients \a coeff
 is copied into the returned structure, meaning the coefficients can be freed
 after this function returns if they will not be needed again.
 
@@ -57,11 +57,11 @@ struct iir_filter_t* iir_filter_new(const struct iir_coeff_t* coeff)
 
 
 
-/*! \brief Free IIR filter instance
+/*! \brief Free %IIR filter instance
 
 \param fi Filter object to free. May be 0.
 
-Frees a previously-allocated IIR filter instance. Can be called on a null
+Frees a previously-allocated %IIR filter instance. Can be called on a null
 pointer without consequences.
 
 */
@@ -69,12 +69,12 @@ void iir_filter_free(struct iir_filter_t* fi);
 
 
 
-/*! \brief Add a further IIR filter to a filter instance
+/*! \brief Add a further %IIR filter to a filter instance
 
 \param fi Filter instance to chain onto.
-\param coeff New IIR filter coefficients to add to chain.
+\param coeff New %IIR filter coefficients to add to chain.
 
-Extends an existing IIR filter by chaining a new set of coefficients onto the
+Extends an existing %IIR filter by chaining a new set of coefficients onto the
 end. This can be used for &gt;4th order Butterworth filters, for example. This
 copies the set of coefficients from \a coeff so the coefficients can be freed
 after this function returns if they are no longer required.
@@ -88,7 +88,7 @@ void iir_filter_chain(struct iir_filter_t* fi, const struct iir_coeff_t* coeff)
 
 
 
-/*! \brief Create a deep copy of an IIR filter instance
+/*! \brief Create a deep copy of an %IIR filter instance
 
 \param fi Filter instance to copy.
 \param state Non-zero to copy state as well.
@@ -121,12 +121,12 @@ double iir_filter(struct iir_filter_t* fi, double samp);
 
 
 
-/*! \brief Count number of coefficient sets in IIR filter chain
+/*! \brief Count number of coefficient sets in %IIR filter chain
 
 \param fi Filter object.
 \returns Number of coefficient sets in chain (≥1).
 
-Returns the number of discrete IIR filter coefficient sets used in the filter
+Returns the number of discrete %IIR filter coefficient sets used in the filter
 object \a fi. There will always be at least one set.
 
 */
@@ -134,13 +134,13 @@ int iir_filter_coeff_sets(const struct iir_filter_t* fi);
 
 
 
-/*! \brief Get IIR coefficient set from filter chain
+/*! \brief Get %IIR coefficient set from filter chain
 
 \param fi Filter object.
 \param idx Index of coefficient set (0 ≤ \a idx &lt; \ref iir_filter_coeff_sets()).
 \returns Newly-allocated coefficient set object.
 
-Extracts the IIR filter coefficient set for the given step (\a idx) in the chain
+Extracts the %IIR filter coefficient set for the given step (\a idx) in the chain
 of filters in \a fi. Returns a newly-allocated filter coefficient set object
 which can be freed with \ref iir_coeff_free().
 

src/libiir/300_common_filters.h

@@ -11,8 +11,8 @@
 
 \ingroup libiir
 
-Functions to create coefficients for various common types of IIR filter. The
+Functions to create coefficients for various common types of %IIR filter. The
-coefficient structures which are returned may be used to instantiate IIR
+coefficient structures which are returned may be used to instantiate %IIR
 filters using \ref iir_filter_new().
 
 The Butterworth filter code comes from the Exstrom Labs LLC code available under
@@ -30,7 +30,7 @@ is a copy of the original code available in the top level of this project.
 \param gain Linear gain of filter.
 \param corner Corner frequency expressed as a fraction of Nyquist
     (0 ≤ \a corner ≤ 1)
-\returns Newly-allocated IIR filter coefficients.
+\returns Newly-allocated %IIR filter coefficients.
 
 Uses the Exstrom labs code to compute the coefficients of an nth-order (param
 \a order) Butterworth-type low pass filter with gain \a gain and corner
@@ -41,7 +41,7 @@ greater than a 4th-order filter. This function won't do that directly for you.
 \a gain will usually be set to be 1.0.
 
 The corner frequency \a corner is expressed as a fraction of the sampling
-frequency (which is of course not known by the IIR code). It should lie between
+frequency (which is of course not known by the %IIR code). It should lie between
 0 (0Hz) and 1 (the Nyquist frequency, or ½ the sampling frequency).
 
 */
@@ -61,7 +61,7 @@ struct iir_coeff_t* iir_butterworth_lowpass(int order,
 \param gain Linear gain of filter.
 \param corner Corner frequency expressed as a fraction of Nyquist
     (0 ≤ \a corner ≤ 1)
-\returns Newly-allocated IIR filter coefficients.
+\returns Newly-allocated %IIR filter coefficients.
 
 Uses the Exstrom labs code to compute the coefficients of an nth-order (param
 \a order) Butterworth-type high pass filter with gain \a gain and corner
@@ -72,7 +72,7 @@ greater than a 4th-order filter. This function won't do that directly for you.
 \a gain will usually be set to be 1.0.
 
 The corner frequency \a corner is expressed as a fraction of the sampling
-frequency (which is of course not known by the IIR code). It should lie between
+frequency (which is of course not known by the %IIR code). It should lie between
 0 (0Hz) and 1 (the Nyquist frequency, or ½ the sampling frequency).
 
 */
@@ -94,7 +94,7 @@ struct iir_coeff_t* iir_butterworth_highpass(int order,
     (0 ≤ \a c1 ≤ 1)
 \param c2 High corner frequency expressed as a fraction of Nyquist
     (0 ≤ \a c2 ≤ 1, and \a c1 < \a c2)
-\returns Newly-allocated IIR filter coefficients.
+\returns Newly-allocated %IIR filter coefficients.
 
 Uses the Exstrom labs code to compute the coefficients of an nth-order (param
 \a order) Butterworth-type band pass filter with gain \a gain and corner
@@ -105,7 +105,7 @@ greater than a 4th-order filter. This function won't do that directly for you.
 \a gain will usually be set to be 1.0.
 
 The corner frequencies \a c1 and \a c2 are expressed as a fraction of the
-sampling frequency (which is of course not known by the IIR code). They should
+sampling frequency (which is of course not known by the %IIR code). They should
 lie between 0 (0Hz) and 1 (the Nyquist frequency, or ½ the sampling frequency),
 and \a c2 should be greater than \a c1.
 
@@ -129,7 +129,7 @@ struct iir_coeff_t* iir_butterworth_bandpass(int order,
     (0 ≤ \a c1 ≤ 1)
 \param c2 High corner frequency expressed as a fraction of Nyquist
     (0 ≤ \a c2 ≤ 1, and \a c1 < \a c2)
-\returns Newly-allocated IIR filter coefficients.
+\returns Newly-allocated %IIR filter coefficients.
 
 Uses the Exstrom labs code to compute the coefficients of an nth-order (param
 \a order) Butterworth-type band stop filter with gain \a gain and corner
@@ -140,7 +140,7 @@ greater than a 4th-order filter. This function won't do that directly for you.
 \a gain will usually be set to be 1.0.
 
 The corner frequencies \a c1 and \a c2 are expressed as a fraction of the
-sampling frequency (which is of course not known by the IIR code). They should
+sampling frequency (which is of course not known by the %IIR code). They should
 lie between 0 (0Hz) and 1 (the Nyquist frequency, or ½ the sampling frequency),
 and \a c2 should be greater than \a c1.
 

src/libiir/400_parser.h

@@ -11,9 +11,9 @@
 
 \ingroup libiir
 
-This is a high-level interface that can instantiate a set of IIR filters based
+This is a high-level interface that can instantiate a set of %IIR filters based
 on a user-specified, human-readable string. The intention of this interface is
-to allow IIR filters to be specified in configuration files so that they can be
+to allow %IIR filters to be specified in configuration files so that they can be
 easily modified by the user and easily understood/parsed by the system.
 
 See \ref string_desc for details on the string description format.
@@ -23,14 +23,14 @@ See \ref string_desc for details on the string description format.
 
 
 
-/*! \brief Instantiate an IIR filter based on a string description
+/*! \brief Instantiate an %IIR filter based on a string description
 
-\param desc IIR filter description.
+\param desc %IIR filter description.
-\returns Pointer to newly-allocated IIR filter instance.
+\returns Pointer to newly-allocated %IIR filter instance.
 \retval 0 on error.
 
-Parses the human-readable description of an IIR filter chain in \a desc,
+Parses the human-readable description of an %IIR filter chain in \a desc,
-instantiating an IIR filter object to match. Returns the new filter. If \a desc
+instantiating an %IIR filter object to match. Returns the new filter. If \a desc
 cannot be parsed correctly, returns 0 and sets \a errno to \c EINVAL.
 
 */
@@ -42,15 +42,15 @@ struct iir_filter_t* iir_parse(const char* desc)
 
 
 
-/*! \brief Instantiate a set of IIR filters based on a string description
+/*! \brief Instantiate a set of %IIR filters based on a string description
 
-\param desc IIR filter description.
+\param desc %IIR filter description.
 \param n Number of instances to allocate.
-\returns Pointer to array of \a n newly-allocated IIR filter instances.
+\returns Pointer to array of \a n newly-allocated %IIR filter instances.
 \retval 0 on error.
 
-Parses the human-readable description of an IIR filter chain in \a desc,
+Parses the human-readable description of an %IIR filter chain in \a desc,
-instantiating a set of \a n identical IIR filter objects to match. Returns a
+instantiating a set of \a n identical %IIR filter objects to match. Returns a
 pointer to an array of new filters. If \a desc cannot be parsed correctly,
 returns 0 and sets \a errno to \c EINVAL.
 

src/libiir/500_response.h

@@ -11,7 +11,7 @@
 
 \ingroup libiir
 
-These functions allow measuring the IIR response (i.e. frequency and phase of
+These functions allow measuring the %IIR response (i.e. frequency and phase of
 the transfer function) at a given frequency. The response is a complex number;
 see \c complex(5) for details. The magnitude \c cabs(z) is the gain of the
 filter and the phase \c carg(z) its phase delay.