From ea6f12d90a8a9e38f1ec9f561705bb1ccf8445eb Mon Sep 17 00:00:00 2001
From: Recep Aslantas <info@recp.me>
Date: Thu, 29 Sep 2016 10:25:33 +0300
Subject: [PATCH] vector [pure] documentation

---
 include/cglm-mat.h |   2 +-
 include/cglm-vec.h | 120 ++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 120 insertions(+), 2 deletions(-)

diff --git a/include/cglm-mat.h b/include/cglm-mat.h
index 78c1623..dbf5c5e 100644
--- a/include/cglm-mat.h
+++ b/include/cglm-mat.h
@@ -182,7 +182,7 @@ glm_mat4_transpose_to(mat4 m, mat4 dest) {
 }
 
 /*!
- * @brief tranpose mat4 and store result at same matrix
+ * @brief tranpose mat4 and store result in same matrix
  *
  * @param[in, out] m source and dest
  */
diff --git a/include/cglm-vec.h b/include/cglm-vec.h
index 4cae84a..4f42513 100644
--- a/include/cglm-vec.h
+++ b/include/cglm-vec.h
@@ -5,6 +5,11 @@
  * Full license can be found in the LICENSE file
  */
 
+/*!
+ * vec3 functions dont have suffix e.g glm_vec_dot (not glm_vec3_dot)
+ * all functions without suffix are vec3 functions
+ */
+
 #ifndef cglm_vec_h
 #define cglm_vec_h
 
@@ -12,6 +17,12 @@
 #include "cglm-intrin.h"
 #include <math.h>
 
+/*!
+ * @brief copy all members of [a] to [dest]
+ *
+ * @param[in]  a    source
+ * @param[out] dest destination
+ */
 CGLM_INLINE
 void
 glm_vec_dup(vec3 a, vec3 dest) {
@@ -20,6 +31,12 @@ glm_vec_dup(vec3 a, vec3 dest) {
   dest[2] = a[2];
 }
 
+/*!
+ * @brief copy first 3 members of [a] to [dest]
+ *
+ * @param[in]  a    source
+ * @param[out] dest destination
+ */
 void
 glm_vec4_dup3(vec4 a, vec3 dest) {
   dest[0] = a[0];
@@ -27,6 +44,12 @@ glm_vec4_dup3(vec4 a, vec3 dest) {
   dest[2] = a[2];
 }
 
+/*!
+ * @brief copy all members of [a] to [dest]
+ *
+ * @param[in]  a    source
+ * @param[out] dest destination
+ */
 CGLM_INLINE
 void
 glm_vec4_dup(vec4 v, vec4 dest) {
@@ -40,18 +63,41 @@ glm_vec4_dup(vec4 v, vec4 dest) {
 #endif
 }
 
+/*!
+ * @brief vec3 dot product
+ *
+ * @param[in] a
+ * @param[in] b
+ *
+ * @return dot product
+ */
 CGLM_INLINE
 float
 glm_vec_dot(vec3 a, vec3 b) {
   return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
 }
 
+/*!
+ * @brief vec4 dot product
+ *
+ * @param[in] a
+ * @param[in] b
+ *
+ * @return dot product
+ */
 CGLM_INLINE
 float
 glm_vec4_dot(vec4 a, vec4 b) {
   return a[0] * b[0] + a[1] * b[1] + a[2] * b[2] + a[3] * b[3];
 }
 
+/*!
+ * @brief vec3 cross product
+ *
+ * @param[in]  a source 1
+ * @param[in]  b source 2
+ * @param[out] d destination
+ */
 CGLM_INLINE
 void
 glm_vec_cross(vec3 a, vec3 b, vec3 d) {
@@ -61,19 +107,39 @@ glm_vec_cross(vec3 a, vec3 b, vec3 d) {
   d[2] = a[0] * b[1] - a[1] * b[0];
 }
 
+/*!
+ * @brief norm (magnitude) of vec3
+ *
+ * @param[in] vec
+ *
+ * @return norm
+ */
 CGLM_INLINE
 float
 glm_vec_norm(vec3 vec) {
   return sqrtf(vec[0] * vec[0] + vec[1] * vec[1] + vec[2] * vec[2]);
 }
 
+/*!
+ * @brief norm (magnitude) of vec4
+ *
+ * @param[in] vec
+ *
+ * @return norm
+ */
 CGLM_INLINE
 float
-glm_vec4_norm(vec3 vec) {
+glm_vec4_norm(vec4 vec) {
   return sqrtf(vec[0] * vec[0] + vec[1] * vec[1]
                + vec[2] * vec[2] + vec[3] * vec[3]);
 }
 
+/*!
+ * @brief normalize vec3 to dest
+ *
+ * @param[in]  vec  source
+ * @param[out] dest destination
+ */
 CGLM_INLINE
 void
 glm_vec_normalize_to(vec3 vec, vec3 dest) {
@@ -91,6 +157,11 @@ glm_vec_normalize_to(vec3 vec, vec3 dest) {
   dest[2] = vec[2] / norm;
 }
 
+/*!
+ * @brief normalize vec3 and store result in same vec
+ *
+ * @param[in, out] v vector
+ */
 CGLM_INLINE
 void
 glm_vec_normalize(vec3 v) {
@@ -108,6 +179,11 @@ glm_vec_normalize(vec3 v) {
   v[2] = v[2] / norm;
 }
 
+/*!
+ * @brief normalize vec4 and store result in same vec
+ *
+ * @param[in, out] v vector
+ */
 CGLM_INLINE
 void
 glm_vec4_normalize(vec4 v) {
@@ -126,6 +202,13 @@ glm_vec4_normalize(vec4 v) {
   v[3] = v[3] / norm;
 }
 
+/*!
+ * @brief add v2 vector to v1 vector store result in dest
+ *
+ * @param[in]  v1
+ * @param[in]  v2
+ * @param[out] dest destination vector
+ */
 CGLM_INLINE
 void
 glm_vec_add(vec3 v1, vec3 v2, vec3 dest) {
@@ -134,6 +217,13 @@ glm_vec_add(vec3 v1, vec3 v2, vec3 dest) {
   dest[2] = v1[2] + v2[2];
 }
 
+/*!
+ * @brief add v2 vector to v1 vector store result in dest
+ *
+ * @param[in]  v1
+ * @param[in]  v2
+ * @param[out] dest destination vector
+ */
 CGLM_INLINE
 void
 glm_vec4_add(vec4 v1, vec4 v2, vec4 dest) {
@@ -149,6 +239,13 @@ glm_vec4_add(vec4 v1, vec4 v2, vec4 dest) {
 #endif
 }
 
+/*!
+ * @brief subtract v2 vector from v1 vector store result in dest
+ *
+ * @param[in]  v1
+ * @param[in]  v2
+ * @param[out] dest destination vector
+ */
 CGLM_INLINE
 void
 glm_vec_sub(vec3 v1, vec3 v2, vec3 dest) {
@@ -157,6 +254,13 @@ glm_vec_sub(vec3 v1, vec3 v2, vec3 dest) {
   dest[2] = v1[2] - v2[2];
 }
 
+/*!
+ * @brief subtract v2 vector from v1 vector store result in dest
+ *
+ * @param[in]  v1
+ * @param[in]  v2
+ * @param[out] dest destination vector
+ */
 CGLM_INLINE
 void
 glm_vec4_sub(vec4 v1, vec4 v2, vec4 dest) {
@@ -172,6 +276,13 @@ glm_vec4_sub(vec4 v1, vec4 v2, vec4 dest) {
 #endif
 }
 
+/*!
+ * @brief multiply vec3 vector with scalar
+ *
+ * @param[in]  v    vector
+ * @param[in]  s    scalar
+ * @param[out] dest destination vector
+ */
 CGLM_INLINE
 void
 glm_vec_scale(vec3 v, float s, vec3 dest) {
@@ -180,6 +291,13 @@ glm_vec_scale(vec3 v, float s, vec3 dest) {
   dest[2] = v[2] * s;
 }
 
+/*!
+ * @brief multiply vec4 vector with scalar
+ *
+ * @param[in]  v    vector
+ * @param[in]  s    scalar
+ * @param[out] dest destination vector
+ */
 CGLM_INLINE
 void
 glm_vec4_scale(vec4 v, float s, vec4 dest) {