Merge pull request #1164 from z64555/cleanup/doxy_vecmat

Doxy vm_vector_2_matrix functions.

Author: asarium

code/math/vecmat.cpp

@@ -780,7 +780,15 @@ matrix *vm_vec_ang_2_matrix(matrix *m, const vec3d *v, float a)
 	return t;
 }
 
-//generate the vectors for the vm_vector_2_matrix() an vm_vector_2_matrix_norm() functions so we can avoid goto
+/**
+ * @brief Generates a matrix from a normalized fvec.
+ *
+ * @param[in,out] matrix The matrix to generate
+ *
+ * @details The matrix's fvec is used to generate the uvec and rvec
+ *
+ * @sa vm_vector_2_matrix(), vm_vector_2_matrix_norm()
+ */
 void vm_vector_2_matrix_gen_vectors(matrix *m)
 {
 	vec3d *xvec=&m->vec.rvec;
@@ -806,11 +814,6 @@ void vm_vector_2_matrix_gen_vectors(matrix *m)
 	}
 }
 
-//computes a matrix from one or more vectors. The forward vector is required,
-//with the other two being optional.  If both up & right vectors are passed,
-//the up vector is used.  If only the forward vector is passed, a bank of
-//zero is assumed
-//returns ptr to matrix
 matrix *vm_vector_2_matrix(matrix *m, const vec3d *fvec, const vec3d *uvec, const vec3d *rvec)
 {
 	vec3d fvec_norm;
@@ -832,7 +835,6 @@ matrix *vm_vector_2_matrix(matrix *m, const vec3d *fvec, const vec3d *uvec, cons
 	return vm_vector_2_matrix_norm(m, fvec, uvec, rvec);
 }
 
-//quicker version of vm_vector_2_matrix() that takes normalized vectors
 matrix *vm_vector_2_matrix_norm(matrix *m, const vec3d *fvec, const vec3d *uvec, const vec3d *rvec)
 {
 	matrix temp = *m;
@@ -874,7 +876,8 @@ matrix *vm_vector_2_matrix_norm(matrix *m, const vec3d *fvec, const vec3d *uvec,
 			temp.vec.fvec = *fvec;
 
 			vm_vector_2_matrix_gen_vectors(&temp);
-		} else {
+		}
+		else {
 			//normalize new perpendicular vector
 			vm_vec_normalize(xvec);
 

code/math/vecmat.h

@@ -237,15 +237,39 @@ matrix *vm_angle_2_matrix(matrix *m, float a, int angle_index);
 //computes a matrix from a forward vector and an angle
 matrix *vm_vec_ang_2_matrix(matrix *m, const vec3d *v, float a);
 
-//computes a matrix from one or more vectors. The forward vector is required,
-//with the other two being optional.  If both up & right vectors are passed,
-//the up vector is used.  If only the forward vector is passed, a bank of
-//zero is assumed
-//returns ptr to matrix
+/**
+ * @brief Generates a matrix from one or more vectors
+ *
+ * @param[out] matrix The generated matrix. Does not need to be an Identity matrix
+ * @param[in] fvec Vector referencing the forward direction
+ * @param[in] uvec Vector referencing the up direction (Optional)
+ * @param[in] rvec Vector referencing the right-hand direction (Optional)
+ *
+ * @returns Pointer to the generated matrix
+ *
+ * @note If all three vectors are given, rvec is ignored.
+ * @note If uvec was bogus (either being in the same direction of fvec or -fvec) then only fvec is used
+ *
+ * @sa vm_vector_2_matrix_norm
+ */
 matrix *vm_vector_2_matrix(matrix *m, const vec3d *fvec, const vec3d *uvec, const vec3d *rvec);
 
-//this version of vector_2_matrix requires that the vectors be more-or-less
-//normalized and close to perpendicular
+
+/**
+ * @brief Generates a matrix from one or more normalized vectors
+ *
+ * @param[out] matrix The generated matrix. Does not need to be an Identity matrix
+ * @param[in] fvec Normalized Vector referencing the forward direction
+ * @param[in] uvec Normalized Vector referencing the up direction (Optional)
+ * @param[in] rvec Normalized Vector referencing the right-hand direction (Optional)
+ *
+ * @returns Pointer to the generated matrix
+ *
+ * @note If all three vectors are given, rvec is ignored.
+ * @note If uvec was bogus (either being in the same direction of fvec or -fvec) then only fvec is used
+ *
+ * @sa vm_vector_2_matrix
+ */
 matrix *vm_vector_2_matrix_norm(matrix *m, const vec3d *fvec, const vec3d *uvec = NULL, const vec3d *rvec = NULL);
 
 //rotates a vector through a matrix. returns ptr to dest vector