[conv1d] add basic documentation

diff --git a/src/ai/conv1d.h b/src/ai/conv1d.h
index 5a951ac..4d52276 100644 (file)
--- a/src/ai/conv1d.h
+++ b/src/ai/conv1d.h
@@ -21,37 +21,160 @@
 #ifndef AUBIO_CONV1D_H
 #define AUBIO_CONV1D_H
 
+/** \file
+
+  Convolutional layer (1D)
+
+  Standard implementation of a 1D convolutional layer, partly optimized for
+  CPU.
+
+  Note
+  ----
+  Only the forward pass is implemented for now.
+
+  References
+  ----------
+  Vincent Dumoulin, Francesco Visin - A guide to convolution arithmetic for
+  deep learning. https://github.com/vdumoulin/conv_arithmetic
+
+*/
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/** conv1d layer */
 typedef struct _aubio_conv1d_t aubio_conv1d_t;
 
-/** create a new conv1d layer */
-aubio_conv1d_t *new_aubio_conv1d(uint_t filters, uint_t kernel_shape[1]);
+/** create a new conv1d layer
 
-/** perform forward 1D convolution */
-void aubio_conv1d_do(aubio_conv1d_t *t, aubio_tensor_t *input_tensor,
-        aubio_tensor_t *activations);
+  \param n_filters number of filters
+  \param kernel_shape length of each filter
 
-/** TODO: implement */
-void aubio_conv1d_train(aubio_conv1d_t *t, aubio_tensor_t *input_tensor);
+  \return new conv1d layer
 
-/** get conv1d weights */
-aubio_tensor_t *aubio_conv1d_get_kernel(aubio_conv1d_t *t);
+*/
+aubio_conv1d_t *new_aubio_conv1d(uint_t n_filters, uint_t kernel_shape[1]);
 
-/** get conv1d biases */
-fvec_t *aubio_conv1d_get_bias(aubio_conv1d_t *t);
+/** set padding mode
 
-/** set conv1d stride */
-uint_t aubio_conv1d_set_stride(aubio_conv1d_t *c, uint_t stride[1]);
+  \param c                  layer
+  \param padding_mode       padding mode
+
+  \return 0 on success, non-zero otherwise
 
+  Available padding: "same", and "valid".
+
+  Todo:
+  - add causal mode
+
+*/
 uint_t aubio_conv1d_set_padding_mode(aubio_conv1d_t *c,
     const char_t *padding_mode);
 
+/** set stride
+
+  \param c      layer
+  \param stride array of length 1 containing the stride parameter
+
+  \return 0 on success, non-zero otherwise
+
+*/
+uint_t aubio_conv1d_set_stride(aubio_conv1d_t *c, uint_t stride[1]);
+
+/** get current stride settings
+
+  \param t  layer
+
+  \return   array of length 1 containing the stride parameter
+
+*/
+uint_t *aubio_conv1d_get_stride(aubio_conv1d_t* t);
+
+/** get output shape
+
+  \param t                  layer
+  \param input_tensor       input tensor
+  \param shape              output shape
+
+  \return 0 on success, non-zero otherwise
+
+  Upon return, `shape` will be filled with the output shape of the layer. This
+  function should be called after ::aubio_conv1d_set_stride or
+  ::aubio_conv1d_set_padding_mode, and before ::aubio_conv1d_get_kernel or
+  ::aubio_conv1d_get_bias.
+
+*/
 uint_t aubio_conv1d_get_output_shape(aubio_conv1d_t *t,
         aubio_tensor_t *input_tensor, uint_t *shape);
 
+/** get kernel weights
+
+  \param t ::aubio_conv1d_t layer
+
+  \return tensor of weights
+
+  When called after ::aubio_conv1d_get_output_shape, this function will return
+  a pointer to the tensor holding the weights of this layer.
+
+*/
+aubio_tensor_t *aubio_conv1d_get_kernel(aubio_conv1d_t *t);
+
+/** get biases
+
+  \param t layer
+
+  \return vector of biases
+
+  When called after ::aubio_conv1d_get_output_shape, this function will return
+  a pointer to the vector holding the biases.
+
+*/
+fvec_t *aubio_conv1d_get_bias(aubio_conv1d_t *t);
+
+/** set kernel weights
+
+  \param t          layer
+  \param kernel     kernel weights
+
+  \return 0 on success, non-zero otherwise
+
+  Copy kernel weights into internal layer memory.  This function should be
+  called after ::aubio_conv1d_get_output_shape.
+
+*/
+uint_t aubio_conv1d_set_kernel(aubio_conv1d_t *t, aubio_tensor_t *kernel);
+
+/** set biases
+
+  \param t          layer
+  \param bias       biases
+
+  \return 0 on success, non-zero otherwise
+
+  Copy vector of biases into internal layer memory. This function should be
+  called after ::aubio_conv1d_get_output_shape.
+
+*/
+uint_t aubio_conv1d_set_bias(aubio_conv1d_t *t, fvec_t *bias);
+
+/** compute layer output
+
+  \param t              layer
+  \param input_tensor   input tensor
+  \param output_tensor  output tensor
+
+  Perform 1D convolution.
+
+*/
+void aubio_conv1d_do(aubio_conv1d_t *t, aubio_tensor_t *input_tensor,
+        aubio_tensor_t *output_tensor);
+
+/** destroy conv1d layer
+
+  \param t  layer
+
+*/
 void del_aubio_conv1d(aubio_conv1d_t *t);
 
 #ifdef __cplusplus