From 47b465c609c4cadbdd300b6bcad0a16b6fc30967 Mon Sep 17 00:00:00 2001
From: Paul Brossier <piem@piem.org>
Date: Fri, 26 Oct 2018 20:51:32 +0200
Subject: [PATCH] [python] add docstrings for pvoc

---
 python/ext/py-phasevoc.c | 103 ++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 98 insertions(+), 5 deletions(-)

diff --git a/python/ext/py-phasevoc.c b/python/ext/py-phasevoc.c
index e53fdf93..e67c5f07 100644
--- a/python/ext/py-phasevoc.c
+++ b/python/ext/py-phasevoc.c
@@ -1,6 +1,58 @@
 #include "aubio-types.h"
 
-static char Py_pvoc_doc[] = "pvoc object";
+static char Py_pvoc_doc[] = ""
+"pvoc(win_s=512, hop_s=256)\n"
+"\n"
+"Phase vocoder.\n"
+"\n"
+"`pvoc` creates callable object implements a phase vocoder [1]_,\n"
+"using the tricks detailed in [2]_.\n"
+"\n"
+"The call function takes one input of type `fvec` and of size\n"
+"`hop_s`, and returns a `cvec` of length `win_s//2+1`.\n"
+"\n"
+"Parameters\n"
+"----------\n"
+"win_s : int\n"
+"  number of channels in the phase-vocoder.\n"
+"hop_s : int\n"
+"  number of samples expected between each call\n"
+"\n"
+"Examples\n"
+"--------\n"
+">>> x = aubio.fvec(256)\n"
+">>> pv = aubio.pvoc(512, 256)\n"
+">>> pv(x)\n"
+"aubio cvec of 257 elements\n"
+"\n"
+"Default values for hop_s and win_s are provided:\n"
+"\n"
+">>> pv = aubio.pvoc()\n"
+">>> pv.win_s, pv.hop_s\n"
+"512, 256\n"
+"\n"
+"A `cvec` can be resynthesised using `rdo()`:\n"
+"\n"
+">>> pv = aubio.pvoc(512, 256)\n"
+">>> y = aubio.cvec(512)\n"
+">>> x_reconstructed = pv.rdo(y)\n"
+">>> x_reconstructed.shape\n"
+"(256,)\n"
+"\n"
+"References\n"
+"----------\n"
+".. [1] James A. Moorer. The use of the phase vocoder in computer music\n"
+"   applications. `Journal of the Audio Engineering Society`,\n"
+"   26(1/2):42–45, 1978.\n"
+".. [2] Amalia de Götzen, Nicolas Bernardini, and Daniel Arfib. Traditional\n"
+"   (?) implementations of a phase vocoder: the tricks of the trade.\n"
+"   In `Proceedings of the International Conference on Digital Audio\n"
+"   Effects` (DAFx-00), pages 37–44, University of Verona, Italy, 2000.\n"
+"   (`online version <"
+"https://www.cs.princeton.edu/courses/archive/spr09/cos325/Bernardini.pdf"
+">`_).\n"
+"";
+
 
 typedef struct
 {
@@ -121,9 +173,11 @@ Py_pvoc_do(Py_pvoc * self, PyObject * args)
 
 static PyMemberDef Py_pvoc_members[] = {
   {"win_s", T_INT, offsetof (Py_pvoc, win_s), READONLY,
-    "size of the window"},
+    "int: Size of phase vocoder analysis windows, in samples.\n"
+    ""},
   {"hop_s", T_INT, offsetof (Py_pvoc, hop_s), READONLY,
-    "size of the hop"},
+    "int: Interval between two analysis, in samples.\n"
+    ""},
   { NULL } // sentinel
 };
 
@@ -175,8 +229,47 @@ Pyaubio_pvoc_set_window (Py_pvoc *self, PyObject *args)
 
 static PyMethodDef Py_pvoc_methods[] = {
   {"rdo", (PyCFunction) Py_pvoc_rdo, METH_VARARGS,
-    "synthesis of spectral grain"},
-  {"set_window", (PyCFunction) Pyaubio_pvoc_set_window, METH_VARARGS, ""},
+    "rdo(fftgrain)\n"
+    "\n"
+    "Read a new spectral grain and resynthesise the next `hop_s`\n"
+    "output samples.\n"
+    "\n"
+    "Parameters\n"
+    "----------\n"
+    "fftgrain : cvec\n"
+    "    new input `cvec` to synthesize from, should be of size `win_s/2+1`\n"
+    "\n"
+    "Returns\n"
+    "-------\n"
+    "fvec\n"
+    "    re-synthesised output of shape `(hop_s,)`\n"
+    "\n"
+    "Example\n"
+    "-------\n"
+    ">>> pv = aubio.pvoc(2048, 512)\n"
+    ">>> out = pv.rdo(aubio.cvec(2048))\n"
+    ">>> out.shape\n"
+    "(512,)\n"
+    ""},
+  {"set_window", (PyCFunction) Pyaubio_pvoc_set_window, METH_VARARGS,
+    "set_window(window_type)\n"
+    "\n"
+    "Set window function\n"
+    "\n"
+    "Parameters\n"
+    "----------\n"
+    "window_type : str\n"
+    "    the window type to use for this phase vocoder\n"
+    "\n"
+    "Raises\n"
+    "------\n"
+    "ValueError\n"
+    "    If an unknown window type was given.\n"
+    "\n"
+    "See Also\n"
+    "--------\n"
+    "window : create a window.\n"
+    ""},
   {NULL}
 };
 
-- 
2.11.0