Index: python/ext/aubiomodule.c
===================================================================
--- python/ext/aubiomodule.c	(revision 72d08ae2cbb7eae10ddabe5769088d933862e8fd)
+++ python/ext/aubiomodule.c	(revision 07382d8c0476840e5a86b3807577c988cc52e28a)
@@ -11,72 +11,192 @@
 
 static char Py_alpha_norm_doc[] = ""
-"alpha_norm(fvec, integer) -> float\n"
-"\n"
-"Compute alpha normalisation factor on vector, given alpha\n"
+"alpha_norm(vec, alpha)\n"
+"\n"
+"Compute `alpha` normalisation factor of vector `vec`.\n"
+"\n"
+"Parameters\n"
+"----------\n"
+"vec : fvec\n"
+"   input vector\n"
+"alpha : float\n"
+"   norm factor\n"
+"\n"
+"Returns\n"
+"-------\n"
+"float\n"
+"   p-norm of the input vector, where `p=alpha`\n"
 "\n"
 "Example\n"
 "-------\n"
 "\n"
-">>> b = alpha_norm(a, 9)";
+">>> a = aubio.fvec(np.arange(10)); alpha = 2\n"
+">>> aubio.alpha_norm(a, alpha), (sum(a**alpha)/len(a))**(1./alpha)\n"
+"(5.338539123535156, 5.338539126015656)\n"
+"\n"
+"Note\n"
+"----\n"
+"Computed as:\n"
+"\n"
+".. math::\n"
+"  l_{\\alpha} = \n"
+"       \\|\\frac{\\sum_{n=0}^{N-1}{{x_n}^{\\alpha}}}{N}\\|^{1/\\alpha}\n"
+"";
 
 static char Py_bintomidi_doc[] = ""
-"bintomidi(float, samplerate = integer, fftsize = integer) -> float\n"
-"\n"
-"Convert bin (float) to midi (float), given the sampling rate and the FFT size\n"
+"bintomidi(fftbin, samplerate, fftsize)\n"
+"\n"
+"Convert FFT bin to frequency in midi note, given the sampling rate\n"
+"and the size of the FFT.\n"
+"\n"
+"Parameters\n"
+"----------\n"
+"fftbin : float\n"
+"   input frequency bin\n"
+"samplerate : float\n"
+"   sampling rate of the signal\n"
+"fftsize : float\n"
+"   size of the FFT\n"
+"\n"
+"Returns\n"
+"-------\n"
+"float\n"
+"   Frequency converted to midi note.\n"
 "\n"
 "Example\n"
 "-------\n"
 "\n"
-">>> midi = bintomidi(float, samplerate = 44100, fftsize = 1024)";
+">>> aubio.bintomidi(10, 44100, 1024)\n"
+"68.62871551513672\n"
+"";
 
 static char Py_miditobin_doc[] = ""
-"miditobin(float, samplerate = integer, fftsize = integer) -> float\n"
-"\n"
-"Convert midi (float) to bin (float), given the sampling rate and the FFT size\n"
+"miditobin(midi, samplerate, fftsize)\n"
+"\n"
+"Convert frequency in midi note to FFT bin, given the sampling rate\n"
+"and the size of the FFT.\n"
+"\n"
+"Parameters\n"
+"----------\n"
+"midi : float\n"
+"   input frequency, in midi note\n"
+"samplerate : float\n"
+"   sampling rate of the signal\n"
+"fftsize : float\n"
+"   size of the FFT\n"
+"\n"
+"Returns\n"
+"-------\n"
+"float\n"
+"   Frequency converted to FFT bin.\n"
+"\n"
+"Examples\n"
+"--------\n"
+"\n"
+">>> aubio.miditobin(69, 44100, 1024)\n"
+"10.216779708862305\n"
+">>> aubio.miditobin(75.08, 32000, 512)\n"
+"10.002175331115723\n"
+"";
+
+static char Py_bintofreq_doc[] = ""
+"bintofreq(fftbin, samplerate, fftsize)\n"
+"\n"
+"Convert FFT bin to frequency in Hz, given the sampling rate\n"
+"and the size of the FFT.\n"
+"\n"
+"Parameters\n"
+"----------\n"
+"fftbin : float\n"
+"   input frequency bin\n"
+"samplerate : float\n"
+"   sampling rate of the signal\n"
+"fftsize : float\n"
+"   size of the FFT\n"
+"\n"
+"Returns\n"
+"-------\n"
+"float\n"
+"   Frequency converted to Hz.\n"
 "\n"
 "Example\n"
 "-------\n"
 "\n"
-">>> bin = miditobin(midi, samplerate = 44100, fftsize = 1024)";
-
-static char Py_bintofreq_doc[] = ""
-"bintofreq(float, samplerate = integer, fftsize = integer) -> float\n"
-"\n"
-"Convert bin number (float) in frequency (Hz), given the sampling rate and the FFT size\n"
+">>> aubio.bintofreq(10, 44100, 1024)\n"
+"430.6640625\n"
+"";
+
+static char Py_freqtobin_doc[] = ""
+"freqtobin(freq, samplerate, fftsize)\n"
+"\n"
+"Convert frequency in Hz to FFT bin, given the sampling rate\n"
+"and the size of the FFT.\n"
+"\n"
+"Parameters\n"
+"----------\n"
+"midi : float\n"
+"   input frequency, in midi note\n"
+"samplerate : float\n"
+"   sampling rate of the signal\n"
+"fftsize : float\n"
+"   size of the FFT\n"
+"\n"
+"Returns\n"
+"-------\n"
+"float\n"
+"   Frequency converted to FFT bin.\n"
+"\n"
+"Examples\n"
+"--------\n"
+"\n"
+">>> aubio.freqtobin(440, 44100, 1024)\n"
+"10.216779708862305\n"
+"";
+
+static char Py_zero_crossing_rate_doc[] = ""
+"zero_crossing_rate(vec)\n"
+"\n"
+"Compute zero-crossing rate of `vec`.\n"
+"\n"
+"Parameters\n"
+"----------\n"
+"vec : fvec\n"
+"   input vector\n"
+"\n"
+"Returns\n"
+"-------\n"
+"float\n"
+"   Zero-crossing rate.\n"
 "\n"
 "Example\n"
 "-------\n"
 "\n"
-">>> freq = bintofreq(bin, samplerate = 44100, fftsize = 1024)";
-
-static char Py_freqtobin_doc[] = ""
-"freqtobin(float, samplerate = integer, fftsize = integer) -> float\n"
-"\n"
-"Convert frequency (Hz) in bin number (float), given the sampling rate and the FFT size\n"
+">>> a = np.linspace(-1., 1., 1000, dtype=aubio.float_type)\n"
+">>> aubio.zero_crossing_rate(a), 1/1000\n"
+"(0.0010000000474974513, 0.001)\n"
+"";
+
+static char Py_min_removal_doc[] = ""
+"min_removal(vec)\n"
+"\n"
+"Remove the minimum value of a vector to each of its element.\n"
+"\n"
+"Modifies the input vector in-place and returns a reference to it.\n"
+"\n"
+"Parameters\n"
+"----------\n"
+"vec : fvec\n"
+"   input vector\n"
+"\n"
+"Returns\n"
+"-------\n"
+"fvec\n"
+"   modified input vector\n"
 "\n"
 "Example\n"
 "-------\n"
 "\n"
-">>> bin = freqtobin(freq, samplerate = 44100, fftsize = 1024)";
-
-static char Py_zero_crossing_rate_doc[] = ""
-"zero_crossing_rate(fvec) -> float\n"
-"\n"
-"Compute Zero crossing rate of a vector\n"
-"\n"
-"Example\n"
-"-------\n"
-"\n"
-">>> z = zero_crossing_rate(a)";
-
-static char Py_min_removal_doc[] = ""
-"min_removal(fvec) -> float\n"
-"\n"
-"Remove the minimum value of a vector, in-place modification\n"
-"\n"
-"Example\n"
-"-------\n"
-"\n"
-">>> min_removal(a)";
+">>> aubio.min_removal(aubio.fvec(np.arange(1,4)))\n"
+"array([0., 1., 2.], dtype=" AUBIO_NPY_SMPL_STR ")\n"
+"";
 
 extern void add_ufuncs ( PyObject *m );
