Improved vector and matrix documentation on C++ extension

Documentation/Doxygen/dsp.dxy.in

@@ -773,7 +773,7 @@ SHOW_FILES             = YES
 # Folder Tree View (if specified).
 # The default value is: YES.
 
-SHOW_NAMESPACES        = YES
+SHOW_NAMESPACES        = NO
 
 # The FILE_VERSION_FILTER tag can be used to specify a program or script that
 # doxygen should invoke to get the current version for each file (typically from
@@ -2430,7 +2430,7 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             = ARM_MATH_NEON=1 ARM_FLOAT16_SUPPORTED=1 __STATIC_FORCEINLINE= __ALIGNED(x)=
+PREDEFINED             = HAS_VECTOR HAS_PREDICATED_LOOP ARM_MATH_NEON=1 ARM_FLOAT16_SUPPORTED=1 __STATIC_FORCEINLINE= __ALIGNED(x)=
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

dsppp/Include/dsppp/algorithms.hpp

@@ -2,13 +2,11 @@
 /** @file */ 
 #pragma once 
 
-/** \addtogroup DSPPP C++ extension
+/** \defgroup DSPPP C++ extension
  *  C++ template extension to CMSIS-DSP. It is not yet part of
  *  the pack but the headers can be found on the 
  *  [CMSIS-DSP github](https://github.com/ARM-software/CMSIS-DSP/dsppp/Include)
  *  The principles are described in this @ref dsppp_main "page"
- *  @{
- *  @}
  */
 
 
@@ -22,7 +20,7 @@ namespace arm_cmsis_dsp {
 
 /** \addtogroup ALGO Architecture independent algorithms
  *  \ingroup DSPPP
- *  @{
+ *  Algorithms written in an architecture independent way
  */
 
 /*
@@ -32,13 +30,16 @@ Matrix transpose
 */
 
 
-/**
- * Transpose a matrix.
- *
- * @param dst Destination matrix.
- * @param src Source matrix.
- *
- */
+
+ /** @ingroup ALGO
+  *  @brief Transpose a matrix.
+  *
+  * @tparam MA Any matrix type
+  * @tparam MB Any matrix type
+  * @param dst Destination matrix.
+  * @param src Source matrix.
+  *
+  */
 template<typename MA,
          typename MB,
          typename std::enable_if<
@@ -52,6 +53,7 @@ inline void transposeTo(MA &dst,
 }
 
 
+
 /*
 
 Init a diagonal matrix (0 outside of diagonal)
@@ -110,7 +112,17 @@ inline void _identity(Matrix<P,R,R,A> &v,
 }
 
 
-
+/**
+ * @ingroup ALGO
+ * @brief Matrix x Vector product.
+ *
+ * @tparam M Any matrix type
+ * @tparam V Any vector type
+ * @param m matrix.
+ * @param v vector.
+ * @return The matrix x vector product
+ *
+ */
 template<typename M,
          typename V,
          typename std::enable_if<CompatibleStaticMatVecProduct<M,V>::value,bool>::type = true>
@@ -141,6 +153,17 @@ inline void dot(RES && res,const M&m,const V&v)
    _dot_m_v(res,m,v,CURRENT_ARCH);
 }
 
+
+ /** @ingroup ALGO
+  *  @brief Matrix x Matrix product.
+  *
+  * @tparam MA Any matrix type
+  * @tparam MB Any matrix type
+  * @param ma Matrix.
+  * @param mb Matrix.
+  * @return ma x mb matrix product
+  *
+  */
 template<typename MA,
          typename MB,
          typename std::enable_if<CompatibleStaticMatMatProduct<MA,MB>::value &&
@@ -197,13 +220,21 @@ inline typename OutputMatrix<MA,MB>::type dot(const MA&ma,const MB&mb)
    return(res);
 }
 
-/*
-
-
-Get res matrix as argument to avoid memory allocation when
-assigning the result to a different type of Matrix (like a Matrix view).
-
-*/
+ /** @ingroup ALGO
+  *  @brief Matrix x Matrix product
+  *
+  * @tparam MA Any matrix type
+  * @tparam MB Any matrix type
+  * @tparam RES Any matrix type
+  * @param res Output matrix. Result of ma x mb is written to this argument
+  * @param ma Matrix.
+  * @param mb Matrix.
+  * 
+  * Used in dynamic mode (dimension of matrix not know at build time)
+  * to avoid a memory allocation if the result matrix is already available
+  * (Enable to reuse the same matrix storage for the result in some algorithms)
+  *
+  */
 template<typename MA,
          typename MB,
          typename RES,
@@ -246,7 +277,14 @@ inline typename OutputMatrix<MA,MB>::type dot(const MA&ma,const MB&mb,const TMP
 }
 
 
-
+ /** @ingroup ALGO
+  *  @brief Create identity matrix
+  *
+  * @tparam P Datatype of matrix elements
+  * @param l Dimension of matrix (l x l)
+  * @return Identity matrix. It is a dynamic matrix (size not know at build time)
+  * 
+  */
 template<typename P>
 Matrix<P,DYNAMIC,DYNAMIC,TMP_ALLOC> mk_identity(const vector_length_t l)
 {
@@ -256,6 +294,14 @@ Matrix<P,DYNAMIC,DYNAMIC,TMP_ALLOC> mk_identity(const vector_length_t l)
 };
 
 
+ /** @ingroup ALGO
+  *  @brief Create identity matrix
+  *
+  * @tparam P Datatype of matrix elements
+  * @tparam L Matrix dimension (L x L)
+  * @return Identity matrix. It is a static matrix : size known at build time.
+  * 
+  */
 template<typename P,int L>
 Matrix<P,L,L,TMP_ALLOC> mk_identity()
 {
@@ -264,6 +310,4 @@ Matrix<P,L,L,TMP_ALLOC> mk_identity()
        return(res);
 };
 
-/*! @} */
-
 }

dsppp/Include/dsppp/matrix.hpp

@@ -463,56 +463,111 @@ struct VecRef<Matrix<P,R,C,A>,((R<0) || (C<0))>
  * 
  ****************/
 
+/**
+ * @brief  Outer product operator for expressions
+ *
+ * @tparam LHS Left hand side datatype
+ * @tparam RHS Right hand side datatype
+ * @tparam DerivedOp Operator for the Outer operation
+ * 
+ * vector `op` vector (including matrix)
+ */
 template<typename LHS,typename RHS,typename DerivedOp>
 struct _Outer: _Expr<_Outer<LHS,RHS,DerivedOp>>
 {
+    //! Type of vector elements
     using Scalar = typename traits<LHS>::Scalar;
 #if defined(HAS_VECTOR)
+    //! Type of vector in the architecture
     using Vector = typename traits<LHS>::Vector;
 #endif
+    /**
+    * @brief      Create an Outer operator
+    *
+    * @param lhs Left hand side expression
+    * @param rhs Right hand side expression
+    * @param op operator
+    */
     _Outer(const LHS &lhs,
             const RHS &rhs,
             const _BinaryOperator<Scalar,DerivedOp> &op):
             lhs_(lhs),rhs_(rhs),op_(op){
     }
 
-
+    /**
+    * @brief      Create an Outer operator from another operator of same type
+    *
+    * @param other the other operator
+    */
     _Outer(const _Outer &other):
     lhs_(other.lhs_),rhs_(other.rhs_),op_(other.op_){
     }
 
     _Outer& operator=(const _Outer& other) = delete;
     _Outer& operator=(_Outer&& other) = delete;
 
+    /**
+    * @brief   Move semantic for _Outer operator
+    *
+    * @param other the other operator
+    */
     _Outer(_Outer &&other): 
     lhs_(std::move(other.lhs_)),rhs_(std::move(other.rhs_)),op_(std::move(other.op_))
     {
     }
 
 
 
+    /**
+    * @brief   Length of the matrix (seen as vector) resulting from the outer operator
+    * @tparam R Right hand side datatype
+    * @tparam L Left hand side datatype
+    *
+    * @return  vector dimension
+    */
     template<typename R=RHS, typename L=LHS,
              typename std::enable_if<IsVector<L>::value && IsVector<R>::value,bool>::type = true>
     vector_length_t length() const {
         return(lhs_.length() * rhs_.length());
     }
 
+    /**
+    * @brief   Rows of the matrix
+    * @tparam R Right hand side datatype
+    * @tparam L Left hand side datatype
+    *
+    * @return  number of rows
+    */
     template<typename R=RHS, typename L=LHS,
              typename std::enable_if<IsVector<L>::value,bool>::type = true>
     vector_length_t rows() const {
         return(lhs_.length());
     }
 
 
-
+    /**
+    * @brief   Columns of the matrix
+    * @tparam R Right hand side datatype
+    * @tparam L Left hand side datatype
+    *
+    * @return  number of columns
+    */
     template<typename R=RHS, typename L=LHS,
              typename std::enable_if<IsVector<R>::value,bool>::type = true>
     vector_length_t columns() const {
         return(rhs_.length());
     }
 
 
-
+    /**
+    * @brief   Expression value at given position
+    * @tparam R Right hand side datatype
+    * @tparam L Left hand side datatype
+    * @param r row index
+    * @param c column index
+    *
+    * @return  expression value
+    */
     template<typename R=RHS, typename L=LHS,
              typename std::enable_if<IsVector<L>::value && 
                         IsVector<R>::value,bool>::type = true>
@@ -523,13 +578,25 @@ struct _Outer: _Expr<_Outer<LHS,RHS,DerivedOp>>
 
 
 #if defined(HAS_VECTOR)
-    /*************
+    /*
      * 
      * For matrix
      * 
      */
 
     /* V + V */
+
+    /**
+    * @brief   Expression vector value at given position
+    * @tparam R Right hand side datatype
+    * @tparam L Left hand side datatype
+    * @param r row index
+    * @param c column index
+    *
+    * @return  expression vector value
+    *
+    * Vector + Vector (matrix interpreted as a Vector)
+    */
     template<typename R=RHS, typename L=LHS,
              typename std::enable_if<IsVector<L>::value && 
                         IsVector<R>::value,bool>::type = true>
@@ -538,6 +605,18 @@ struct _Outer: _Expr<_Outer<LHS,RHS,DerivedOp>>
         return(op_(lhs_[r],rhs_.vector_op(c)));
     }
 
+    /**
+    * @brief   Expression vector value at given position with tail predication
+    * @tparam R Right hand side datatype
+    * @tparam L Left hand side datatype
+    * @param r row index
+    * @param c column index
+    * @param remaining remaining number of samples in loop
+    *
+    * @return  expression vector value
+    *
+    * Vector + Vector (matrix interpreted as a Vector)
+    */
     template<typename R=RHS, typename L=LHS,
              typename std::enable_if<IsVector<L>::value && 
                         IsVector<R>::value,bool>::type = true>
@@ -623,6 +702,16 @@ struct NbCols<_Outer<LHS,RHS,OP>>
 };
 
 
+/**
+* @brief   Outer product
+* @tparam VA Right hand side datatype
+* @tparam VB Left hand side datatype
+* @param a Vector a
+* @param b Vector b
+*
+* @return  Outer product of a and b
+*
+*/
 template<typename VA,typename VB,
 typename std::enable_if<vector_idx_pair<VA,VB>(),bool>::type = true>
 inline auto outer(const VA&a,const VB&b)