Index: python/ext/py-sink.c
===================================================================
--- python/ext/py-sink.c	(revision d0bdf0c4db5eabb3d0601ff01cf1989426368ca9)
+++ python/ext/py-sink.c	(revision a79ec768a0cf2eab0e5ecb368afb62f494a640bc)
@@ -10,5 +10,52 @@
 } 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 *
@@ -114,5 +161,5 @@
 }
 
-/* function Py_sink_do */
+/* function Py_sink_do_multi */
 static PyObject *
 Py_sink_do_multi(Py_sink * self, PyObject * args)
@@ -148,7 +195,10 @@
 
 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)
 
@@ -161,18 +211,7 @@
 
 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 */
 };
Index: python/ext/py-source.c
===================================================================
--- python/ext/py-source.c	(revision d0bdf0c4db5eabb3d0601ff01cf1989426368ca9)
+++ python/ext/py-source.c	(revision a79ec768a0cf2eab0e5ecb368afb62f494a640bc)
@@ -11,5 +11,62 @@
 } 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 *
@@ -136,8 +193,12 @@
 
 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)
 
@@ -166,11 +227,13 @@
 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 */
 };
