Index: src/io/audio_unit.h
===================================================================
--- src/io/audio_unit.h	(revision ac20c856d41f89c5c9c4e2f197ff79d4fc4e0c2d)
+++ src/io/audio_unit.h	(revision ac20c856d41f89c5c9c4e2f197ff79d4fc4e0c2d)
@@ -0,0 +1,45 @@
+/*
+  Copyright (C) 2013 Paul Brossier <piem@aubio.org>
+
+  This file is part of aubio.
+
+  aubio is free software: you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation, either version 3 of the License, or
+  (at your option) any later version.
+
+  aubio is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with aubio.  If not, see <http://www.gnu.org/licenses/>.
+
+*/
+
+#ifndef _AUBIO_IO_AUDIO_UNIT_H
+#define _AUBIO_IO_AUDIO_UNIT_H
+
+/** \file
+
+*/
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct _aubio_audio_unit_t aubio_audio_unit_t;
+
+typedef uint_t (*aubio_audio_unit_callback_t) (void * closure, float *ibuf, float *obuf, uint_t size);
+
+
+aubio_audio_unit_t * new_aubio_audio_unit(uint_t samplerate, uint_t inchannels,
+    uint_t outchannels, uint_t blocksize);
+uint_t del_aubio_audio_unit(aubio_audio_unit_t *o);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* _AUBIO_IO_AUDIO_UNIT_H */
Index: src/io/sink.h
===================================================================
--- src/io/sink.h	(revision de5d3f123debc4c03dad0ad15f2af5b7a444e0c0)
+++ src/io/sink.h	(revision ac20c856d41f89c5c9c4e2f197ff79d4fc4e0c2d)
@@ -1,4 +1,4 @@
 /*
-  Copyright (C) 2012 Paul Brossier <piem@aubio.org>
+  Copyright (C) 2012-2013 Paul Brossier <piem@aubio.org>
 
   This file is part of aubio.
@@ -24,5 +24,5 @@
 /** \file
 
-  Media sink
+  Media sink to write blocks of consecutive audio samples to file.
 
   \example io/test-sink.c
@@ -34,7 +34,39 @@
 #endif
 
+/** media sink object */
 typedef struct _aubio_sink_t aubio_sink_t;
+
+/**
+
+  create new ::aubio_sink_t
+
+  \param uri the file path or uri to write to
+  \param samplerate sample rate to write the file at
+
+  \return newly created ::aubio_sink_t
+
+  Creates a new sink object.
+
+*/
 aubio_sink_t * new_aubio_sink(char_t * uri, uint_t samplerate);
-void aubio_sink_do(aubio_sink_t * s, fvec_t * write_data, uint_t written);
+
+/**
+
+  write monophonic vector of length hop_size to sink
+
+  \param s sink, created with ::new_aubio_sink
+  \param write_data ::fvec_t samples to write to sink
+  \param write number of frames to write
+
+*/
+void aubio_sink_do(aubio_sink_t * s, fvec_t * write_data, uint_t write);
+
+/**
+
+  close sink and cleanup memory
+
+  \param s source object, created with ::new_aubio_source
+
+*/
 void del_aubio_sink(aubio_sink_t * s);
 
Index: src/io/sink_apple_audio.h
===================================================================
--- src/io/sink_apple_audio.h	(revision de5d3f123debc4c03dad0ad15f2af5b7a444e0c0)
+++ src/io/sink_apple_audio.h	(revision ac20c856d41f89c5c9c4e2f197ff79d4fc4e0c2d)
@@ -1,4 +1,4 @@
 /*
-  Copyright (C) 2012 Paul Brossier <piem@aubio.org>
+  Copyright (C) 2012-2013 Paul Brossier <piem@aubio.org>
 
   This file is part of aubio.
@@ -24,5 +24,11 @@
 /** \file
 
-  Apple Audio Media
+  Write to file using Apple AudioToolbox's
+  [ExtAudioFileRef](https://developer.apple.com/library/ios/#documentation/MusicAudio/Reference/ExtendedAudioFileServicesReference/Reference/reference.html)
+
+  Avoid including this file directly! Prefer using ::aubio_sink_t instead to
+  make your code portable.
+
+  To read from file, use ::aubio_source_t.
 
   \example io/test-sink_apple_audio.c
@@ -35,6 +41,37 @@
 
 typedef struct _aubio_sink_apple_audio_t aubio_sink_apple_audio_t;
-aubio_sink_apple_audio_t * new_aubio_sink_apple_audio(char_t * method, uint_t samplerate);
+
+/**
+
+  create new ::aubio_sink_apple_audio_t
+
+  \param uri the file path or uri to write to
+  \param samplerate sample rate to write the file at
+
+  \return newly created ::aubio_sink_apple_audio_t
+
+  Creates a new sink object.
+
+*/
+aubio_sink_apple_audio_t * new_aubio_sink_apple_audio(char_t * uri, uint_t samplerate);
+
+/**
+
+  write monophonic vector of length hop_size to sink
+
+  \param s sink, created with ::new_aubio_sink_apple_audio
+  \param write_data ::fvec_t samples to write to sink
+  \param write number of frames to write
+
+*/
 void aubio_sink_apple_audio_do(aubio_sink_apple_audio_t * s, fvec_t * write_data, uint_t write);
+
+/**
+
+  close sink and cleanup memory
+
+  \param s sink, created with ::new_aubio_sink_apple_audio
+
+*/
 void del_aubio_sink_apple_audio(aubio_sink_apple_audio_t * s);
 
Index: src/io/sink_sndfile.h
===================================================================
--- src/io/sink_sndfile.h	(revision de5d3f123debc4c03dad0ad15f2af5b7a444e0c0)
+++ src/io/sink_sndfile.h	(revision ac20c856d41f89c5c9c4e2f197ff79d4fc4e0c2d)
@@ -1,4 +1,4 @@
 /*
-  Copyright (C) 2012 Paul Brossier <piem@aubio.org>
+  Copyright (C) 2012-2013 Paul Brossier <piem@aubio.org>
 
   This file is part of aubio.
@@ -24,5 +24,10 @@
 /** \file
 
-  sndfile sink
+  Write to file using [libsndfile](http://www.mega-nerd.com/libsndfile/)
+
+  Avoid including this file directly! Prefer using ::aubio_sink_t instead to
+  make your code portable.
+
+  To read from file, use ::aubio_source_t.
 
   \example io/test-sink_sndfile.c
@@ -35,6 +40,37 @@
 
 typedef struct _aubio_sink_sndfile_t aubio_sink_sndfile_t;
-aubio_sink_sndfile_t * new_aubio_sink_sndfile(char_t * method, uint_t samplerate);
+
+/**
+
+  create new ::aubio_sink_sndfile_t
+
+  \param uri the file path or uri to write to
+  \param samplerate sample rate to write the file at
+
+  \return newly created ::aubio_sink_sndfile_t
+
+  Creates a new sink object.
+
+*/
+aubio_sink_sndfile_t * new_aubio_sink_sndfile(char_t * uri, uint_t samplerate);
+
+/**
+
+  write monophonic vector of length hop_size to sink
+
+  \param s sink, created with ::new_aubio_sink_sndfile
+  \param write_data ::fvec_t samples to write to sink
+  \param write number of frames to write
+
+*/
 void aubio_sink_sndfile_do(aubio_sink_sndfile_t * s, fvec_t * write_data, uint_t write);
+
+/**
+
+  close sink and cleanup memory
+
+  \param s sink, created with ::new_aubio_sink_sndfile
+
+*/
 void del_aubio_sink_sndfile(aubio_sink_sndfile_t * s);
 
Index: src/io/source.h
===================================================================
--- src/io/source.h	(revision de5d3f123debc4c03dad0ad15f2af5b7a444e0c0)
+++ src/io/source.h	(revision ac20c856d41f89c5c9c4e2f197ff79d4fc4e0c2d)
@@ -1,4 +1,4 @@
 /*
-  Copyright (C) 2012 Paul Brossier <piem@aubio.org>
+  Copyright (C) 2012-2013 Paul Brossier <piem@aubio.org>
 
   This file is part of aubio.
@@ -24,5 +24,5 @@
 /** \file
 
-  Media source object
+  Media source to read blocks of consecutive audio samples from file
 
   \example io/test-source.c
@@ -34,5 +34,5 @@
 #endif
 
-/** source object structure */
+/** media source object */
 typedef struct _aubio_source_t aubio_source_t;
 
@@ -42,29 +42,29 @@
 
   \param uri the file path or uri to read from
-  \param samplerate the sample rate to read the file at
-  \param hop_size the size of the blocks to read from
+  \param samplerate sampling rate to view the fie at
+  \param block_size the size of the blocks to read from
 
   Creates a new source object. If `0` is passed as `samplerate`, the sample
   rate of the original file is used.
 
-  The samplerate of the current source can be obtained with
+  The samplerate of newly created source can be obtained using
   ::aubio_source_get_samplerate.
 
 */
-aubio_source_t * new_aubio_source(char_t * uri, uint_t samplerate, uint_t hop_size);
+aubio_source_t * new_aubio_source(char_t * uri, uint_t samplerate, uint_t block_size);
 
 /**
 
-  read monophonic vector of length hop_size from source object
+  read monophonic vector of length block_size from source object
 
   \param s source object, created with ::new_aubio_source
-  \param read_data ::fvec_t of data to read to
-  \param read number of frames actually read
+  \param read_to ::fvec_t of data to read to
+  \param read upon returns, equals to number of frames actually read
 
   Upon returns, `read` contains the number of frames actually read from the
-  source. `hop_size` if enough frames could be read, less otherwise.
+  source. `block_size` if enough frames could be read, less otherwise.
 
 */
-void aubio_source_do(aubio_source_t * s, fvec_t * read_data, uint_t * read);
+void aubio_source_do(aubio_source_t * s, fvec_t * read_to, uint_t * read);
 
 /**
@@ -80,5 +80,5 @@
 /**
 
-  destroy source object
+  close source and cleanup memory
 
   \param s source object, created with ::new_aubio_source
Index: src/io/source_apple_audio.h
===================================================================
--- src/io/source_apple_audio.h	(revision de5d3f123debc4c03dad0ad15f2af5b7a444e0c0)
+++ src/io/source_apple_audio.h	(revision ac20c856d41f89c5c9c4e2f197ff79d4fc4e0c2d)
@@ -1,4 +1,4 @@
 /*
-  Copyright (C) 2012 Paul Brossier <piem@aubio.org>
+  Copyright (C) 2012-2013 Paul Brossier <piem@aubio.org>
 
   This file is part of aubio.
@@ -24,5 +24,11 @@
 /** \file
 
-  aubio source using ExtAudioFileRef
+  Read from file using Apple AudioToolbox's
+  [ExtAudioFileRef](https://developer.apple.com/library/ios/#documentation/MusicAudio/Reference/ExtendedAudioFileServicesReference/Reference/reference.html)
+
+  Avoid including this file directly! Prefer using ::aubio_source_t instead to
+  make your code portable.
+
+  To write to file, use ::aubio_sink_t.
 
   \example io/test-source_apple_audio.c
@@ -34,8 +40,56 @@
 #endif
 
+/** apple audio media source object */
 typedef struct _aubio_source_apple_audio_t aubio_source_apple_audio_t;
-aubio_source_apple_audio_t * new_aubio_source_apple_audio(char_t * path, uint_t samplerate, uint_t block_size);
+
+/**
+
+  create new ::aubio_source_apple_audio_t
+
+  \param uri the file path or uri to read from
+  \param samplerate sampling rate to view the fie at
+  \param block_size the size of the blocks to read from
+
+  Creates a new source object. If `0` is passed as `samplerate`, the sample
+  rate of the original file is used.
+
+  The samplerate of newly created source can be obtained using
+  ::aubio_source_apple_audio_get_samplerate.
+
+*/
+aubio_source_apple_audio_t * new_aubio_source_apple_audio(char_t * uri, uint_t samplerate, uint_t block_size);
+
+/**
+
+  read monophonic vector of length block_size from source object
+
+  \param s source object, created with ::new_aubio_source_apple_audio
+  \param read_to ::fvec_t of data to read to
+  \param read upon returns, equals to number of frames actually read
+
+  Upon returns, `read` contains the number of frames actually read from the
+  source. `block_size` if enough frames could be read, less otherwise.
+
+*/
 void aubio_source_apple_audio_do(aubio_source_apple_audio_t * s, fvec_t * read_to, uint_t * read);
+void aubio_source_apple_audio_do_multi(aubio_source_apple_audio_t * s, fmat_t * read_to, uint_t * read);
+
+/**
+
+  get samplerate of source object
+
+  \param s source object, created with ::new_aubio_source_apple_audio
+  \return samplerate, in Hz
+
+*/
 uint_t aubio_source_apple_audio_get_samplerate(aubio_source_apple_audio_t * s);
+
+/**
+
+  close source and cleanup memory
+
+  \param s source object, created with ::new_aubio_source_apple_audio
+
+*/
 void del_aubio_source_apple_audio(aubio_source_apple_audio_t * s);
 
Index: src/io/source_sndfile.h
===================================================================
--- src/io/source_sndfile.h	(revision de5d3f123debc4c03dad0ad15f2af5b7a444e0c0)
+++ src/io/source_sndfile.h	(revision ac20c856d41f89c5c9c4e2f197ff79d4fc4e0c2d)
@@ -1,4 +1,4 @@
 /*
-  Copyright (C) 2012 Paul Brossier <piem@aubio.org>
+  Copyright (C) 2012-2013 Paul Brossier <piem@aubio.org>
 
   This file is part of aubio.
@@ -24,4 +24,11 @@
 /** \file
 
+  Read from file using [libsndfile](http://www.mega-nerd.com/libsndfile/)
+
+  Avoid including this file directly! Prefer using ::aubio_source_t instead to
+  make your code portable.
+
+  To write to file, use ::aubio_sink_t.
+
   \example io/test-source_sndfile.c
 
@@ -32,8 +39,55 @@
 #endif
 
+/** sndfile media source object */
 typedef struct _aubio_source_sndfile_t aubio_source_sndfile_t;
-aubio_source_sndfile_t * new_aubio_source_sndfile(char_t * path, uint_t samplerate, uint_t block_size);
+
+/**
+
+  create new ::aubio_source_sndfile_t
+
+  \param uri the file path or uri to read from
+  \param samplerate sampling rate to view the fie at
+  \param block_size the size of the blocks to read from
+
+  Creates a new source object. If `0` is passed as `samplerate`, the sample
+  rate of the original file is used.
+
+  The samplerate of newly created source can be obtained using
+  ::aubio_source_sndfile_get_samplerate.
+
+*/
+aubio_source_sndfile_t * new_aubio_source_sndfile(char_t * uri, uint_t samplerate, uint_t block_size);
+
+/**
+
+  read monophonic vector of length block_size from source object
+
+  \param s source object, created with ::new_aubio_source_sndfile
+  \param read_to ::fvec_t of data to read to
+  \param read upon returns, equals to number of frames actually read
+
+  Upon returns, `read` contains the number of frames actually read from the
+  source. `block_size` if enough frames could be read, less otherwise.
+
+*/
 void aubio_source_sndfile_do(aubio_source_sndfile_t * s, fvec_t * read_to, uint_t * read);
+
+/**
+
+  get samplerate of source object
+
+  \param s source object, created with ::new_aubio_source_sndfile
+  \return samplerate, in Hz
+
+*/
 uint_t aubio_source_sndfile_get_samplerate(aubio_source_sndfile_t * s);
+
+/**
+
+  close source and cleanup memory
+
+  \param s source object, created with ::new_aubio_source_sndfile
+
+*/
 void del_aubio_source_sndfile(aubio_source_sndfile_t * s);
 
