From f72364db4c34eac3550cf98dca20641e9aca81f7 Mon Sep 17 00:00:00 2001
From: Paul Brossier <piem@piem.org>
Date: Sat, 2 Mar 2013 22:29:36 -0500
Subject: [PATCH] src/*.h: improve documentation

---
 src/cvec.h      | 34 ++++++++++++++++++++++++++++------
 src/fmat.h      | 14 ++++++++------
 src/fvec.h      | 41 +++++++++++++++++++++++++++++++++++------
 src/lvec.h      | 16 ++++++++++------
 src/mathutils.h |  1 +
 5 files changed, 82 insertions(+), 24 deletions(-)

diff --git a/src/cvec.h b/src/cvec.h
index aeff6e01..0e92b7cf 100644
--- a/src/cvec.h
+++ b/src/cvec.h
@@ -37,7 +37,29 @@ extern "C" {
 
 */
 
-/** Buffer for complex data */
+/** Buffer for complex data
+
+  \code
+
+  uint_t buffer_size = 1024;
+
+  // create a complex vector of 512 values
+  cvec_t * input = new_cvec (buffer_size);
+
+  // set some values of the vector
+  input->norm[23] = 2.;
+  input->phas[23] = M_PI;
+  // ..
+
+  // compute the mean of the vector
+  mean = cvec_mean(input);
+
+  // destroy the vector
+  del_cvec (input);
+
+  \endcode
+
+ */
 typedef struct {
   uint_t length;  /**< length of buffer = (requested length)/2 + 1 */
   smpl_t *norm;   /**< norm array of size ::cvec_t.length */
@@ -68,7 +90,7 @@ void del_cvec(cvec_t *s);
   result can be obtained by assigning vec->norm[position]. Its purpose
   is to access these values from wrappers, as created by swig.
 
-  \param s vector to write to 
+  \param s vector to write to
   \param data norm value to write in s->norm[position]
   \param position sample position to write to
 
@@ -129,9 +151,9 @@ smpl_t * cvec_get_norm(cvec_t *s);
 */
 smpl_t * cvec_get_phas(cvec_t *s);
 
-/** print out cvec data 
+/** print out cvec data
 
-  \param s vector to print out 
+  \param s vector to print out
 
 */
 void cvec_print(cvec_t *s);
@@ -144,14 +166,14 @@ void cvec_print(cvec_t *s);
 */
 void cvec_set(cvec_t *s, smpl_t val);
 
-/** set all elements to zero 
+/** set all elements to zero
 
   \param s vector to modify
 
 */
 void cvec_zeros(cvec_t *s);
 
-/** set all elements to ones 
+/** set all elements to ones
 
   \param s vector to modify
 
diff --git a/src/fmat.h b/src/fmat.h
index 9d21d3d6..4c52a844 100644
--- a/src/fmat.h
+++ b/src/fmat.h
@@ -27,18 +27,20 @@ extern "C" {
 
 /** \file
 
-  Real buffers
+  Matrix of real valued data
 
-  This file specifies the fmat_t type, which is used in aubio to store real
-  valued arrays.
+  This file specifies the fmat_t type, which is used in aubio to store arrays
+  of floating point values.
+
+  \example test-fmat.c
 
 */
 
 /** Buffer for real data */
 typedef struct {
-  uint_t length;   /**< length of buffer */
-  uint_t height; /**< number of channels */
-  smpl_t **data;   /**< data array of size [length] * [channels] */
+  uint_t length; /**< length of matrix */
+  uint_t height; /**< height of matrix */
+  smpl_t **data; /**< data array of size [length] * [height] */
 } fmat_t;
 
 /** fmat_t buffer creation function
diff --git a/src/fvec.h b/src/fvec.h
index e08814ea..b00a651b 100644
--- a/src/fvec.h
+++ b/src/fvec.h
@@ -27,17 +27,46 @@ extern "C" {
 
 /** \file
 
-  Real buffers
+  Vector of real-valued data
 
-  This file specifies the fvec_t buffer type, which is used throughout aubio to
-  store real data.
+  This file specifies the ::fvec_t buffer type, which is used throughout aubio
+  to store vector of real-valued ::smpl_t.
+
+  \example test-fvec.c
 
 */
 
-/** Buffer for real data */
+/** Buffer for real data
+
+  Vector of real-valued data
+
+  ::fvec_t is is the structure used to store vector of real-valued data, ::smpl_t .
+
+  \code
+
+  uint_t buffer_size = 1024;
+
+  // create a vector of 512 values
+  fvec_t * input = new_fvec (buffer_size);
+
+  // set some values of the vector
+  input->data[23] = 2.;
+  // ..
+
+  // compute the mean of the vector
+  mean = fvec_mean(a_vector);
+
+  // destroy the vector
+  del_fvec(a_vector);
+
+  \endcode
+
+  See `examples/` and `tests/src` directories for more examples.
+
+ */
 typedef struct {
-  uint_t length;   /**< length of buffer */
-  smpl_t *data;   /**< data array of size [length] */
+  uint_t length;  /**< length of buffer */
+  smpl_t *data;   /**< data vector of length ::fvec_t.length */
 } fvec_t;
 
 /** fvec_t buffer creation function
diff --git a/src/lvec.h b/src/lvec.h
index 94fc8c6c..5bf0bce1 100644
--- a/src/lvec.h
+++ b/src/lvec.h
@@ -27,18 +27,22 @@ extern "C" {
 
 /** \file
 
-  Real buffers
+  Vector of real-valued data in double precision
 
-  This file specifies the lvec_t buffer type, which is used in aubio to store
-  double precision real data. Note that the lvec_t data type is mostly used for
-  IIR filters (see temporal/filter.h).
+  This file specifies the ::lvec_t buffer type, which is used in some places in
+  aubio to store a vector of ::lsmp_t.
+
+  Note: the lvec_t data type is required in some algorithms such as IIR filters
+  (see temporal/filter.h).
+
+  \example test-lvec.c
 
 */
 
 /** Buffer for real data in double precision */
 typedef struct {
-  uint_t length;   /**< length of buffer */
-  lsmp_t *data;   /**< data array of size [length] */
+  uint_t length; /**< length of buffer */
+  lsmp_t *data;  /**< data array of size [length] */
 } lvec_t;
 
 /** lvec_t buffer creation function
diff --git a/src/mathutils.h b/src/mathutils.h
index 31c01f3f..01142dd3 100644
--- a/src/mathutils.h
+++ b/src/mathutils.h
@@ -23,6 +23,7 @@
   Various math functions
 
   \example test-mathutils.c
+  \example test-mathutils-window.c
 
  */
 
-- 
2.26.2