fixes: #371

include/cglm/mat2x3.h

@@ -81,15 +81,13 @@ glm_mat2x3_make(float * __restrict src, mat2x3 dest) {
 /*!
  * @brief multiply m1 and m2 to dest
  *
- * m1, m2 and dest matrices can be same matrix, it is possible to write this:
- *
  * @code
- * glm_mat2x3_mul(m, m, m);
+ * glm_mat2x3_mul(mat2x3, mat3x2, mat2);
  * @endcode
  *
- * @param[in]  m1   left matrix
- * @param[in]  m2   right matrix
- * @param[out] dest destination matrix
+ * @param[in]  m1   left matrix (mat2x3)
+ * @param[in]  m2   right matrix (mat3x2)
+ * @param[out] dest destination matrix (mat2)
  */
 CGLM_INLINE
 void

include/cglm/mat2x4.h

@@ -79,15 +79,13 @@ glm_mat2x4_make(float * __restrict src, mat2x4 dest) {
 /*!
  * @brief multiply m1 and m2 to dest
  *
- * m1, m2 and dest matrices can be same matrix, it is possible to write this:
- *
  * @code
- * glm_mat2x4_mul(m, m, m);
+ * glm_mat2x4_mul(mat2x4, mat4x2, mat2);
  * @endcode
  *
- * @param[in]  m1   left matrix
- * @param[in]  m2   right matrix
- * @param[out] dest destination matrix
+ * @param[in]  m1   left matrix (mat2x4)
+ * @param[in]  m2   right matrix (mat4x2)
+ * @param[out] dest destination matrix (mat2)
  */
 CGLM_INLINE
 void

include/cglm/mat3x2.h

@@ -83,15 +83,13 @@ glm_mat3x2_make(float * __restrict src, mat3x2 dest) {
 /*!
  * @brief multiply m1 and m2 to dest
  *
- * m1, m2 and dest matrices can be same matrix, it is possible to write this:
- *
  * @code
- * glm_mat3x2_mul(m, m, m);
+ * glm_mat3x2_mul(mat3x2, mat2x3, mat3);
  * @endcode
  *
- * @param[in]  m1   left matrix
- * @param[in]  m2   right matrix
- * @param[out] dest destination matrix
+ * @param[in]  m1   left matrix (mat3x2)
+ * @param[in]  m2   right matrix (mat2x3)
+ * @param[out] dest destination matrix (mat3)
  */
 CGLM_INLINE
 void

include/cglm/mat3x4.h

@@ -86,15 +86,13 @@ glm_mat3x4_make(float * __restrict src, mat3x4 dest) {
 /*!
  * @brief multiply m1 and m2 to dest
  *
- * m1, m2 and dest matrices can be same matrix, it is possible to write this:
- *
  * @code
- * glm_mat3x4_mul(m, m, m);
+ * glm_mat3x4_mul(mat3x4, mat4x3, mat3);
  * @endcode
  *
- * @param[in]  m1   left matrix
- * @param[in]  m2   right matrix
- * @param[out] dest destination matrix
+ * @param[in]  m1   left matrix (mat3x4)
+ * @param[in]  m2   right matrix (mat4x3)
+ * @param[out] dest destination matrix (mat3)
  */
 CGLM_INLINE
 void

include/cglm/mat4x2.h

@@ -89,15 +89,13 @@ glm_mat4x2_make(float * __restrict src, mat4x2 dest) {
 /*!
  * @brief multiply m1 and m2 to dest
  *
- * m1, m2 and dest matrices can be same matrix, it is possible to write this:
- *
  * @code
- * glm_mat4x2_mul(m, m, m);
+ * glm_mat4x2_mul(mat4x2, mat2x4, mat4);
  * @endcode
  *
- * @param[in]  m1   left matrix
- * @param[in]  m2   right matrix
- * @param[out] dest destination matrix
+ * @param[in]  m1   left matrix (mat4x2)
+ * @param[in]  m2   right matrix (mat2x4)
+ * @param[out] dest destination matrix (mat4)
  */
 CGLM_INLINE
 void

include/cglm/mat4x3.h

@@ -98,15 +98,13 @@ glm_mat4x3_make(float * __restrict src, mat4x3 dest) {
 /*!
  * @brief multiply m1 and m2 to dest
  *
- * m1, m2 and dest matrices can be same matrix, it is possible to write this:
- *
  * @code
- * glm_mat4x3_mul(m, m, m);
+ * glm_mat4x3_mul(mat4x3, mat3x4, mat4);
  * @endcode
  *
- * @param[in]  m1   left matrix
- * @param[in]  m2   right matrix
- * @param[out] dest destination matrix
+ * @param[in]  m1   left matrix (mat4x3)
+ * @param[in]  m2   right matrix (mat3x4)
+ * @param[out] dest destination matrix (mat4)
  */
 CGLM_INLINE
 void

include/cglm/struct/mat2.h

@@ -108,13 +108,13 @@ glms_mat2_(zero)(void) {
  *
  * @code
  * mat2 m = GLM_MAT2_IDENTITY_INIT;
- * glm_mat2_mul(m, m, m);
+ * r = glms_mat2_mul(m, m);
  * @endcode
  *
  * @param[in]  m1   left matrix
  * @param[in]  m2   right matrix
  *
- * @returns matrix
+ * @returns destination matrix
  */
 CGLM_INLINE
 mat2s

include/cglm/struct/mat2x3.h

@@ -64,15 +64,13 @@ glms_mat2x3_(make)(float * __restrict src) {
 /*!
  * @brief multiply m1 and m2 to dest
  *
- * m1, m2 and dest matrices can be same matrix, it is possible to write this:
- *
  * @code
- * glm_mat2x3_mul(m, m, m);
+ * r = glms_mat2x3_mul(mat2x3s, mat3x2s);
  * @endcode
  *
- * @param[in]  m1   left matrix
- * @param[in]  m2   right matrix
- * @param[out] dest destination matrix
+ * @param[in]  m1   left matrix (mat2x3s)
+ * @param[in]  m2   right matrix (mat3x2s)
+ * @returns destination matrix (mat2s)
  */
 CGLM_INLINE
 mat2s

include/cglm/struct/mat2x4.h

@@ -64,15 +64,13 @@ glms_mat2x4_(make)(float * __restrict src) {
 /*!
  * @brief multiply m1 and m2 to dest
  *
- * m1, m2 and dest matrices can be same matrix, it is possible to write this:
- *
  * @code
- * glm_mat2x4_mul(m, m, m);
+ * r = glms_mat2x4_mul(mat2x4s, mat4x2s);
  * @endcode
  *
- * @param[in]  m1   left matrix
- * @param[in]  m2   right matrix
- * @param[out] dest destination matrix
+ * @param[in]  m1   left matrix (mat2x4s)
+ * @param[in]  m2   right matrix (mat4x2s)
+ * @returns destination matrix (mat2s)
  */
 CGLM_INLINE
 mat2s

include/cglm/struct/mat3.h

@@ -124,12 +124,12 @@ glms_mat3_(zero)(void) {
  *
  * @code
  * mat3 m = GLM_MAT3_IDENTITY_INIT;
- * glm_mat3_mul(m, m, m);
+ * r = glms_mat3_mul(m, m);
  * @endcode
  *
  * @param[in]  m1   left matrix
  * @param[in]  m2   right matrix
- * @returns         destination matrix
+ * @returns destination matrix
  */
 CGLM_INLINE
 mat3s

include/cglm/struct/mat3x2.h

@@ -64,15 +64,13 @@ glms_mat3x2_(make)(float * __restrict src) {
 /*!
  * @brief multiply m1 and m2 to dest
  *
- * m1, m2 and dest matrices can be same matrix, it is possible to write this:
- *
  * @code
- * glm_mat3x2_mul(m, m, m);
+ * r = glms_mat3x2_mul(mat3x2s, mat2x3s);
  * @endcode
  *
- * @param[in]  m1   left matrix
- * @param[in]  m2   right matrix
- * @param[out] dest destination matrix
+ * @param[in]  m1   left matrix (mat3x2s)
+ * @param[in]  m2   right matrix (mat2x3s)
+ * @returns destination matrix (mat3s)
  */
 CGLM_INLINE
 mat3s

include/cglm/struct/mat3x4.h

@@ -64,15 +64,13 @@ glms_mat3x4_(make)(float * __restrict src) {
 /*!
  * @brief multiply m1 and m2 to dest
  *
- * m1, m2 and dest matrices can be same matrix, it is possible to write this:
- *
  * @code
- * glm_mat3x4_mul(m, m, m);
+ * r = glms_mat3x4_mul(mat3x4s, mat4x3s);
  * @endcode
  *
- * @param[in]  m1   left matrix
- * @param[in]  m2   right matrix
- * @param[out] dest destination matrix
+ * @param[in]  m1   left matrix (mat3x4s)
+ * @param[in]  m2   right matrix (mat4x3s)
+ * @returns destination matrix (mat3s)
  */
 CGLM_INLINE
 mat3s

include/cglm/struct/mat4.h

@@ -200,12 +200,12 @@ glms_mat4_(ins3)(mat3s mat, mat4s dest) {
  *
  * @code
  * mat4 m = GLM_MAT4_IDENTITY_INIT;
- * glm_mat4_mul(m, m, m);
+ * r = glms_mat4_mul(m, m);
  * @endcode
  *
  * @param[in]  m1   left matrix
  * @param[in]  m2   right matrix
- * @returns         destination matrix
+ * @returns destination matrix
  */
 CGLM_INLINE
 mat4s

include/cglm/struct/mat4x2.h

@@ -65,15 +65,13 @@ glms_mat4x2_(make)(float * __restrict src) {
 /*!
  * @brief multiply m1 and m2 to dest
  *
- * m1, m2 and dest matrices can be same matrix, it is possible to write this:
- *
  * @code
- * glm_mat4x2_mul(m, m, m);
+ * r = glms_mat4x2_mul(mat4x2s, mat2x4s);
  * @endcode
  *
- * @param[in]  m1   left matrix
- * @param[in]  m2   right matrix
- * @param[out] dest destination matrix
+ * @param[in]  m1   left matrix (mat4x2s)
+ * @param[in]  m2   right matrix (mat2x4s)
+ * @returns destination matrix (mat4s)
  */
 CGLM_INLINE
 mat4s

include/cglm/struct/mat4x3.h

@@ -64,15 +64,13 @@ glms_mat4x3_(make)(float * __restrict src) {
 /*!
  * @brief multiply m1 and m2 to dest
  *
- * m1, m2 and dest matrices can be same matrix, it is possible to write this:
- *
  * @code
- * glm_mat4x3_mul(m, m, m);
+ * r = glms_mat4x3_mul(mat4x3s, mat3x4s);
  * @endcode
  *
- * @param[in]  m1   left matrix
- * @param[in]  m2   right matrix
- * @param[out] dest destination matrix
+ * @param[in]  m1   left matrix (mat4x3s)
+ * @param[in]  m2   right matrix (mat3x4s)
+ * @returns destination matrix (mat4s)
  */
 CGLM_INLINE
 mat4s