From: Paul Brossier <piem@piem.org>
Date: Sun, 3 Mar 2013 03:44:18 +0000 (-0500)
Subject: src/*/*.h: add link to examples, remove trailing spaces, improve documentation
X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=69b11d8946d92586bc51bbc9d5f1c54185226ca9;p=aubio.git

src/*/*.h: add link to examples, remove trailing spaces, improve documentation
---

diff --git a/src/io/sink.h b/src/io/sink.h
index 8c98027e..5db236e3 100644
--- a/src/io/sink.h
+++ b/src/io/sink.h
@@ -29,6 +29,8 @@ extern "C" {
 
   Media sink
 
+  \example io/test-sink.c
+
 */
 
 typedef struct _aubio_sink_t aubio_sink_t;
diff --git a/src/onset/onset.h b/src/onset/onset.h
index c5ed9f4b..703442f0 100644
--- a/src/onset/onset.h
+++ b/src/onset/onset.h
@@ -20,17 +20,20 @@
 
 /** \file
  
-  Onset detection driver
+  Onset detection object
 
   The following routines compute the onset detection function and detect peaks
   in these functions. When onsets are found above a given silence threshold,
   and after a minimum inter-onset interval, the output vector returned by
-  aubio_onset_do is filled with 1. Otherwise, the output vector remains 0.
+  ::aubio_onset_do is filled with `1`. Otherwise, the output vector remains
+  `0`.
 
   The peak-picking threshold, the silence threshold, and the minimum
   inter-onset interval can be adjusted during the execution of the
   aubio_onset_do routine using the corresponding functions.
 
+  \example onset/test-onset.c
+
 */
 
 
diff --git a/src/onset/peakpicker.h b/src/onset/peakpicker.h
index 74fdfffb..63b3b9b2 100644
--- a/src/onset/peakpicker.h
+++ b/src/onset/peakpicker.h
@@ -21,6 +21,8 @@
 /** \file 
  
   Peak picking utilities function
+
+  \example onset/test-peakpicker.c
   
 */
 
diff --git a/src/pitch/pitch.h b/src/pitch/pitch.h
index b00c45a0..01670352 100644
--- a/src/pitch/pitch.h
+++ b/src/pitch/pitch.h
@@ -32,6 +32,8 @@ extern "C" {
   This file creates the objects required for the computation of the selected
   pitch detection algorithm and output the results, in midi note or Hz.
 
+  \example pitch/test-pitch.c
+
 */
 
 /** pitch detection object */
diff --git a/src/pitch/pitchfcomb.h b/src/pitch/pitchfcomb.h
index 14c27c96..471208f9 100644
--- a/src/pitch/pitchfcomb.h
+++ b/src/pitch/pitchfcomb.h
@@ -27,8 +27,10 @@
 
    This file was derived from the tuneit project, written by Mario Lang to
    detect the fundamental frequency of a sound.
-   
-   see http://delysid.org/tuneit.html 
+
+   See http://delysid.org/tuneit.html
+
+   \example pitch/test-pitchfcomb.c
 
 */
 
@@ -42,28 +44,28 @@ extern "C" {
 /** pitch detection object */
 typedef struct _aubio_pitchfcomb_t aubio_pitchfcomb_t;
 
-/** execute pitch detection on an input buffer 
- 
+/** execute pitch detection on an input buffer
+
   \param p pitch detection object as returned by new_aubio_pitchfcomb
-  \param input input signal window (length as specified at creation time) 
+  \param input input signal window (length as specified at creation time)
   \param output pitch candidates in bins
- 
+
 */
 void aubio_pitchfcomb_do (aubio_pitchfcomb_t * p, fvec_t * input,
     fvec_t * output);
 
 /** creation of the pitch detection object
- 
-  \param buf_size size of the input buffer to analyse 
-  \param hop_size step size between two consecutive analysis instant 
- 
+
+  \param buf_size size of the input buffer to analyse
+  \param hop_size step size between two consecutive analysis instant
+
 */
 aubio_pitchfcomb_t *new_aubio_pitchfcomb (uint_t buf_size, uint_t hop_size);
 
 /** deletion of the pitch detection object
- 
+
   \param p pitch detection object as returned by new_aubio_pitchfcomb
- 
+
 */
 void del_aubio_pitchfcomb (aubio_pitchfcomb_t * p);
 
diff --git a/src/pitch/pitchmcomb.h b/src/pitch/pitchmcomb.h
index a183f165..48809aab 100644
--- a/src/pitch/pitchmcomb.h
+++ b/src/pitch/pitchmcomb.h
@@ -23,7 +23,7 @@
   Pitch detection using multiple-comb filter
 
   This fundamental frequency estimation algorithm implements spectral
-  flattening, multi-comb filtering and peak histogramming. 
+  flattening, multi-comb filtering and peak histogramming.
 
   This method was designed by Juan P. Bello and described in:
 
@@ -31,6 +31,8 @@
   Music''.  PhD thesis, Centre for Digital Music, Queen Mary University of
   London, London, UK, 2003.
 
+  \example pitch/test-pitchmcomb.c
+
 */
 
 #ifndef PITCHMCOMB_H
@@ -44,27 +46,27 @@ extern "C" {
 typedef struct _aubio_pitchmcomb_t aubio_pitchmcomb_t;
 
 /** execute pitch detection on an input spectral frame
- 
+
   \param p pitch detection object as returned by new_aubio_pitchmcomb
-  \param fftgrain input signal spectrum as computed by aubio_pvoc_do 
- 
+  \param in_fftgrain input signal spectrum as computed by aubio_pvoc_do
+  \param out_cands pitch candidate frequenciess, in bins
+
 */
-void aubio_pitchmcomb_do (aubio_pitchmcomb_t * p, cvec_t * fftgrain,
-    fvec_t * output);
+void aubio_pitchmcomb_do (aubio_pitchmcomb_t * p, cvec_t * in_fftgrain,
+    fvec_t * out_cands);
 
 /** creation of the pitch detection object
- 
-  \param buf_size size of the input buffer to analyse 
-  \param hop_size step size between two consecutive analysis instant 
-  \param samplerate sampling rate of the signal 
- 
+
+  \param buf_size size of the input buffer to analyse
+  \param hop_size step size between two consecutive analysis instant
+
 */
 aubio_pitchmcomb_t *new_aubio_pitchmcomb (uint_t buf_size, uint_t hop_size);
 
 /** deletion of the pitch detection object
- 
+
   \param p pitch detection object as returned by new_aubio_pitchfcomb
- 
+
 */
 void del_aubio_pitchmcomb (aubio_pitchmcomb_t * p);
 
@@ -72,4 +74,4 @@ void del_aubio_pitchmcomb (aubio_pitchmcomb_t * p);
 }
 #endif
 
-#endif/*PITCHMCOMB_H*/ 
+#endif /* PITCHMCOMB_H */
diff --git a/src/pitch/pitchschmitt.h b/src/pitch/pitchschmitt.h
index 03b42e62..5a9ee561 100644
--- a/src/pitch/pitchschmitt.h
+++ b/src/pitch/pitchschmitt.h
@@ -18,17 +18,19 @@
 
 */
 
-/** \file 
+/** \file
+
+   Pitch detection using a Schmitt trigger
 
-   Pitch detection using a Schmitt trigger 
- 
    This pitch extraction method implements a Schmitt trigger to estimate the
    period of a signal.
 
    This file was derived from the tuneit project, written by Mario Lang to
    detect the fundamental frequency of a sound.
-   
-   see http://delysid.org/tuneit.html 
+
+   See http://delysid.org/tuneit.html
+
+   \example pitch/test-pitchschmitt.c
 
 */
 
@@ -42,27 +44,27 @@ extern "C" {
 /** pitch detection object */
 typedef struct _aubio_pitchschmitt_t aubio_pitchschmitt_t;
 
-/** execute pitch detection on an input buffer 
- 
-  \param p pitch detection object as returned by new_aubio_pitchschmitt 
-  \param input input signal window (length as specified at creation time) 
-  \param output pitch period estimates, in samples
- 
+/** execute pitch detection on an input buffer
+
+  \param p pitch detection object as returned by new_aubio_pitchschmitt
+  \param samples_in input signal vector (length as specified at creation time)
+  \param cands_out pitch period estimates, in samples
+
 */
-void aubio_pitchschmitt_do (aubio_pitchschmitt_t * p, fvec_t * in,
-    fvec_t * out);
+void aubio_pitchschmitt_do (aubio_pitchschmitt_t * p, fvec_t * samples_in,
+    fvec_t * cands_out);
 
 /** creation of the pitch detection object
- 
-  \param buf_size size of the input buffer to analyse 
- 
+
+  \param buf_size size of the input buffer to analyse
+
 */
 aubio_pitchschmitt_t *new_aubio_pitchschmitt (uint_t buf_size);
 
 /** deletion of the pitch detection object
- 
-  \param p pitch detection object as returned by new_aubio_pitchschmitt 
- 
+
+  \param p pitch detection object as returned by new_aubio_pitchschmitt
+
 */
 void del_aubio_pitchschmitt (aubio_pitchschmitt_t * p);
 
diff --git a/src/pitch/pitchyin.h b/src/pitch/pitchyin.h
index 4e858408..b5216d38 100644
--- a/src/pitch/pitchyin.h
+++ b/src/pitch/pitchyin.h
@@ -18,16 +18,16 @@
 
 */
 
-/** \file 
-  
+/** \file
+
   Pitch detection using the YIN algorithm
- 
+
   This algorithm was developped by A. de Cheveigne and H. Kawahara and
   published in:
-  
+
   De Cheveigné, A., Kawahara, H. (2002) "YIN, a fundamental frequency
-  estimator for speech and music", J. Acoust. Soc. Am. 111, 1917-1930.  
- 
+  estimator for speech and music", J. Acoust. Soc. Am. 111, 1917-1930.
+
   see http://recherche.ircam.fr/equipes/pcm/pub/people/cheveign.html
 
 */
@@ -43,40 +43,40 @@ extern "C" {
 typedef struct _aubio_pitchyin_t aubio_pitchyin_t;
 
 /** creation of the pitch detection object
- 
-  \param buf_size size of the input buffer to analyse 
- 
+
+  \param buf_size size of the input buffer to analyse
+
 */
 aubio_pitchyin_t *new_aubio_pitchyin (uint_t buf_size);
 
 /** deletion of the pitch detection object
- 
-  \param p pitch detection object as returned by new_aubio_pitchyin()
- 
+
+  \param o pitch detection object as returned by new_aubio_pitchyin()
+
 */
 void del_aubio_pitchyin (aubio_pitchyin_t * o);
 
-/** execute pitch detection on an input buffer 
- 
-  \param p pitch detection object as returned by new_aubio_pitchyin()
-  \param input input signal window (length as specified at creation time) 
-  \param tol tolerance parameter for minima selection [default 0.85] 
- 
+/** execute pitch detection an input buffer
+
+  \param o pitch detection object as returned by new_aubio_pitchyin()
+  \param samples_in input signal vector (length as specified at creation time)
+  \param cands_out pitch period candidates, in samples
+
 */
-void aubio_pitchyin_do (aubio_pitchyin_t * o, fvec_t * in, fvec_t * out);
+void aubio_pitchyin_do (aubio_pitchyin_t * o, fvec_t * samples_in, fvec_t * cands_out);
+
 
+/** set tolerance parameter for YIN algorithm
 
-/** set tolerance parameter for YIN algorithm 
-  
-  \param o YIN pitch detection object 
+  \param o YIN pitch detection object
   \param tol tolerance parameter for minima selection [default 0.15]
 
 */
 uint_t aubio_pitchyin_set_tolerance (aubio_pitchyin_t * o, smpl_t tol);
 
-/** get tolerance parameter for YIN algorithm 
-  
-  \param o YIN pitch detection object 
+/** get tolerance parameter for YIN algorithm
+
+  \param o YIN pitch detection object
   \return tolerance parameter for minima selection [default 0.15]
 
 */
@@ -86,4 +86,4 @@ smpl_t aubio_pitchyin_get_tolerance (aubio_pitchyin_t * o);
 }
 #endif
 
-#endif /*PITCHYIN_H*/ 
+#endif /*PITCHYIN_H*/
diff --git a/src/pitch/pitchyinfft.h b/src/pitch/pitchyinfft.h
index bd7b5f17..8ce51dde 100644
--- a/src/pitch/pitchyinfft.h
+++ b/src/pitch/pitchyinfft.h
@@ -45,12 +45,12 @@ typedef struct _aubio_pitchyinfft_t aubio_pitchyinfft_t;
 
 /** execute pitch detection on an input buffer 
  
-  \param p pitch detection object as returned by new_aubio_pitchyinfft
-  \param input input signal window (length as specified at creation time) 
-  \param output pitch period candidates, in samples
+  \param o pitch detection object as returned by new_aubio_pitchyinfft
+  \param samples_in input signal vector (length as specified at creation time)
+  \param cands_out pitch period candidates, in samples
  
 */
-void aubio_pitchyinfft_do (aubio_pitchyinfft_t * p, fvec_t * in, fvec_t * out);
+void aubio_pitchyinfft_do (aubio_pitchyinfft_t * o, fvec_t * samples_in, fvec_t * cands_out);
 /** creation of the pitch detection object
  
   \param buf_size size of the input buffer to analyse 
@@ -59,10 +59,10 @@ void aubio_pitchyinfft_do (aubio_pitchyinfft_t * p, fvec_t * in, fvec_t * out);
 aubio_pitchyinfft_t *new_aubio_pitchyinfft (uint_t buf_size);
 /** deletion of the pitch detection object
  
-  \param p pitch detection object as returned by new_aubio_pitchyinfft()
+  \param o pitch detection object as returned by new_aubio_pitchyinfft()
  
 */
-void del_aubio_pitchyinfft (aubio_pitchyinfft_t * p);
+void del_aubio_pitchyinfft (aubio_pitchyinfft_t * o);
 
 /** get tolerance parameter for YIN algorithm 
   
@@ -71,7 +71,7 @@ void del_aubio_pitchyinfft (aubio_pitchyinfft_t * p);
   \return tolerance parameter for minima selection [default 0.15]
 
 */
-smpl_t aubio_pitchyinfft_get_tolerance (aubio_pitchyinfft_t * p);
+smpl_t aubio_pitchyinfft_get_tolerance (aubio_pitchyinfft_t * o);
 
 /** set tolerance parameter for YIN algorithm 
   
@@ -79,7 +79,7 @@ smpl_t aubio_pitchyinfft_get_tolerance (aubio_pitchyinfft_t * p);
   \param tol tolerance parameter for minima selection [default 0.15]
 
 */
-uint_t aubio_pitchyinfft_set_tolerance (aubio_pitchyinfft_t * p, smpl_t tol);
+uint_t aubio_pitchyinfft_set_tolerance (aubio_pitchyinfft_t * o, smpl_t tol);
 
 #ifdef __cplusplus
 }
diff --git a/src/tempo/tempo.h b/src/tempo/tempo.h
index d6d01f68..31269b2f 100644
--- a/src/tempo/tempo.h
+++ b/src/tempo/tempo.h
@@ -25,6 +25,8 @@
   This object stores all the memory required for tempo detection algorithm
   and returns the estimated beat locations.
 
+  \example tempo/test-tempo.h
+
 */
 
 #ifndef TEMPO_H
diff --git a/src/temporal/biquad.h b/src/temporal/biquad.h
index b3004ac2..42cb36f9 100644
--- a/src/temporal/biquad.h
+++ b/src/temporal/biquad.h
@@ -35,6 +35,8 @@
   See also <a href="http://en.wikipedia.org/wiki/Digital_biquad_filter">Digital
   biquad filter</a> on wikipedia.
 
+  \example temporal/test-biquad.c
+
 */
 
 #ifdef __cplusplus
@@ -54,7 +56,7 @@ extern "C" {
 uint_t aubio_filter_set_biquad (aubio_filter_t * f, lsmp_t b0, lsmp_t b1,
     lsmp_t b2, lsmp_t a1, lsmp_t a2);
 
-/** create new biquad filter
+/** create biquad filter with `b0`, `b1`, `b2`, `a1`, `a2` coeffs
 
   \param b0 forward filter coefficient
   \param b1 forward filter coefficient