Index: src/pitchfcomb.c
===================================================================
--- src/pitchfcomb.c	(revision 7cded32206cb485ddfde9a26bb0dbe9506ea9b1b)
+++ src/pitchfcomb.c	(revision 7f3ccc5e83ab732b4d7b7c3766f25571caff1f8e)
@@ -15,14 +15,4 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
-
-*/
-
-/* 
-  
-   This file was taken from the tuneit project, in the file
-   tuneit.c -- Detect fundamental frequency of a sound
-   see http://delysid.org/tuneit.html 
-  
-   a fast harmonic comb filter algorithm for pitch tracking
 
 */
Index: src/pitchfcomb.h
===================================================================
--- src/pitchfcomb.h	(revision 7cded32206cb485ddfde9a26bb0dbe9506ea9b1b)
+++ src/pitchfcomb.h	(revision 7f3ccc5e83ab732b4d7b7c3766f25571caff1f8e)
@@ -18,4 +18,18 @@
 */
 
+/** \file
+
+   Pitch detection using a fast harmonic comb filter
+
+   This pitch extraction method implements a fast harmonic comb filter to
+   determine the fundamental frequency of a harmonic sound.
+
+   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 
+
+*/
+
 #ifndef _PITCHFCOMB_H
 #define _PITCHFCOMB_H
@@ -25,8 +39,27 @@
 #endif
 
+/** pitch detection object */
 typedef struct _aubio_pitchfcomb_t aubio_pitchfcomb_t;
 
+/** 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) 
+ 
+*/
 smpl_t aubio_pitchfcomb_detect (aubio_pitchfcomb_t *p, fvec_t * input);
+/** creation of the pitch detection object
+ 
+  \param bufsize size of the input buffer to analyse 
+  \param hopsize step size between two consecutive analysis instant 
+  \param samplerate sampling rate of the signal 
+ 
+*/
 aubio_pitchfcomb_t * new_aubio_pitchfcomb (uint_t bufsize, uint_t hopsize, uint_t samplerate);
+/** 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);
 
Index: src/pitchmcomb.c
===================================================================
--- src/pitchmcomb.c	(revision 7cded32206cb485ddfde9a26bb0dbe9506ea9b1b)
+++ src/pitchmcomb.c	(revision 7f3ccc5e83ab732b4d7b7c3766f25571caff1f8e)
@@ -161,5 +161,5 @@
   vec_alpha_normalise(mag,p->alpha); /* alpha normalisation  */
   /* skipped */                      /* low pass filtering   */
-  /** \bug: vec_movind_thres writes out of bounds */
+  /** \bug vec_moving_thres may write out of bounds */
   vec_adapt_thres(mag,tmp,p->win_post,p->win_pre); /* adaptative threshold */
   vec_add(mag,-p->threshold);        /* fixed threshold      */
@@ -325,5 +325,5 @@
 aubio_pitchmcomb_t * new_aubio_pitchmcomb(uint_t bufsize, uint_t hopsize, uint_t channels, uint_t samplerate) {
   aubio_pitchmcomb_t * p = AUBIO_NEW(aubio_pitchmcomb_t);
-  /** \bug should check if size / 8 > post+pre+1 */
+  /* bug: should check if size / 8 > post+pre+1 */
   uint_t i;
   uint_t spec_size;
Index: src/pitchmcomb.h
===================================================================
--- src/pitchmcomb.h	(revision 7cded32206cb485ddfde9a26bb0dbe9506ea9b1b)
+++ src/pitchmcomb.h	(revision 7f3ccc5e83ab732b4d7b7c3766f25571caff1f8e)
@@ -19,8 +19,17 @@
 
 /** \file
- * spectral pitch detection function
- * 
- * \todo check/fix peak picking
- */
+
+  Pitch detection using multiple-comb filter
+
+  This fundamental frequency estimation algorithm implements spectral
+  flattening, multi-comb filtering and peak histogramming. 
+
+  This method was designed by Juan P. Bello and described in:
+
+  Juan-Pablo Bello. ``Towards the Automated Analysis of Simple Polyphonic
+  Music''.  PhD thesis, Centre for Digital Music, Queen Mary University of
+  London, London, UK, 2003.
+
+*/
 
 #ifndef PITCHMCOMB_H
@@ -31,9 +40,29 @@
 #endif
 
+/** pitch detection object */
 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 
+ 
+*/
 smpl_t aubio_pitchmcomb_detect(aubio_pitchmcomb_t * p, cvec_t * fftgrain);
 uint_t aubio_pitch_cands(aubio_pitchmcomb_t * p, cvec_t * fftgrain, smpl_t * cands);
+/** creation of the pitch detection object
+ 
+  \param bufsize size of the input buffer to analyse 
+  \param hopsize step size between two consecutive analysis instant 
+  \param channels number of channels to analyse
+  \param samplerate sampling rate of the signal 
+ 
+*/
 aubio_pitchmcomb_t * new_aubio_pitchmcomb(uint_t bufsize, uint_t hopsize, uint_t channels, uint_t samplerate);
+/** 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);
 
Index: src/pitchyin.h
===================================================================
--- src/pitchyin.h	(revision 7cded32206cb485ddfde9a26bb0dbe9506ea9b1b)
+++ src/pitchyin.h	(revision 7f3ccc5e83ab732b4d7b7c3766f25571caff1f8e)
@@ -17,12 +17,17 @@
 */
 
-/* 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.  
- *
- * see http://recherche.ircam.fr/equipes/pcm/pub/people/cheveign.html
- */
+/** \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.  
+ 
+  see http://recherche.ircam.fr/equipes/pcm/pub/people/cheveign.html
+
+*/
 
 #ifndef PITCHYIN_H
@@ -33,10 +38,33 @@
 #endif
 
+/** compute difference function
+  
+  \param input input signal 
+  \param yinbuf output buffer to store difference function (half shorter than input)
+
+*/
 void aubio_pitchyin_diff(fvec_t * input, fvec_t * yinbuf);
 
+/** in place computation of the YIN cumulative normalised function 
+  
+  \param yinbuf input signal (a square difference function), also used to store function 
+
+*/
 void aubio_pitchyin_getcum(fvec_t * yinbuf);
 
+/** detect pitch in a YIN function
+  
+  \param yinbuf input buffer as computed by aubio_pitchyin_getcum
+
+*/
 uint_t aubio_pitchyin_getpitch(fvec_t *yinbuf);
 
+/** fast implementation of the YIN algorithm 
+  
+  \param input input signal 
+  \param yinbuf input buffer used to compute the YIN function
+  \param tol tolerance parameter for minima selection [default 0.15]
+
+*/
 smpl_t aubio_pitchyin_getpitchfast(fvec_t * input, fvec_t *yinbuf, smpl_t tol);
 
Index: src/pitchyinfft.c
===================================================================
--- src/pitchyinfft.c	(revision 7cded32206cb485ddfde9a26bb0dbe9506ea9b1b)
+++ src/pitchyinfft.c	(revision 7f3ccc5e83ab732b4d7b7c3766f25571caff1f8e)
@@ -16,17 +16,4 @@
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */
-
-/* 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.  
- *
- * see http://recherche.ircam.fr/equipes/pcm/pub/people/cheveign.html
- *
- * This implementation is using an FFT to compute the square difference
- * function, which allows spectral weighting 
- * 
- */
 
 #include "aubio_priv.h"
@@ -139,5 +126,5 @@
 	  /* 3 point quadratic interpolation */
 	  //return vec_quadint_min(yin,tau,1);
-	  /* additional check nlikely octave doubling in higher frequencies */
+	  /* additional check for (unlikely) octave doubling in higher frequencies */
 	  if (tau>35) {
 		  return vec_quadint_min(yin,tau,1)+1;
Index: src/pitchyinfft.h
===================================================================
--- src/pitchyinfft.h	(revision 7cded32206cb485ddfde9a26bb0dbe9506ea9b1b)
+++ src/pitchyinfft.h	(revision 7f3ccc5e83ab732b4d7b7c3766f25571caff1f8e)
@@ -17,12 +17,18 @@
 */
 
-/* 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.  
- *
- * see http://recherche.ircam.fr/equipes/pcm/pub/people/cheveign.html
- */
+/** \file
+ 
+  Pitch detection using a spectral implementation of the YIN algorithm
+  
+  This algorithm was derived from the YIN algorithm (see pitchyin.c). In this
+  implementation, a Fourier transform is used to compute a tapered square
+  difference function, which allows spectral weighting. Because the difference
+  function is tapered, the selection of the period is simplified.
+ 
+  Paul Brossier, ``Automatic annotation of musical audio for interactive
+  systems'', Chapter 3, Pitch Analysis, PhD thesis, Centre for Digital music,
+  Queen Mary University of London, London, UK, 2003.
+
+*/
 
 #ifndef PITCHYINFFT_H
@@ -33,7 +39,20 @@
 #endif
 
+/** pitch detection object */
 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 tol tolerance parameter for minima selection [default 0.85] 
+ 
+*/
 smpl_t aubio_pitchyinfft_detect (aubio_pitchyinfft_t *p, fvec_t * input, smpl_t tol);
+/** creation of the pitch detection object
+ 
+  \param bufsize size of the input buffer to analyse 
+ 
+*/
 aubio_pitchyinfft_t * new_aubio_pitchyinfft (uint_t bufsize);
 void del_aubio_pitchyinfft (aubio_pitchyinfft_t *p);
