Comment rewrite

include/math/matmul.hpp

@@ -31,7 +31,7 @@
  * Functions to print out tensors with std::cout << x std::endl;
  *
  *++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
-#pragma one
+#pragma once
 //---------------------------------------------------------------------------------------------------------------------------
 // INCLUDE DESCRIPTION
 //-----------------------------------------------------------------------------------------------------
@@ -50,55 +50,45 @@
 namespace panic{
 namespace math{
 
-//--------------------------------------------------------------------------------------------------------------------------
-// Function Name : panic::math::matmul
-//
-// Description:
-//   	Multiplies to panic::tensor::real_matrix
-//		C(2,4) = A(2,3) * B(3,4)
-//
-// 	Inputs:
-//
-//   A           	const panic::tensor::real_matrix&
-//
-//	 B				const panic::tensor::real_matrix&
-//
-// Outputs:
-//   C 				panic::tensor::real_matrix&
-//
-// Returns:
-//   bool
-//
-// Notes:
-//		If input matrix dimentions are not correct, output is a empty matrix and returns false.
-//  	The C matrix is resized if nessessary.
-//--------------------------------------------------------------------------------------------------------------------------
+/**
+ * @brief Calculates matrix multiplication of two matrices.
+ *
+ * Computes:
+ * @code
+ * C(n, p) = A(n,m) + B(m,p)
+ * @endcode
+ *
+ * @tparam T Numeric element type.
+ * @param A First matrix.
+ * @param B Second matrix. @ p B.rows needs to be the size of @p A.cols.
+ * @param C Output matrix. Resized to C(A.rows, B.cols).
+ *
+ * @return true if @p C was resized and filled successfully.
+ * @return false if resizing @p C failed or A==B.
+ *
+ * @note This overload writes the result into an existing matrix to avoid
+ *       unnecessary temporary allocations.
+ */
 template <typename T>
 bool matmul(const panic::tensor::matrix<T>& A, const panic::tensor::matrix<T>& B, panic::tensor::matrix<T>& C);
 
-//--------------------------------------------------------------------------------------------------------------------------
-// Function Name : panic::math::matmul
-//
-// Description:
-//   	Multiplies to panic::tensor::real_matrix
-//		C(2,4) = A(2,3) * B(3,4)
-//
-// 	Inputs:
-//
-//   A           	const panic::tensor::real_matrix&
-//
-//	 B				const panic::tensor::real_matrix&
-//
-// Outputs:
-//   None. 				
-//
-// Returns:
-//   C 				panic::tensor::real_matrix&
-//
-// Notes:
-//		If input matrix dimentions are not correct, returns an a empty matrix.
-//   	Creates new matrix, C, for the result.
-//--------------------------------------------------------------------------------------------------------------------------
+/**
+ * @brief Returns a new matrix of multiplication of two matrices.
+ *
+ * Computes:
+ * @code
+ * result(n, p) = A(n,m) + B(m,p)
+ * @endcode
+ *
+ * @tparam T Numeric element type.
+ * @param A First matrix.
+ * @param B Second matrix. @ p B.rows needs to be the size of @p A.cols.
+ *
+ * @return A new matrix containing the result.
+ * @return An empty vector if the operation fails.
+ *
+ * @note This overload is convenient, but may allocate a new matrix.
+ */
 template <typename T>
 panic::tensor::matrix<T> matmul(const panic::tensor::matrix<T>& A, const panic::tensor::matrix<T>& B);