From f44b11162c98da00bdc88cd54c584a8257f92433 Mon Sep 17 00:00:00 2001
From: Paul Brossier <piem@altern.org>
Date: Wed, 17 May 2006 19:44:51 +0000
Subject: [PATCH] update pitchdetection docs, make wrapper methods private
 update pitchdetection docs, make wrapper methods private

---
 src/pitchdetection.c |  8 ++++-
 src/pitchdetection.h | 74 ++++++++++++++++++++++++++++++++------------
 swig/aubio.i         |  2 --
 3 files changed, 61 insertions(+), 23 deletions(-)

diff --git a/src/pitchdetection.c b/src/pitchdetection.c
index 8b400cdf..70b06d67 100644
--- a/src/pitchdetection.c
+++ b/src/pitchdetection.c
@@ -33,6 +33,12 @@ typedef smpl_t (*aubio_pitchdetection_func_t)(aubio_pitchdetection_t *p,
 typedef smpl_t (*aubio_pitchdetection_conv_t)(smpl_t value,uint_t srate,uint_t bufsize);
 void aubio_pitchdetection_slideblock(aubio_pitchdetection_t *p, fvec_t *ibuf);
 
+smpl_t aubio_pitchdetection_mcomb(aubio_pitchdetection_t *p, fvec_t * ibuf);
+smpl_t aubio_pitchdetection_yin(aubio_pitchdetection_t *p, fvec_t *ibuf);
+smpl_t aubio_pitchdetection_schmitt(aubio_pitchdetection_t *p, fvec_t *ibuf);
+smpl_t aubio_pitchdetection_fcomb(aubio_pitchdetection_t *p, fvec_t *ibuf);
+smpl_t aubio_pitchdetection_yinfft(aubio_pitchdetection_t *p, fvec_t *ibuf);
+
 struct _aubio_pitchdetection_t {
 	aubio_pitchdetection_type type;
 	aubio_pitchdetection_mode mode;
@@ -124,7 +130,7 @@ aubio_pitchdetection_t * new_aubio_pitchdetection(uint_t bufsize,
                         p->freqconv = freqconvmidi;
                         break;
 		case aubio_pitchm_cent:
-                        /** bug: not implemented */
+                        /* bug: not implemented */
                         p->freqconv = freqconvmidi;
                         break;
 		case aubio_pitchm_bin:
diff --git a/src/pitchdetection.h b/src/pitchdetection.h
index d6403452..92e760fe 100644
--- a/src/pitchdetection.h
+++ b/src/pitchdetection.h
@@ -23,39 +23,73 @@
 extern "C" {
 #endif
 
+/** \file
+
+  Generic method for pitch detection  
+
+  This file creates the objects required for the computation of the selected
+  pitch detection algorithm and output the results, in midi note or Hz.
+
+*/
+
+/** pitch detection algorithm */
 typedef enum {
-        aubio_pitch_yin,
-        aubio_pitch_mcomb,
-        aubio_pitch_schmitt,
-        aubio_pitch_fcomb,
-	aubio_pitch_yinfft
+        aubio_pitch_yin,     /**< YIN algorithm */
+        aubio_pitch_mcomb,   /**< Multi-comb filter */
+        aubio_pitch_schmitt, /**< Schmitt trigger */
+        aubio_pitch_fcomb,   /**< Fast comb filter */
+        aubio_pitch_yinfft   /**< Spectral YIN */
 } aubio_pitchdetection_type;
 
+/** pitch detection output mode */
 typedef enum {
-        aubio_pitchm_freq,
-        aubio_pitchm_midi,
-        aubio_pitchm_cent,
-        aubio_pitchm_bin
+        aubio_pitchm_freq,   /**< Frequency (Hz) */
+        aubio_pitchm_midi,   /**< MIDI note (0.,127) */
+        aubio_pitchm_cent,   /**< Cent */
+        aubio_pitchm_bin     /**< Frequency bin (0,bufsize) */
 } aubio_pitchdetection_mode;
 
+/** pitch detection object */
 typedef struct _aubio_pitchdetection_t aubio_pitchdetection_t;
-	
+
+/** execute pitch detection on an input signal frame
+ 
+  \param p pitch detection object as returned by new_aubio_pitchdetection
+  \param ibuf input signal of length hopsize 
+ 
+*/
 smpl_t aubio_pitchdetection(aubio_pitchdetection_t * p, fvec_t * ibuf);
-smpl_t aubio_pitchdetection_mcomb(aubio_pitchdetection_t *p, fvec_t * ibuf);
-smpl_t aubio_pitchdetection_yin(aubio_pitchdetection_t *p, fvec_t *ibuf);
-smpl_t aubio_pitchdetection_schmitt(aubio_pitchdetection_t *p, fvec_t *ibuf);
-smpl_t aubio_pitchdetection_fcomb(aubio_pitchdetection_t *p, fvec_t *ibuf);
-smpl_t aubio_pitchdetection_yinfft(aubio_pitchdetection_t *p, fvec_t *ibuf);
 
+/** change yin or yinfft tolerance threshold
+  
+  default is 0.15 for yin and 0.85 for yinfft
+ 
+*/
 void aubio_pitchdetection_set_yinthresh(aubio_pitchdetection_t *p, smpl_t thres);
+
+/** deletion of the pitch detection object
+ 
+  \param p pitch detection object as returned by new_aubio_pitchdetection
+ 
+*/
 void del_aubio_pitchdetection(aubio_pitchdetection_t * p);
 
+/** 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 
+  \param type set pitch detection algorithm
+  \param mode set pitch units for output
+ 
+*/
 aubio_pitchdetection_t * new_aubio_pitchdetection(uint_t bufsize, 
-		uint_t hopsize, 
-		uint_t channels,
-		uint_t samplerate,
-		aubio_pitchdetection_type type,
-		aubio_pitchdetection_mode mode);
+        uint_t hopsize, 
+        uint_t channels,
+        uint_t samplerate,
+        aubio_pitchdetection_type type,
+        aubio_pitchdetection_mode mode);
 
 #ifdef __cplusplus
 }
diff --git a/swig/aubio.i b/swig/aubio.i
index 9edcd9f0..b628a08e 100644
--- a/swig/aubio.i
+++ b/swig/aubio.i
@@ -203,8 +203,6 @@ typedef enum {
 } aubio_pitchdetection_mode;
 
 smpl_t aubio_pitchdetection(aubio_pitchdetection_t * p, fvec_t * ibuf);
-smpl_t aubio_pitchdetection_mcomb(aubio_pitchdetection_t *p, fvec_t * ibuf);
-smpl_t aubio_pitchdetection_yin(aubio_pitchdetection_t *p, fvec_t *ibuf);
 
 void aubio_pitchdetection_set_yinthresh(aubio_pitchdetection_t *p, smpl_t thres);
 
-- 
2.26.2