From 55b62606a151b9343b509dda6cc46a7bc54174e9 Mon Sep 17 00:00:00 2001
From: Paul Brossier <piem@piem.org>
Date: Fri, 26 Oct 2018 18:23:34 +0200
Subject: [PATCH] [python] add docstrings to alpha_norm and zero_crossing_rate

---
 python/ext/aubiomodule.c | 68 +++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 59 insertions(+), 9 deletions(-)

diff --git a/python/ext/aubiomodule.c b/python/ext/aubiomodule.c
index d6b111ef..092e3e62 100644
--- a/python/ext/aubiomodule.c
+++ b/python/ext/aubiomodule.c
@@ -10,14 +10,37 @@
 static char aubio_module_doc[] = "Python module for the aubio library";
 
 static char Py_alpha_norm_doc[] = ""
-"alpha_norm(fvec, integer) -> float\n"
+"alpha_norm(vec, alpha)\n"
 "\n"
-"Compute alpha normalisation factor on vector, given alpha\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(fftbin, samplerate, fftsize)\n"
@@ -130,24 +153,51 @@ static char Py_freqtobin_doc[] = ""
 "";
 
 static char Py_zero_crossing_rate_doc[] = ""
-"zero_crossing_rate(fvec) -> float\n"
+"zero_crossing_rate(vec)\n"
+"\n"
+"Compute zero-crossing rate of `vec`.\n"
+"\n"
+"Parameters\n"
+"----------\n"
+"vec : fvec\n"
+"   input vector\n"
 "\n"
-"Compute Zero crossing rate of a vector\n"
+"Returns\n"
+"-------\n"
+"float\n"
+"   Zero-crossing rate.\n"
 "\n"
 "Example\n"
 "-------\n"
 "\n"
-">>> z = zero_crossing_rate(a)";
+">>> 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(fvec) -> float\n"
+"min_removal(vec)\n"
+"\n"
+"Remove the minimum value of a vector to each of its element.\n"
 "\n"
-"Remove the minimum value of a vector, in-place modification\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"
-">>> 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 );
 extern int generated_types_ready(void);
-- 
2.11.0