[python] improve docstrings for shift and ishift

diff --git a/python/ext/py-musicutils.h b/python/ext/py-musicutils.h
index 44b27fb..2c6836d 100644 (file)
--- a/python/ext/py-musicutils.h
+++ b/python/ext/py-musicutils.h
@@ -156,33 +156,69 @@ static char Py_aubio_level_detection_doc[] = ""
 PyObject * Py_aubio_level_detection(PyObject *self, PyObject *args);
 
 static char Py_aubio_shift_doc[] = ""
-"Swap left and right partitions of a vector\n"
+"shift(vec)\n"
 "\n"
-"Returns the swapped vector. The input vector is also modified.\n"
+"Swap left and right partitions of a vector, in-place.\n"
+"\n"
+"Parameters\n"
+"----------\n"
+"vec : fvec\n"
+"   input vector to shift\n"
+"\n"
+"Returns\n"
+"-------\n"
+"fvec\n"
+"   The swapped vector.\n"
+"\n"
+"Notes\n"
+"-----\n"
+"The input vector is also modified.\n"
 "\n"
 "For a vector of length N, the partition is split at index N - N//2.\n"
 "\n"
 "Example\n"
 "-------\n"
 "\n"
-">>> import numpy\n"
-">>> shift(numpy.arange(3, dtype=aubio.float_type))\n"
-"array([2., 0., 1.], dtype=" AUBIO_NPY_SMPL_STR ")";
+">>> aubio.shift(aubio.fvec(np.arange(3)))\n"
+"array([2., 0., 1.], dtype=" AUBIO_NPY_SMPL_STR ")\n"
+"\n"
+"See Also\n"
+"--------\n"
+"ishift\n"
+"";
 PyObject * Py_aubio_shift(PyObject *self, PyObject *args);
 
 static char Py_aubio_ishift_doc[] = ""
-"Swap right and left partitions of a vector\n"
+"ishift(vec)\n"
 "\n"
-"Returns the swapped vector. The input vector is also modified.\n"
+"Swap right and left partitions of a vector, in-place.\n"
 "\n"
-"Unlike with shift(), the partition is split at index N//2.\n"
+"Parameters\n"
+"----------\n"
+"vec : fvec\n"
+"   input vector to shift\n"
+"\n"
+"Returns\n"
+"-------\n"
+"fvec\n"
+"   The swapped vector.\n"
+"\n"
+"Notes\n"
+"-----\n"
+"The input vector is also modified.\n"
+"\n"
+"Unlike with :py:func:`shift`, the partition is split at index N//2.\n"
 "\n"
 "Example\n"
 "-------\n"
 "\n"
-">>> import numpy\n"
-">>> ishift(numpy.arange(3, dtype=aubio.float_type))\n"
-"array([1., 2., 0.], dtype=" AUBIO_NPY_SMPL_STR ")";
+">>> aubio.ishift(aubio.fvec(np.arange(3)))\n"
+"array([1., 2., 0.], dtype=" AUBIO_NPY_SMPL_STR ")\n"
+"\n"
+"See Also\n"
+"--------\n"
+"shift\n"
+"";
 PyObject * Py_aubio_ishift(PyObject *self, PyObject *args);
 
 #endif /* PY_AUBIO_MUSICUTILS_H */