documentation fixes

18 files changed, 56 insertions, 42 deletions

diff --git a/doc/specifications.dox b/doc/specifications.dox
index 28746e5..4b305f4 100644
--- a/doc/specifications.dox
+++ b/doc/specifications.dox
@@ -1,5 +1,5 @@
 /**
- * @page spec_training_file Training Input File Specification
+ * @page spec_grid_file Grid Input File Specification
  *
  * This page specifies the training file that can be parsed by
  * read_training_from_file(). Below is an example training file.
diff --git a/include/gensvm_debug.h b/include/gensvm_debug.h
index d95d0eb..361e885 100644
--- a/include/gensvm_debug.h
+++ b/include/gensvm_debug.h
@@ -3,7 +3,7 @@
  * @file gensvm_debug.h
  * @author Gertjan van den Burg
  * @date May, 2016
- * @brief Header for useful debug functions
+ * @brief Header file for gensvm_debug.c
  *
  * @details
  * Contains defines useful for debugging.
diff --git a/include/gensvm_globals.h b/include/gensvm_globals.h
index 96d3b38..74aafd2 100644
--- a/include/gensvm_globals.h
+++ b/include/gensvm_globals.h
@@ -1,5 +1,5 @@
 /**
- * @file globals.h
+ * @file gensvm_globals.h
  * @author Gertjan van den Burg
  * @date January, 2014
  * @brief Global definitions
diff --git a/include/gensvm_grid.h b/include/gensvm_grid.h
index a37ce12..d01aa9c 100644
--- a/include/gensvm_grid.h
+++ b/include/gensvm_grid.h
@@ -2,7 +2,7 @@
  * @file gensvm_grid.h
  * @author Gertjan van den Burg
  * @date May, 2016
- * @brief Structs necessary for the grid search
+ * @brief Header file for gensvm_grid.c
  *
  * @details
  * The grid search for the optimal parameters is done through a queue.
diff --git a/include/gensvm_io.h b/include/gensvm_io.h
index 3f34c1a..6ba14f4 100644
--- a/include/gensvm_io.h
+++ b/include/gensvm_io.h
@@ -2,7 +2,7 @@
  * @file gensvm_io.h
  * @author Gertjan van den Burg
  * @date January, 2014
- * @brief Header files for gensvm_io.c
+ * @brief Header file for gensvm_io.c
  *
  * @details
  * Function declarations for input/output functions.
diff --git a/include/gensvm_kernel.h b/include/gensvm_kernel.h
index a1fac20..b832eb9 100644
--- a/include/gensvm_kernel.h
+++ b/include/gensvm_kernel.h
@@ -2,7 +2,7 @@
  * @file gensvm_kernel.h
  * @author Gertjan van den Burg
  * @date January, 2014
- * @brief Header file for kernel functionality
+ * @brief Header file for gensvm_kernel.c
  *
  * @details
  * Contains function declarations for computing the kernel matrix
diff --git a/include/gensvm_matrix.h b/include/gensvm_matrix.h
deleted file mode 100644
index 9982b78..0000000
--- a/include/gensvm_matrix.h
+++ /dev/null
@@ -1,16 +0,0 @@
-/**
- * @file gensvm_matrix.h
- * @author Gertjan van den Burg
- * @date August, 2013
- * @brief Header with defines for matrix access
- *
- * @details
- * Contains defines useful for dealing with matrices.
- *
- */
-
-#ifndef GENSVM_MATRIX_H
-#define GENSVM_MATRIX_H
-
-
-#endif
diff --git a/include/gensvm_memory.h b/include/gensvm_memory.h
index 08d6f2d..3af95d1 100644
--- a/include/gensvm_memory.h
+++ b/include/gensvm_memory.h
@@ -2,7 +2,10 @@
  * @file gensvm_memory.h
  * @author Gertjan van den Burg
  * @date May, 2016
- * @brief Global definitions
+ * @brief Header file for gensvm_memory.c
+ *
+ * @details
+ * Contains macro definitions for easy memory access.
  *
  */
 
diff --git a/include/gensvm_task.h b/include/gensvm_task.h
index 98c8f26..16ab361 100644
--- a/include/gensvm_task.h
+++ b/include/gensvm_task.h
@@ -2,7 +2,7 @@
  * @file gensvm_task.h
  * @author Gertjan van den Burg
  * @date August, 2013
- * @brief Struct for a single task in the queue
+ * @brief Header file for gensvm_task.c
  *
  * @details
  * The grid search for the optimal parameters is done through a queue.
diff --git a/include/gensvm_timer.h b/include/gensvm_timer.h
index 5dd4dcb..4c541b3 100644
--- a/include/gensvm_timer.h
+++ b/include/gensvm_timer.h
@@ -1,8 +1,8 @@
 /**
- * @file timer.h
+ * @file gensvm_timer.h
  * @author Gertjan van den Burg
  * @date August, 2013
- * @brief Header file for timer.c
+ * @brief Header file for gensvm_timer.c
  *
  * @details
  * Function declaration for timer function used to measure computation time.
diff --git a/src/gensvm_init.c b/src/gensvm_init.c
index e0f44c1..8bee73a 100644
--- a/src/gensvm_init.c
+++ b/src/gensvm_init.c
@@ -27,8 +27,14 @@
  * significant improvement in the number of iterations necessary
  * because the seeded model V is closer to the optimal V.
  *
+ * When no seed model is supplied, the rows of V are seeded with random 
+ * numbers between the inverse of the minimum and the inverse of the maximum 
+ * of the corresponding column of Z. This is done to center the product of the 
+ * two in the simplex space.
+ *
  * @param[in] 		from_model 	GenModel from which to copy V
  * @param[in,out] 	to_model 	GenModel to which V will be copied
+ * @param[in] 		data 		GenData structure with the data
  */
 void gensvm_init_V(struct GenModel *from_model,
 	       	struct GenModel *to_model, struct GenData *data)
diff --git a/src/gensvm_kernel.c b/src/gensvm_kernel.c
index 97328d2..67c063d 100644
--- a/src/gensvm_kernel.c
+++ b/src/gensvm_kernel.c
@@ -98,6 +98,21 @@ void gensvm_kernel_postprocess(struct GenModel *model,
 	free(K2);
 }
 
+/**
+ * @brief Compute the kernel matrix
+ *
+ * @details
+ * This function computes the kernel matrix of a data matrix based on the 
+ * requested kernel type and the kernel parameters. The potential types of 
+ * kernel functions are document in KernelType. This function uses a naive 
+ * multiplication and computes the entire upper triangle of the kernel matrix, 
+ * then copies this over to the lower triangle.
+ *
+ * @param[in] 	model 	a GenModel structure with the model
+ * @param[in] 	data 	a GenData structure with the data
+ * @param[out]	K 	an nxn preallocated kernel matrix
+ *
+ */
 void gensvm_make_kernel(struct GenModel *model, struct GenData *data,
 	       	double *K)
 {
@@ -132,11 +147,17 @@ void gensvm_make_kernel(struct GenModel *model, struct GenData *data,
 }
 
 /**
- * @brief Find the (reduced) eigendecomposition of a kernel matrix.
+ * @brief Find the (reduced) eigendecomposition of a kernel matrix
+ *
+ * @todo
+ * Document this function
  *
- * @details.
- * tbd
+ * @param[in] K
+ * @param[in] n
+ * @param[out] P
+ * @param[out] Sigma
  *
+ * @return
  */
 long gensvm_make_eigen(double *K, long n, double **P, double **Sigma)
 {
diff --git a/src/gensvm_pred.c b/src/gensvm_pred.c
index 1feb14a..afa1ab9 100644
--- a/src/gensvm_pred.c
+++ b/src/gensvm_pred.c
@@ -23,7 +23,7 @@
  * norm. The nearest simplex vertex determines the predicted class label,
  * which is recorded in predy.
  *
- * @param[in] 	data 		GenData to predict labels for
+ * @param[in] 	testdata 	GenData to predict labels for
  * @param[in] 	model 		GenModel with optimized V
  * @param[out] 	predy 		pre-allocated vector to record predictions in
  */
diff --git a/src/gensvm_simplex.c b/src/gensvm_simplex.c
index a704d85..1a853cc 100644
--- a/src/gensvm_simplex.c
+++ b/src/gensvm_simplex.c
@@ -16,14 +16,12 @@
  * @brief Generate matrix of simplex vertex coordinates
  *
  * @details
- * Generate the simplex matrix. Each row of the created
- * matrix contains the coordinate vector of a single
- * vertex of the K-simplex in K-1 dimensions. The simplex
- * generated is a special simplex with edges of length 1.
- * The simplex matrix U must already have been allocated.
+ * Generate the simplex matrix. Each row of the created matrix contains the 
+ * coordinate vector of a single vertex of the K-simplex in K-1 dimensions.  
+ * The simplex generated is a special simplex with edges of length 1. The 
+ * simplex matrix U of the GenModel must already have been allocated.
  *
- * @param[in] 		K 	number of classes
- * @param[in,out] 	U 	simplex matrix of size K * (K-1)
+ * @param[in,out] 	model 	a GenModel structure
  */
 void gensvm_simplex(struct GenModel *model)
 {
diff --git a/src/gensvm_sv.c b/src/gensvm_sv.c
index abfb871..bb5c48c 100644
--- a/src/gensvm_sv.c
+++ b/src/gensvm_sv.c
@@ -21,8 +21,7 @@
  * other classes).  All objects for which this is not the case are thus support
  * vectors.
  *
- * @param[in] 	model 	GenModel with solution
- * @param[in] 	data 	GenData to be used
+ * @param[in] 	model 	GenModel with solution and up-to-date Q matrix
  * @return 		number of support vectors with this solution
  *
  */
diff --git a/src/gensvm_timer.c b/src/gensvm_timer.c
index 0e020fe..18bcad6 100644
--- a/src/gensvm_timer.c
+++ b/src/gensvm_timer.c
@@ -15,7 +15,7 @@
 /**
  * @brief Calculate the time between two time recordings
  *
- * @detail
+ * @details
  * This function should be used with time recordings done by clock_gettime() 
  * using CLOCK_MONOTONIC_RAW. For this, the Timer() macro has been defined in 
  * the header file. Example usage:
diff --git a/src/gensvm_update.c b/src/gensvm_update.c
index 289f50c..59ce3a8 100644
--- a/src/gensvm_update.c
+++ b/src/gensvm_update.c
@@ -38,6 +38,7 @@
  * GenModel::R to speed up the computation.
  *
  * @param[in] 	model 	GenModel structure with the current model
+ * @param[in] 	data 	GenData structure with the data (used for y)
  * @param[in] 	i 	index of the instance for which to calculate omega
  * @returns 		the value of omega for instance i
  *
@@ -70,6 +71,7 @@ double gensvm_calculate_omega(struct GenModel *model, struct GenData *data,
  * check if strictly less than 2 are nonzero. See also the @ref update_math.
  *
  * @param[in] 	model 	GenModel structure with the current model
+ * @param[in] 	data 	GenData structure with the data (used for y)
  * @param[in] 	i 	index of the instance for which to check
  * @returns 		whether or not we can do simple majorization
  *
@@ -206,6 +208,7 @@ void gensvm_calculate_ab_simple(struct GenModel *model, long i, long j,
  * returned.
  *
  * @param[in] 		model 	GenModel structure with the current model
+ * @param[in] 		data 	GenData structure with the data
  * @param[in] 		i 	index of the instance to update
  * @param[out] 		beta	beta vector of linear coefficients (assumed to
  * 				be allocated elsewhere, initialized here)
diff --git a/tests/src/test_gensvm_update.c b/tests/src/test_gensvm_update.c
index 81dcb37..e0314e5 100644
--- a/tests/src/test_gensvm_update.c
+++ b/tests/src/test_gensvm_update.c
@@ -1,8 +1,8 @@
 /**
- * @file test_gensvm_optimize.c
+ * @file test_gensvm_update.c
  * @author Gertjan van den Burg
  * @date September, 2016
- * @brief Unit tests for gensvm_optimize.c functions
+ * @brief Unit tests for gensvm_update.c functions
  */
 
 #include "minunit.h"