From 78c1d32f5400a9de0524dd5bd1c9405ecf65166f Mon Sep 17 00:00:00 2001
From: Paul Brossier <piem@piem.org>
Date: Tue, 30 Oct 2018 17:57:27 +0100
Subject: [PATCH] [py] improve fvec doc

---
 python/lib/aubio/__init__.py | 50 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 49 insertions(+), 1 deletion(-)

diff --git a/python/lib/aubio/__init__.py b/python/lib/aubio/__init__.py
index e7b891c4..9c202c78 100644
--- a/python/lib/aubio/__init__.py
+++ b/python/lib/aubio/__init__.py
@@ -8,8 +8,56 @@ from .midiconv import *
 from .slicing import *
 
 class fvec(numpy.ndarray):
-    """a numpy vector holding audio samples"""
+    """fvec(input_arg=1024, **kwargs)
+    A vector holding float samples.
 
+    If `input_arg` is an `int`, a 1-dimensional vector of length `input_arg`
+    will be created and filled with zeros. Otherwise, if `input_arg` is an
+    `array_like` object, it will be converted to a 1-dimensional vector of
+    type :data:`float_type`.
+
+    Parameters
+    ----------
+    input_arg : `int` or `array_like`
+        Can be a positive integer, or any object that can be converted to
+        a numpy array with :func:`numpy.array`.
+    **kwargs
+        Additional keyword arguments passed to :func:`numpy.zeros`, if
+        `input_arg` is an integer, or to :func:`numpy.array`. Should not
+        include `dtype`, which is already specified as
+        :data:`aubio.float_type`.
+
+    Returns
+    -------
+    numpy.ndarray
+        Array of shape `(length,)`.
+
+    Examples
+    --------
+    >>> aubio.fvec(10)
+    array([0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], dtype=float32)
+    >>> aubio.fvec([0,1,2])
+    array([0., 1., 2.], dtype=float32)
+    >>> a = np.arange(10); type(a), type(aubio.fvec(a))
+    (<class 'numpy.ndarray'>, <class 'numpy.ndarray'>)
+    >>> a.dtype, aubio.fvec(a).dtype
+    (dtype('int64'), dtype('float32'))
+
+    Notes
+    -----
+
+    In the Python world, `fvec` is simply a subclass of
+    :class:`numpy.ndarray`. In practice, any 1-dimensional `numpy.ndarray` of
+    `dtype` :data:`float_type` may be passed to methods accepting
+    `fvec` as parameter. For instance, `sink()` or `pvoc()`.
+
+    See Also
+    --------
+    cvec : a container holding spectral data
+    numpy.ndarray : parent class of :class:`fvec`
+    numpy.zeros : create a numpy array filled with zeros
+    numpy.array : create a numpy array from an existing object
+    """
     def __new__(cls, input_arg=1024, **kwargs):
         if isinstance(input_arg, int):
             if input_arg == 0:
-- 
2.11.0