src/onset/onset.h: add examples to documentation

[aubio.git] / src / onset / onset.h

diff --git a/src/onset/onset.h b/src/onset/onset.h
index 4742d5a..e0a5858 100644 (file)
--- a/src/onset/onset.h
+++ b/src/onset/onset.h
@@ -25,7 +25,7 @@
   The following routines compute the onset detection function and detect peaks
   in these functions. When onsets are found above a given silence threshold,
   and after a minimum inter-onset interval, the output vector returned by
-  ::aubio_onset_do is filled with `1`. Otherwise, the output vector remains
+  aubio_onset_do() is filled with `1`. Otherwise, the output vector remains
   `0`.
 
   The peak-picking threshold, the silence threshold, and the minimum
@@ -33,6 +33,8 @@
   aubio_onset_do routine using the corresponding functions.
 
   \example onset/test-onset.c
+  \example examples/aubioonset.c
+  \example examples/aubionotes.c
 
 */
 
@@ -54,13 +56,15 @@ typedef struct _aubio_onset_t aubio_onset_t;
   \param hop_size hop size for phase vocoder
   \param samplerate sampling rate of the input signal
 
+  \return newly created ::aubio_onset_t
+
 */
 aubio_onset_t * new_aubio_onset (char_t * method,
     uint_t buf_size, uint_t hop_size, uint_t samplerate);
 
 /** execute onset detection
 
-  \param o onset detection object as returned by ::new_aubio_onset
+  \param o onset detection object as returned by new_aubio_onset()
   \param input new audio vector of length hop_size
   \param onset output vector of length 1, containing 0 if no onset was found,
   and a value equal or greater than 1 otherwise
@@ -72,7 +76,7 @@ aubio_onset_t * new_aubio_onset (char_t * method,
   to `offset = 1 + a` where `a` is a number in the range`[0, 1]`.
 
   The final onset detection time, in samples, can be obtained with
-  ::aubio_onset_get_last_onset. It can also be derived from `offset` as
+  aubio_onset_get_last(). It can also be derived from `offset` as
   follows:
 
   \code
@@ -81,35 +85,41 @@ aubio_onset_t * new_aubio_onset (char_t * method,
 
   where `total_frames` is the total number of frames processed so far, and
   `delay` is the current delay of the onset object, as returned by
-  ::aubio_onset_get_delay.
+  aubio_onset_get_delay().
 
 */
 void aubio_onset_do (aubio_onset_t *o, fvec_t * input, fvec_t * onset);
 
 /** get the time of the latest onset detected, in samples
 
-  \param o onset detection object as returned by ::new_aubio_onset
+  \param o onset detection object as returned by new_aubio_onset()
+
+  \return onset detection timestamps (in samples)
 
 */
 uint_t aubio_onset_get_last (aubio_onset_t *o);
 
 /** get the time of the latest onset detected, in seconds
 
-  \param o onset detection object as returned by ::new_aubio_onset
+  \param o onset detection object as returned by new_aubio_onset()
+
+  \return onset detection timestamps (in seconds)
 
 */
 smpl_t aubio_onset_get_last_s (aubio_onset_t *o);
 
 /** get the time of the latest onset detected, in milliseconds
 
-  \param o onset detection object as returned by ::new_aubio_onset
+  \param o onset detection object as returned by new_aubio_onset()
+
+  \return onset detection timestamps (in milliseconds)
 
 */
 smpl_t aubio_onset_get_last_ms (aubio_onset_t *o);
 
 /** set onset detection silence threshold
 
-  \param o onset detection object as returned by ::new_aubio_onset
+  \param o onset detection object as returned by new_aubio_onset()
   \param silence new silence detection threshold
 
 */
@@ -117,7 +127,7 @@ uint_t aubio_onset_set_silence(aubio_onset_t * o, smpl_t silence);
 
 /** get onset detection function
 
-  \param o onset detection object as returned by ::new_aubio_onset
+  \param o onset detection object as returned by new_aubio_onset()
   \return the current value of the descriptor
 
 */
@@ -125,7 +135,7 @@ smpl_t aubio_onset_get_descriptor ( aubio_onset_t *o);
 
 /** get thresholded onset detection function
 
-  \param o onset detection object as returned by ::new_aubio_onset
+  \param o onset detection object as returned by new_aubio_onset()
   \return the value of the thresholded descriptor
 
 */
@@ -133,7 +143,7 @@ smpl_t aubio_onset_get_thresholded_descriptor ( aubio_onset_t *o);
 
 /** set onset detection peak picking threshold
 
-  \param o onset detection object as returned by ::new_aubio_onset
+  \param o onset detection object as returned by new_aubio_onset()
   \param threshold new peak-picking threshold
 
 */
@@ -141,7 +151,7 @@ uint_t aubio_onset_set_threshold(aubio_onset_t * o, smpl_t threshold);
 
 /** set minimum inter onset interval in samples
 
-  \param o onset detection object as returned by ::new_aubio_onset
+  \param o onset detection object as returned by new_aubio_onset()
   \param minioi minimum interval between two consecutive onsets (in
   samples)
 
@@ -150,7 +160,7 @@ uint_t aubio_onset_set_minioi(aubio_onset_t * o, uint_t minioi);
 
 /** set minimum inter onset interval in seconds
 
-  \param o onset detection object as returned by ::new_aubio_onset
+  \param o onset detection object as returned by new_aubio_onset()
   \param minioi minimum interval between two consecutive onsets (in
   seconds)
 
@@ -159,7 +169,7 @@ uint_t aubio_onset_set_minioi_s(aubio_onset_t * o, smpl_t minioi);
 
 /** set minimum inter onset interval in milliseconds
 
-  \param o onset detection object as returned by ::new_aubio_onset
+  \param o onset detection object as returned by new_aubio_onset()
   \param minioi minimum interval between two consecutive onsets (in
   milliseconds)
 
@@ -168,7 +178,7 @@ uint_t aubio_onset_set_minioi_ms(aubio_onset_t * o, smpl_t minioi);
 
 /** set minimum inter onset interval in samples
 
-  \param o onset detection object as returned by ::new_aubio_onset
+  \param o onset detection object as returned by new_aubio_onset()
   \param delay constant system delay to take back from detection time
   (in samples)
 
@@ -177,7 +187,7 @@ uint_t aubio_onset_set_delay(aubio_onset_t * o, uint_t delay);
 
 /** set minimum inter onset interval in seconds
 
-  \param o onset detection object as returned by ::new_aubio_onset
+  \param o onset detection object as returned by new_aubio_onset()
   \param delay constant system delay to take back from detection time
   (in seconds)
 
@@ -186,7 +196,7 @@ uint_t aubio_onset_set_delay_s(aubio_onset_t * o, smpl_t delay);
 
 /** set minimum inter onset interval in milliseconds
 
-  \param o onset detection object as returned by ::new_aubio_onset
+  \param o onset detection object as returned by new_aubio_onset()
   \param delay constant system delay to take back from detection time
   (in milliseconds)
 
@@ -195,7 +205,7 @@ uint_t aubio_onset_set_delay_ms(aubio_onset_t * o, smpl_t delay);
 
 /** get minimum inter onset interval in samples
 
-  \param o onset detection object as returned by ::new_aubio_onset
+  \param o onset detection object as returned by new_aubio_onset()
   \return minimum interval between two consecutive onsets (in
   samples)
 
@@ -204,7 +214,7 @@ uint_t aubio_onset_get_minioi(aubio_onset_t * o);
 
 /** get minimum inter onset interval in seconds
 
-  \param o onset detection object as returned by ::new_aubio_onset
+  \param o onset detection object as returned by new_aubio_onset()
   \return minimum interval between two consecutive onsets (in
   seconds)
 
@@ -213,7 +223,7 @@ smpl_t aubio_onset_get_minioi_s(aubio_onset_t * o);
 
 /** get minimum inter onset interval in milliseconds
 
-  \param o onset detection object as returned by ::new_aubio_onset
+  \param o onset detection object as returned by new_aubio_onset()
   \return minimum interval between two consecutive onsets (in
   milliseconds)
 
@@ -222,7 +232,7 @@ smpl_t aubio_onset_get_minioi_ms(aubio_onset_t * o);
 
 /** get minimum inter onset interval in samples
 
-  \param o onset detection object as returned by ::new_aubio_onset
+  \param o onset detection object as returned by new_aubio_onset()
   \return constant system delay to take back from detection time
   (in samples)
 
@@ -231,7 +241,7 @@ uint_t aubio_onset_get_delay(aubio_onset_t * o);
 
 /** get minimum inter onset interval in seconds
 
-  \param o onset detection object as returned by ::new_aubio_onset
+  \param o onset detection object as returned by new_aubio_onset()
   \return constant system delay to take back from detection time
   (in seconds)
 
@@ -240,7 +250,7 @@ smpl_t aubio_onset_get_delay_s(aubio_onset_t * o);
 
 /** get minimum inter onset interval in milliseconds
 
-  \param o onset detection object as returned by ::new_aubio_onset
+  \param o onset detection object as returned by new_aubio_onset()
   \return constant system delay to take back from detection time
   (in milliseconds)