[conv2d] add basic documentation

diff --git a/src/ai/conv2d.h b/src/ai/conv2d.h
index bd7eca4..e23f17d 100644 (file)
--- a/src/ai/conv2d.h
+++ b/src/ai/conv2d.h
@@ -21,46 +21,157 @@
 #ifndef AUBIO_CONV2D_H
 #define AUBIO_CONV2D_H
 
+/** \file
+
+  Convolutional layer (2D)
+
+  Standard implementation of a 2D 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
 
+/** conv2d layer */
 typedef struct _aubio_conv2d_t aubio_conv2d_t;
 
-/** create a new conv2d layer */
-aubio_conv2d_t *new_aubio_conv2d(uint_t filters, uint_t *kernel_shape);
-
-/** perform forward 2D convolution */
-void aubio_conv2d_do(aubio_conv2d_t *t, aubio_tensor_t *input_tensor,
-        aubio_tensor_t *activations);
+/** create a new conv2d layer
 
-/** TODO: implement */
-void aubio_conv2d_train(aubio_conv2d_t *t, aubio_tensor_t *input_tensor);
+  \param n_filters number of filters
+  \param kernel_shape shape of each filter
 
-/** set internal kernel weights */
-uint_t aubio_conv2d_set_kernel(aubio_conv2d_t *t, aubio_tensor_t *kernel);
+  \return new conv2d layer
 
-/** get conv2d weights */
-aubio_tensor_t *aubio_conv2d_get_kernel(aubio_conv2d_t *t);
+*/
+aubio_conv2d_t *new_aubio_conv2d(uint_t n_filters, uint_t kernel_shape[2]);
 
-/** set internal biases */
-uint_t aubio_conv2d_set_bias(aubio_conv2d_t *t, fvec_t *bias);
+/** set padding mode
 
-/** get conv2d biases */
-fvec_t *aubio_conv2d_get_bias(aubio_conv2d_t *t);
+  \param c                  layer
+  \param padding_mode       padding mode
 
-/** set conv2d stride */
-uint_t aubio_conv2d_set_stride(aubio_conv2d_t *c,
-    uint_t stride[2]);
+  \return 0 on success, non-zero otherwise
 
-uint_t *aubio_conv2d_get_stride(aubio_conv2d_t* t);
+  Available padding: "same", and "valid".
 
+*/
 uint_t aubio_conv2d_set_padding_mode(aubio_conv2d_t *c,
     const char_t *padding_mode);
 
+/** set stride
+
+  \param c      layer
+  \param stride array of length 2 containing the strides
+
+  \return 0 on success, non-zero otherwise
+
+*/
+uint_t aubio_conv2d_set_stride(aubio_conv2d_t *c, uint_t stride[2]);
+
+/** get current stride settings
+
+  \param t  layer
+
+  \return   array of length 2 containing the stride in each dimension
+
+*/
+uint_t *aubio_conv2d_get_stride(aubio_conv2d_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_conv2d_set_stride or
+  ::aubio_conv2d_set_padding_mode, and before ::aubio_conv2d_get_kernel or
+  ::aubio_conv2d_get_bias.
+
+*/
 uint_t aubio_conv2d_get_output_shape(aubio_conv2d_t *t,
         aubio_tensor_t *input_tensor, uint_t *shape);
 
+/** get kernel weights
+
+  \param t  ::aubio_conv2d_t layer
+
+  \return tensor of weights
+
+  When called after ::aubio_conv2d_get_output_shape, this function will return
+  a pointer to the tensor holding the weights of this layer.
+
+*/
+aubio_tensor_t *aubio_conv2d_get_kernel(aubio_conv2d_t *t);
+
+/** get biases
+
+  \param t layer
+
+  \return vector of biases
+
+  When called after ::aubio_conv2d_get_output_shape, this function will return
+  a pointer to the vector holding the biases.
+
+*/
+fvec_t *aubio_conv2d_get_bias(aubio_conv2d_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_conv2d_get_output_shape.
+
+*/
+uint_t aubio_conv2d_set_kernel(aubio_conv2d_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_conv2d_get_output_shape.
+
+*/
+uint_t aubio_conv2d_set_bias(aubio_conv2d_t *t, fvec_t *bias);
+
+/** compute layer output
+
+  \param t              layer
+  \param input_tensor   input tensor
+  \param output_tensor  output tensor
+
+  Perform 2D convolution.
+
+*/
+void aubio_conv2d_do(aubio_conv2d_t *t, aubio_tensor_t *input_tensor,
+        aubio_tensor_t *output_tensor);
+
+/** destroy conv2d layer
+
+  \param t  layer
+
+*/
 void del_aubio_conv2d(aubio_conv2d_t *t);
 
 #ifdef __cplusplus