From c0608bdf055470fc0678853870ed286dcf4c47c4 Mon Sep 17 00:00:00 2001
From: Paul Brossier <piem@piem.org>
Date: Sat, 2 Mar 2013 14:18:00 -0500
Subject: [PATCH] src/spectral/: improve documentation

---
 src/spectral/filterbank_mel.h | 16 ++++++++--------
 src/spectral/specdesc.h       | 13 +++++++++++--
 2 files changed, 19 insertions(+), 10 deletions(-)

diff --git a/src/spectral/filterbank_mel.h b/src/spectral/filterbank_mel.h
index 56e29133..6d338cdd 100644
--- a/src/spectral/filterbank_mel.h
+++ b/src/spectral/filterbank_mel.h
@@ -21,13 +21,11 @@
 
 /** \file
 
-  Mel frequency filter bankd coefficients 
+  Filterbank object coefficients initialization
 
-  Set filter bank coefficients to Mel frequency bands.
-
-  The filter coefficients are built according to Malcolm Slaney's Auditory
-  Toolbox available at http://cobweb.ecn.purdue.edu/~malcolm/interval/1998-010/
-  (see the file mfcc.m). 
+  Functions to create set the ::aubio_filterbank_t coefficients to
+    - ::aubio_filterbank_set_triangle_bands: overlapping triangular bands,
+    - ::aubio_filterbank_set_mel_coeffs_slaney: Mel frequency bands.
 
 */
 
@@ -57,7 +55,9 @@ uint_t aubio_filterbank_set_triangle_bands (aubio_filterbank_t * fb,
   \param fb filterbank object
   \param samplerate audio sampling rate
 
-  This function fills the filterbank coefficients according to Malcolm Slaney.
+  The filter coefficients are built according to Malcolm Slaney's Auditory
+  Toolbox, available at http://cobweb.ecn.purdue.edu/~malcolm/interval/1998-010/
+  (see file mfcc.m).
 
 */
 uint_t aubio_filterbank_set_mel_coeffs_slaney (aubio_filterbank_t * fb,
@@ -67,4 +67,4 @@ uint_t aubio_filterbank_set_mel_coeffs_slaney (aubio_filterbank_t * fb,
 }
 #endif
 
-#endif                          // FILTERBANK_MEL_H
+#endif // FILTERBANK_MEL_H
diff --git a/src/spectral/specdesc.h b/src/spectral/specdesc.h
index c867d1ff..814f1909 100644
--- a/src/spectral/specdesc.h
+++ b/src/spectral/specdesc.h
@@ -26,9 +26,11 @@
   of a windowed signal (as created with aubio_pvoc). They output one smpl_t per
   buffer (stored in a vector of size [1]).
  
+  \section specdesc Spectral description functions
+
   A list of the spectral description methods currently available follows.
 
-  \section onsetdesc Onset detection functions
+  \subsection onsetdesc Onset detection functions
 
   These functions are designed to raise at notes attacks in music signals.
 
@@ -81,7 +83,7 @@
   International Conference on Digital Audio Effects'' (DAFx-06), Montreal,
   Canada, 2006. 
 
-  \section shapedesc Spectral shape descriptors
+  \subsection shapedesc Spectral shape descriptors
 
   The following descriptors are described in:
 
@@ -138,6 +140,8 @@
   This function returns the bin number below which 95% of the spectrum energy
   is found.
 
+  \example spectral/test-specdesc.c
+
 */
 
 
@@ -168,6 +172,11 @@ void aubio_specdesc_do (aubio_specdesc_t * o, cvec_t * fftgrain,
   \param method spectral description method
   \param buf_size length of the input spectrum frame
 
+  The parameter \p method is a string that can be any of:
+
+    - `energy`, `hfc`, `complex`, `phase`, `specdiff`, `kl`, `mkl`, `specflux`
+    - `centroid`, `spread`, `skewness`, `kurtosis`, `slope`, `decrease`, `rolloff`
+
 */
 aubio_specdesc_t *new_aubio_specdesc (char_t * method, uint_t buf_size);
 
-- 
2.26.2