[batchnorm] add basic documentation, shuffle declarations to match usage order

diff --git a/src/ai/batchnorm.h b/src/ai/batchnorm.h
index 6c0e44f..8d389a5 100644 (file)
--- a/src/ai/batchnorm.h
+++ b/src/ai/batchnorm.h
@@ -21,10 +21,6 @@
 #ifndef AUBIO_BATCHNORM_H
 #define AUBIO_BATCHNORM_H
 
-#ifdef __cplusplus
-extern "C" {
-#endif
-
 /** \file
 
  Batch normalization layer.
@@ -38,27 +34,142 @@ extern "C" {
 
 */
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** batch normalization layer */
 typedef struct _aubio_batchnorm_t aubio_batchnorm_t;
 
+/** create a new batch normalization layer
+
+  This layer takes no parameters. The number of output channels will be
+  determined as the inner-most dimension of the input tensor when calling
+  ::aubio_batchnorm_get_output_shape.
+
+*/
 aubio_batchnorm_t *new_aubio_batchnorm(void);
 
-void aubio_batchnorm_do(aubio_batchnorm_t *t,
-        aubio_tensor_t *input_tensor,
-        aubio_tensor_t *activations);
+/** get output shape of the layer
 
-uint_t aubio_batchnorm_set_gamma(aubio_batchnorm_t *t, fvec_t *gamma);
-uint_t aubio_batchnorm_set_beta(aubio_batchnorm_t *t, fvec_t *beta);
-uint_t aubio_batchnorm_set_moving_mean(aubio_batchnorm_t *t, fvec_t *moving_mean);
-uint_t aubio_batchnorm_set_moving_variance(aubio_batchnorm_t *t, fvec_t *moving_variance);
+  \param t      ::aubio_batchnorm_t layer
+  \param input  input tensor
+  \param shape  output shape
+
+  This function determines the number of output channels required and allocate
+  the vectors of weights. The ouptut shape of this layer is identical to the
+  input shape.
+
+*/
+uint_t aubio_batchnorm_get_output_shape(aubio_batchnorm_t *t,
+        aubio_tensor_t *input, uint_t *shape);
 
+/** get a pointer to the gamma vector
+
+  \param t  ::aubio_batchnorm_t layer
+
+  \return   pointer to `fvec_t` holding the gamma parameters
+
+  When called after ::aubio_batchnorm_get_output_shape, this function will
+  return a pointer to the vector allocated to hold the `gamma` weights.
+
+  A NULL pointer will be returned if ::aubio_batchnorm_get_output_shape has not
+  been called yet.
+
+*/
 fvec_t *aubio_batchnorm_get_gamma(aubio_batchnorm_t *t);
+
+/** get a pointer to the beta vector
+
+  \param t  ::aubio_batchnorm_t layer
+
+  \return   pointer to `fvec_t` holding the beta parameters
+*/
 fvec_t *aubio_batchnorm_get_beta(aubio_batchnorm_t *t);
+
+/** get a pointer to the moving mean vector
+
+  \param t  ::aubio_batchnorm_t layer
+
+  \return   pointer to `fvec_t` holding the moving mean parameters
+
+*/
 fvec_t *aubio_batchnorm_get_moving_mean(aubio_batchnorm_t *t);
+
+/** get a pointer to the moving variance vector
+
+  \param t  ::aubio_batchnorm_t layer
+
+  \return   pointer to `fvec_t` holding the moving variance parameters
+
+*/
 fvec_t *aubio_batchnorm_get_moving_variance(aubio_batchnorm_t *t);
 
-uint_t aubio_batchnorm_get_output_shape(aubio_batchnorm_t *t,
-        aubio_tensor_t *input, uint_t *shape);
+/** set gamma vector of batchnorm layer
+
+  \param t      ::aubio_batchnorm_t layer
+  \param gamma  ::fvec_t containing the weights
+
+  \return   0 on success, non-zero otherwise.
+
+  This function will copy the content of an existing vector into
+  the corresponding vector of weights in `t`.
+
+  Note: to spare a copy and load directly the data in `t`,
+  ::aubio_batchnorm_get_gamma can be used instead.
+
+*/
+uint_t aubio_batchnorm_set_gamma(aubio_batchnorm_t *t, fvec_t *gamma);
+
+/** set beta vector of a batchnorm layer
+
+  \param t      ::aubio_batchnorm_t layer
+  \param beta   ::fvec_t containing the weights
+
+  \return   0 on success, non-zero otherwise.
+
+*/
+uint_t aubio_batchnorm_set_beta(aubio_batchnorm_t *t, fvec_t *beta);
+
+/** set moving mean vector of batchnorm layer
 
+  \param t              ::aubio_batchnorm_t layer
+  \param moving_mean    ::fvec_t containing the weights
+
+  \return   0 on success, non-zero otherwise.
+
+*/
+uint_t aubio_batchnorm_set_moving_mean(aubio_batchnorm_t *t,
+        fvec_t *moving_mean);
+
+/** set moving variance vector of batchnorm layer
+
+  \param t                  ::aubio_batchnorm_t layer
+  \param moving_variance    ::fvec_t containing the weights
+
+  \return   0 on success, non-zero otherwise.
+
+*/
+uint_t aubio_batchnorm_set_moving_variance(aubio_batchnorm_t *t,
+        fvec_t *moving_variance);
+
+/** compute batch normalization layer
+
+  \param t             ::aubio_batchnorm_t layer
+  \param input_tensor  input tensor
+  \param activations   output tensor
+
+  \return   0 on success, non-zero otherwise.
+
+*/
+void aubio_batchnorm_do(aubio_batchnorm_t *t, aubio_tensor_t *input_tensor,
+        aubio_tensor_t *activations);
+
+/** delete batch normalization layer
+
+  \param t  ::aubio_batchnorm_t layer to delete
+
+*/
 void del_aubio_batchnorm(aubio_batchnorm_t *t);
 
 #ifdef __cplusplus