Index: src/synth/sampler.h
===================================================================
--- src/synth/sampler.h	(revision 8750bbd4ed5a46cd69c1ed5e1112da2c6b4048ca)
+++ src/synth/sampler.h	(revision 2b6139e795605d54d1b49d96a66643b88b03d544)
@@ -45,4 +45,5 @@
 
   \param samplerate the sampling rate of the new sampler
+  \param hop_size the block size of the new sampler
 
   \return the newly created ::aubio_sampler_t
@@ -53,5 +54,5 @@
 /** load source in sampler
 
-  \param o sampler, created by ::new_aubio_sampler
+  \param o sampler, created by new_aubio_sampler()
   \param uri the uri of the source to load
 
@@ -63,9 +64,9 @@
 /** process sampler function
 
-  \param o sampler, created by ::new_aubio_sampler
+  \param o sampler, created by new_aubio_sampler()
   \param input input of the sampler, to be added to the output
   \param output output of the sampler
 
-This function adds the new samples from the playing sample to the output.
+This function adds the new samples from the playing source to the output.
 
 If `input` is not NULL and different from `output`, then the samples from `input`
@@ -77,9 +78,9 @@
 /** process sampler function, multiple channels
 
-  \param o sampler, created by ::new_aubio_sampler
+  \param o sampler, created by new_aubio_sampler()
   \param input input of the sampler, to be added to the output
   \param output output of the sampler
 
-This function adds the new samples from the playing sample to the output.
+This function adds the new samples from the playing source to the output.
 
 If `input` is not NULL and different from `output`, then the samples from `input`
@@ -91,5 +92,5 @@
 /** get current playing state
 
-  \param o sampler, created by ::new_aubio_sampler
+  \param o sampler, created by new_aubio_sampler()
 
   \return 0 if not playing, 1 if playing
@@ -100,5 +101,5 @@
 /** set current playing state
 
-  \param o sampler, created by ::new_aubio_sampler
+  \param o sampler, created by new_aubio_sampler()
   \param playing 0 for not playing, 1 for playing
 
@@ -110,6 +111,5 @@
 /** play sample from start
 
-  \param o sampler, created by ::new_aubio_sampler
-  \param playing 0 for not playing, 1 for playing
+  \param o sampler, created by new_aubio_sampler()
 
   \return 0 if successful, 1 otherwise
@@ -118,8 +118,7 @@
 uint_t aubio_sampler_play ( aubio_sampler_t * o );
 
-/** stop sample from start
+/** stop sample
 
-  \param o sampler, created by ::new_aubio_sampler
-  \param playing 0 for not playing, 1 for playing
+  \param o sampler, created by new_aubio_sampler()
 
   \return 0 if successful, 1 otherwise
@@ -130,5 +129,5 @@
 /** destroy ::aubio_sampler_t object
 
-  \param o sampler, created by ::new_aubio_sampler
+  \param o sampler, created by new_aubio_sampler()
 
 */
Index: src/synth/wavetable.h
===================================================================
--- src/synth/wavetable.h	(revision 8750bbd4ed5a46cd69c1ed5e1112da2c6b4048ca)
+++ src/synth/wavetable.h	(revision 2b6139e795605d54d1b49d96a66643b88b03d544)
@@ -24,7 +24,7 @@
 /** \file
 
-  Load and play sound files.
+  Wavetable synthesis.
 
-  This file loads a sample and gets ready to play it.
+  This file creates a wavetable and plays it at different frequency.
 
   The `_do` function adds the new samples to the input, and write the result as
@@ -45,6 +45,7 @@
 
   \param samplerate the sampling rate of the new wavetable
+  \param hop_size the block size of the new wavetable
 
-  \return the newly created ::aubio_wavetable_t
+  \return the newly created aubio_wavetable_t
 
 */
@@ -53,5 +54,5 @@
 /** load source in wavetable
 
-  \param o wavetable, created by ::new_aubio_wavetable
+  \param o wavetable, created by new_aubio_wavetable()
   \param uri the uri of the source to load
 
@@ -63,9 +64,9 @@
 /** process wavetable function
 
-  \param o wavetable, created by ::new_aubio_wavetable
+  \param o wavetable, created by new_aubio_wavetable()
   \param input input of the wavetable, to be added to the output
   \param output output of the wavetable
 
-This function adds the new samples from the playing sample to the output.
+This function adds the new samples from the playing wavetable to the output.
 
 If `input` is not NULL and different from `output`, then the samples from `input`
@@ -77,9 +78,9 @@
 /** process wavetable function, multiple channels
 
-  \param o wavetable, created by ::new_aubio_wavetable
+  \param o wavetable, created by new_aubio_wavetable()
   \param input input of the wavetable, to be added to the output
   \param output output of the wavetable
 
-This function adds the new samples from the playing sample to the output.
+This function adds the new samples from the playing wavetable to the output.
 
 If `input` is not NULL and different from `output`, then the samples from `input`
@@ -91,5 +92,5 @@
 /** get current playing state
 
-  \param o wavetable, created by ::new_aubio_wavetable
+  \param o wavetable, created by new_aubio_wavetable()
 
   \return 0 if not playing, 1 if playing
@@ -100,5 +101,5 @@
 /** set current playing state
 
-  \param o wavetable, created by ::new_aubio_wavetable
+  \param o wavetable, created by new_aubio_wavetable()
   \param playing 0 for not playing, 1 for playing
 
@@ -110,5 +111,5 @@
 /** play sample from start
 
-  \param o wavetable, created by ::new_aubio_wavetable
+  \param o wavetable, created by new_aubio_wavetable()
 
   \return 0 if successful, 1 otherwise
@@ -117,7 +118,7 @@
 uint_t aubio_wavetable_play ( aubio_wavetable_t * o );
 
-/** stop sample
+/** stop wavetable
 
-  \param o wavetable, created by ::new_aubio_wavetable
+  \param o wavetable, created by new_aubio_wavetable()
 
   \return 0 if successful, 1 otherwise
@@ -128,5 +129,5 @@
 /** set wavetable frequency
 
-  \param o wavetable, created by ::new_aubio_wavetable
+  \param o wavetable, created by new_aubio_wavetable()
   \param freq new frequency value for the wavetable
 
@@ -138,5 +139,5 @@
 /** get wavetable frequency
 
-  \param o wavetable, created by ::new_aubio_wavetable
+  \param o wavetable, created by new_aubio_wavetable()
 
   \return current frequency, in Hz
@@ -147,5 +148,5 @@
 /** set wavetable amplitude
 
-  \param o wavetable, created by ::new_aubio_wavetable
+  \param o wavetable, created by new_aubio_wavetable()
   \param amp new amplitude value for the wavetable
 
@@ -157,5 +158,5 @@
 /** get wavetable amplitude
 
-  \param o wavetable, created by ::new_aubio_wavetable
+  \param o wavetable, created by new_aubio_wavetable()
 
   \return current amplitude
@@ -164,7 +165,7 @@
 smpl_t aubio_wavetable_get_amp ( aubio_wavetable_t * o);
 
-/** destroy ::aubio_wavetable_t object
+/** destroy aubio_wavetable_t object
 
-  \param o wavetable, created by ::new_aubio_wavetable
+  \param o wavetable, created by new_aubio_wavetable()
 
 */
