From a79ec768a0cf2eab0e5ecb368afb62f494a640bc Mon Sep 17 00:00:00 2001 From: Paul Brossier Date: Sat, 20 Sep 2014 21:01:29 -0300 Subject: [PATCH] python/ext/py-{source,sink}.c: improve documentation --- python/ext/py-sink.c | 77 +++++++++++++++++++++++++++++++++++------------ python/ext/py-source.c | 81 ++++++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 130 insertions(+), 28 deletions(-) diff --git a/python/ext/py-sink.c b/python/ext/py-sink.c index 09679343..be5de364 100644 --- a/python/ext/py-sink.c +++ b/python/ext/py-sink.c @@ -9,7 +9,54 @@ typedef struct uint_t channels; } Py_sink; -static char Py_sink_doc[] = "sink object"; +static char Py_sink_doc[] = "" +" __new__(path, samplerate = 44100, channels = 1)\n" +"\n" +" Create a new sink, opening the given path for writing.\n" +"\n" +" Examples\n" +" --------\n" +"\n" +" Create a new sink at 44100Hz, mono:\n" +"\n" +" >>> sink('/tmp/t.wav')\n" +"\n" +" Create a new sink at 8000Hz, mono:\n" +"\n" +" >>> sink('/tmp/t.wav', samplerate = 8000)\n" +"\n" +" Create a new sink at 32000Hz, stereo:\n" +"\n" +" >>> sink('/tmp/t.wav', samplerate = 32000, channels = 2)\n" +"\n" +" Create a new sink at 32000Hz, 5 channels:\n" +"\n" +" >>> sink('/tmp/t.wav', channels = 5, samplerate = 32000)\n" +"\n" +" __call__(vec, write)\n" +" x(vec,write) <==> x.do(vec, write)\n" +"\n" +" Write vector to sink.\n" +"\n" +" See also\n" +" --------\n" +" aubio.sink.do\n" +"\n"; + +static char Py_sink_do_doc[] = "" +"x.do(vec, write) <==> x(vec, write)\n" +"\n" +"write monophonic vector to sink"; + +static char Py_sink_do_multi_doc[] = "" +"x.do_multi(mat, write)\n" +"\n" +"write polyphonic vector to sink"; + +static char Py_sink_close_doc[] = "" +"x.close()\n" +"\n" +"close this sink now"; static PyObject * Py_sink_new (PyTypeObject * pytype, PyObject * args, PyObject * kwds) @@ -113,7 +160,7 @@ Py_sink_do(Py_sink * self, PyObject * args) Py_RETURN_NONE; } -/* function Py_sink_do */ +/* function Py_sink_do_multi */ static PyObject * Py_sink_do_multi(Py_sink * self, PyObject * args) { @@ -147,9 +194,12 @@ Py_sink_do_multi(Py_sink * self, PyObject * args) } AUBIO_MEMBERS_START(sink) - {"uri", T_STRING, offsetof (Py_sink, uri), READONLY, ""}, - {"samplerate", T_INT, offsetof (Py_sink, samplerate), READONLY, ""}, - {"channels", T_INT, offsetof (Py_sink, channels), READONLY, ""}, + {"uri", T_STRING, offsetof (Py_sink, uri), READONLY, + "path at which the sink was created"}, + {"samplerate", T_INT, offsetof (Py_sink, samplerate), READONLY, + "samplerate at which the sink was created"}, + {"channels", T_INT, offsetof (Py_sink, channels), READONLY, + "number of channels with which the sink was created"}, AUBIO_MEMBERS_STOP(sink) static PyObject * @@ -160,20 +210,9 @@ Pyaubio_sink_close (Py_sink *self, PyObject *unused) } static PyMethodDef Py_sink_methods[] = { - {"__call__", (PyCFunction) Py_sink_do, METH_VARARGS, - "x.__call__(vec, write)\n" - "write monophonic vector to sink" - ""}, - {"do", (PyCFunction) Py_sink_do, METH_VARARGS, - "x.do(vec, write)\n" - "write monophonic vector to sink" - ""}, - {"do_multi", (PyCFunction) Py_sink_do_multi, METH_VARARGS, - "x.do_multi(mat, write)\n" - "write polyphonic vector to sink"}, - {"close", (PyCFunction) Pyaubio_sink_close, METH_NOARGS, - "x.close()\n" - "close this sink now"}, + {"do", (PyCFunction) Py_sink_do, METH_VARARGS, Py_sink_do_doc}, + {"do_multi", (PyCFunction) Py_sink_do_multi, METH_VARARGS, Py_sink_do_multi_doc}, + {"close", (PyCFunction) Pyaubio_sink_close, METH_NOARGS, Py_sink_close_doc}, {NULL} /* sentinel */ }; diff --git a/python/ext/py-source.c b/python/ext/py-source.c index da7f2985..2f8ed6e4 100644 --- a/python/ext/py-source.c +++ b/python/ext/py-source.c @@ -10,7 +10,64 @@ typedef struct uint_t hop_size; } Py_source; -static char Py_source_doc[] = "source object"; +static char Py_source_doc[] = "" +" __new__(path, samplerate = 0, hop_size = 512, channels = 1)\n" +"\n" +" Create a new source, opening the given path for reading.\n" +"\n" +" Examples\n" +" --------\n" +"\n" +" Create a new source, using the original samplerate, with hop_size = 512:\n" +"\n" +" >>> source('/tmp/t.wav')\n" +"\n" +" Create a new source, resampling the original to 8000Hz:\n" +"\n" +" >>> source('/tmp/t.wav', samplerate = 8000)\n" +"\n" +" Create a new source, resampling it at 32000Hz, hop_size = 32:\n" +"\n" +" >>> source('/tmp/t.wav', samplerate = 32000, hop_size = 32)\n" +"\n" +" Create a new source, using its original samplerate:\n" +"\n" +" >>> source('/tmp/t.wav', samplerate = 0)\n" +"\n" +" __call__()\n" +" vec, read = x() <==> vec, read = x.do()\n" +"\n" +" Read vector from source.\n" +"\n" +" See also\n" +" --------\n" +" aubio.source.do\n" +"\n"; + +static char Py_source_get_samplerate_doc[] = "" +"x.get_samplerate() -> source samplerate\n" +"\n" +"Get samplerate of source."; + +static char Py_source_get_channels_doc[] = "" +"x.get_channels() -> number of channels\n" +"\n" +"Get number of channels in source."; + +static char Py_source_do_doc[] = "" +"vec, read = x.do() <==> vec, read = x()\n" +"\n" +"Read monophonic vector from source."; + +static char Py_source_do_multi_doc[] = "" +"mat, read = x.do_multi()\n" +"\n" +"Read polyphonic vector from source."; + +static char Py_source_close_doc[] = "" +"x.close()\n" +"\n" +"Close this source now."; static PyObject * Py_source_new (PyTypeObject * pytype, PyObject * args, PyObject * kwds) @@ -135,10 +192,14 @@ Py_source_do_multi(Py_source * self, PyObject * args) } AUBIO_MEMBERS_START(source) - {"uri", T_STRING, offsetof (Py_source, uri), READONLY, ""}, - {"samplerate", T_INT, offsetof (Py_source, samplerate), READONLY, ""}, - {"channels", T_INT, offsetof (Py_source, channels), READONLY, ""}, - {"hop_size", T_INT, offsetof (Py_source, hop_size), READONLY, ""}, + {"uri", T_STRING, offsetof (Py_source, uri), READONLY, + "path at which the source was created"}, + {"samplerate", T_INT, offsetof (Py_source, samplerate), READONLY, + "samplerate at which the source is viewed"}, + {"channels", T_INT, offsetof (Py_source, channels), READONLY, + "number of channels found in the source"}, + {"hop_size", T_INT, offsetof (Py_source, hop_size), READONLY, + "number of consecutive frames that will be read at each do or do_multi call"}, AUBIO_MEMBERS_STOP(source) @@ -165,13 +226,15 @@ Pyaubio_source_close (Py_source *self, PyObject *unused) static PyMethodDef Py_source_methods[] = { {"get_samplerate", (PyCFunction) Pyaubio_source_get_samplerate, - METH_NOARGS, ""}, + METH_NOARGS, Py_source_get_samplerate_doc}, {"get_channels", (PyCFunction) Pyaubio_source_get_channels, - METH_NOARGS, ""}, + METH_NOARGS, Py_source_get_channels_doc}, + {"do", (PyCFunction) Py_source_do, + METH_NOARGS, Py_source_do_doc}, {"do_multi", (PyCFunction) Py_source_do_multi, - METH_NOARGS, ""}, + METH_NOARGS, Py_source_do_multi_doc}, {"close", (PyCFunction) Pyaubio_source_close, - METH_NOARGS, ""}, + METH_NOARGS, Py_source_close_doc}, {NULL} /* sentinel */ }; -- 2.11.0