CMake: Enable Doxygen

CMakeLists.txt

@@ -6,7 +6,7 @@
 ######################################################################
 
 # Required version
-cmake_minimum_required(VERSION 2.8.12)
+cmake_minimum_required(VERSION 3.9)
 
 # Project Version	
 project(SuperLU C)
@@ -24,6 +24,7 @@ set(PROJECT_VERSION ${VERSION_MAJOR}.${VERSION_MINOR}.${VERSION_BugFix})
 set(USE_XSDK_DEFAULTS TRUE)
 include(CTest)
 include(GNUInstallDirs)
+include(FeatureSummary)
 
 ######################################################################
 
@@ -76,7 +77,7 @@ endif()
 option(enable_internal_blaslib  "Build the CBLAS library" ${enable_blaslib_DEFAULT})
 option(enable_matlabmex "Build the Matlab mex library" OFF)
 option(enable_tests     "Build tests" ON)
-option(enable_doc       "Build doxygen documentation" OFF)
+option(enable_doc       "Add target 'doc' to build Doxygen documentation" OFF)
 option(enable_single    "Enable single precision library" ON)
 option(enable_double    "Enable double precision library" ON)
 option(enable_complex   "Enable complex precision library" ON)
@@ -215,8 +216,7 @@ if (XSDK_ENABLE_Fortran)
 endif()
 
 if(enable_doc)
-  message(FATAL_ERROR "Documentation build requested but not implemented.")
-  #implement doxygen
+  add_subdirectory(DOC)
 endif()
 
 # Generate various configure files with proper definitions

DOC/CMakeLists.txt

@@ -0,0 +1,16 @@
+# build HTML documentation using Doxygen
+
+find_package(Doxygen)
+set_package_properties("Doxygen" PROPERTIES
+  DESCRIPTION "Documentation generator"
+  URL "www.doxygen.org"
+  PURPOSE "Generate HTML documentation from C sources")
+
+# set Doxygen options
+set(DOXYGEN_WARN_LOGFILE "doxygen.log")
+
+doxygen_add_docs(doc
+                 "${PROJECT_SOURCE_DIR}/EXAMPLE"
+                 "${PROJECT_SOURCE_DIR}/FORTRAN"
+                 "${PROJECT_SOURCE_DIR}/SRC"
+                 COMMENT "Generate HTML documentation with Doxygen")

EXAMPLE/sp_ienv.c

@@ -8,7 +8,7 @@ All rights reserved.
 The source code is distributed under BSD license, see the file License.txt
 at the top-level directory.
 */
-/*! @file sp_ienv.c
+/*! @file EXAMPLE/sp_ienv.c
  * \brief Chooses machine-dependent parameters for the local environment.
  *
  * <pre>

FORTRAN/c_fortran_cgssv.c

@@ -22,16 +22,7 @@ typedef struct {
     int *perm_r;
 } factors_t;
 
-void
-c_fortran_cgssv_(int *iopt, int *n, int_t *nnz, int *nrhs, 
-                 complex *values, int_t *rowind, int_t *colptr,
-                 complex *b, int *ldb,
-		 fptr *f_factors, /* a handle containing the address
-				     pointing to the factored matrices */
-		 int_t *info)
-
-{
-/* 
+/*!
  * This routine can be called from Fortran.
  *
  * iopt (input) int
@@ -44,9 +35,15 @@ c_fortran_cgssv_(int *iopt, int *n, int_t *nnz, int *nrhs,
  *      If iopt == 1, it is an output and contains the pointer pointing to
  *                    the structure of the factored matrices.
  *      Otherwise, it it an input.
- *
  */
-
+void
+c_fortran_cgssv_(int *iopt, int *n, int_t *nnz, int *nrhs,
+                 complex *values, int_t *rowind, int_t *colptr,
+                 complex *b, int *ldb,
+                 fptr *f_factors, /* a handle containing the address
+                                     pointing to the factored matrices */
+                 int_t *info)
+{
     SuperMatrix A, AC, B;
     SuperMatrix *L, *U;
     int *perm_r; /* row permutations from partial pivoting */

FORTRAN/c_fortran_dgssv.c

@@ -22,16 +22,7 @@ typedef struct {
     int *perm_r;
 } factors_t;
 
-void
-c_fortran_dgssv_(int *iopt, int *n, int_t *nnz, int *nrhs, 
-                 double *values, int_t *rowind, int_t *colptr,
-                 double *b, int *ldb,
-		 fptr *f_factors, /* a handle containing the address
-				     pointing to the factored matrices */
-		 int_t *info)
-
-{
-/* 
+/*!
  * This routine can be called from Fortran.
  *
  * iopt (input) int
@@ -44,9 +35,15 @@ c_fortran_dgssv_(int *iopt, int *n, int_t *nnz, int *nrhs,
  *      If iopt == 1, it is an output and contains the pointer pointing to
  *                    the structure of the factored matrices.
  *      Otherwise, it it an input.
- *
  */
-
+void
+c_fortran_dgssv_(int *iopt, int *n, int_t *nnz, int *nrhs,
+                 double *values, int_t *rowind, int_t *colptr,
+                 double *b, int *ldb,
+                 fptr *f_factors, /* a handle containing the address
+                                     pointing to the factored matrices */
+                 int_t *info)
+{
     SuperMatrix A, AC, B;
     SuperMatrix *L, *U;
     int *perm_r; /* row permutations from partial pivoting */

FORTRAN/c_fortran_sgssv.c

@@ -22,16 +22,7 @@ typedef struct {
     int *perm_r;
 } factors_t;
 
-void
-c_fortran_sgssv_(int *iopt, int *n, int_t *nnz, int *nrhs, 
-                 float *values, int_t *rowind, int_t *colptr,
-                 float *b, int *ldb,
-		 fptr *f_factors, /* a handle containing the address
-				     pointing to the factored matrices */
-		 int_t *info)
-
-{
-/* 
+/*!
  * This routine can be called from Fortran.
  *
  * iopt (input) int
@@ -44,9 +35,15 @@ c_fortran_sgssv_(int *iopt, int *n, int_t *nnz, int *nrhs,
  *      If iopt == 1, it is an output and contains the pointer pointing to
  *                    the structure of the factored matrices.
  *      Otherwise, it it an input.
- *
  */
-
+void
+c_fortran_sgssv_(int *iopt, int *n, int_t *nnz, int *nrhs,
+                 float *values, int_t *rowind, int_t *colptr,
+                 float *b, int *ldb,
+                 fptr *f_factors, /* a handle containing the address
+                                     pointing to the factored matrices */
+                 int_t *info)
+{
     SuperMatrix A, AC, B;
     SuperMatrix *L, *U;
     int *perm_r; /* row permutations from partial pivoting */

FORTRAN/c_fortran_zgssv.c

@@ -22,16 +22,7 @@ typedef struct {
     int *perm_r;
 } factors_t;
 
-void
-c_fortran_zgssv_(int *iopt, int *n, int_t *nnz, int *nrhs, 
-                 doublecomplex *values, int_t *rowind, int_t *colptr,
-                 doublecomplex *b, int *ldb,
-		 fptr *f_factors, /* a handle containing the address
-				     pointing to the factored matrices */
-		 int_t *info)
-
-{
-/* 
+/*!
  * This routine can be called from Fortran.
  *
  * iopt (input) int
@@ -44,9 +35,15 @@ c_fortran_zgssv_(int *iopt, int *n, int_t *nnz, int *nrhs,
  *      If iopt == 1, it is an output and contains the pointer pointing to
  *                    the structure of the factored matrices.
  *      Otherwise, it it an input.
- *
  */
-
+void
+c_fortran_zgssv_(int *iopt, int *n, int_t *nnz, int *nrhs,
+                 doublecomplex *values, int_t *rowind, int_t *colptr,
+                 doublecomplex *b, int *ldb,
+                 fptr *f_factors, /* a handle containing the address
+                                     pointing to the factored matrices */
+                 int_t *info)
+{
     SuperMatrix A, AC, B;
     SuperMatrix *L, *U;
     int *perm_r; /* row permutations from partial pivoting */

SRC/ccolumn_bmod.c

@@ -43,7 +43,7 @@ at the top-level directory.
  * ========
  * Performs numeric block updates (sup-col) in topological order.
  * It features: col-col, 2cols-col, 3cols-col, and sup-col updates.
- * Special processing on the supernodal portion of L\U[*,j]
+ * Special processing on the supernodal portion of L\\U[*,j]
  * Return value:   0 - successful return
  *               > 0 - number of bytes allocated when run out of space
  * </pre>

SRC/cgsisx.c

@@ -21,7 +21,8 @@ at the top-level directory.
  */
 #include "slu_cdefs.h"
 
-/*! \brief
+/*!
+ * Computes approximate solutions using the ILU factorization from cgsitrf()
  *
  * <pre>
  * Purpose
@@ -373,7 +374,7 @@ at the top-level directory.
  * mem_usage (output) mem_usage_t*
  *	   Record the memory usage statistics, consisting of following fields:
  *	   - for_lu (float)
- *	     The amount of space used in bytes for L\U data structures.
+ *	     The amount of space used in bytes for L\\U data structures.
  *	   - total_needed (float)
  *	     The amount of space needed in bytes to perform factorization.
  *	   - expansions (int)

SRC/cgssvx.c

@@ -21,7 +21,9 @@ at the top-level directory.
  */
 #include "slu_cdefs.h"
 
-/*! \brief
+/*!
+ * Solves the system of linear equations using
+ * the LU factorization from cgstrf()
  *
  * <pre>
  * Purpose
@@ -324,7 +326,7 @@ at the top-level directory.
  * mem_usage (output) mem_usage_t*
  *         Record the memory usage statistics, consisting of following fields:
  *         - for_lu (float)
- *           The amount of space used in bytes for L\U data structures.
+ *           The amount of space used in bytes for L\\U data structures.
  *         - total_needed (float)
  *           The amount of space needed in bytes to perform factorization.
  *         - expansions (int)

SRC/cmemory.c

@@ -98,15 +98,14 @@ void cuser_free(int bytes, int which_end, GlobalLU_t *Glu)
 
 
 
-/*! \brief 
+/*!
+ * Calculate memory usage
  *
- * <pre>
- * mem_usage consists of the following fields:
- *    - for_lu (float)
- *      The amount of space used in bytes for the L\U data structures.
- *    - total_needed (float)
+ * \param mem_usage consists of the following fields:
+ *    - <tt>for_lu (float)</tt>
+ *      The amount of space used in bytes for the L\\U data structures.
+ *    - <tt>total_needed (float)</tt>
  *      The amount of space needed in bytes to perform factorization.
- * </pre>
  */
 int cQuerySpace(SuperMatrix *L, SuperMatrix *U, mem_usage_t *mem_usage)
 {
@@ -136,15 +135,14 @@ int cQuerySpace(SuperMatrix *L, SuperMatrix *U, mem_usage_t *mem_usage)
 } /* cQuerySpace */
 
 
-/*! \brief
+/*!
+ * Calculate memory usage
  *
- * <pre>
- * mem_usage consists of the following fields:
- *    - for_lu (float)
- *      The amount of space used in bytes for the L\U data structures.
- *    - total_needed (float)
+ * \param mem_usage consists of the following fields:
+ *    - <tt>for_lu (float)</tt>
+ *      The amount of space used in bytes for the L\\U data structures.
+ *    - <tt>total_needed (float)</tt>
  *      The amount of space needed in bytes to perform factorization.
- * </pre>
  */
 int ilu_cQuerySpace(SuperMatrix *L, SuperMatrix *U, mem_usage_t *mem_usage)
 {

SRC/cmyblas2.c

@@ -18,6 +18,7 @@ at the top-level directory.
  * and Lawrence Berkeley National Lab.
  * November 15, 1997
  * </pre>
+ * <pre>
  * Purpose:
  *     Level 2 BLAS operations: solves and matvec, written in C.
  * Note:

SRC/cpanel_bmod.c

@@ -46,7 +46,7 @@ at the top-level directory.
  *
  *    Performs numeric block updates (sup-panel) in topological order.
  *    It features: col-col, 2cols-col, 3cols-col, and sup-col updates.
- *    Special processing on the supernodal portion of L\U[*,j]
+ *    Special processing on the supernodal portion of L\\U[*,j]
  *
  *    Before entering this routine, the original nonzeros in the panel 
  *    were already copied into the spa[m,w].

SRC/creadrb.c

@@ -17,6 +17,7 @@ at the top-level directory.
  * Lawrence Berkeley National Laboratory.
  * June 30, 2009
  * </pre>
+ * <pre>
  *
  * Purpose
  * =======

SRC/dcolumn_bmod.c

@@ -43,7 +43,7 @@ at the top-level directory.
  * ========
  * Performs numeric block updates (sup-col) in topological order.
  * It features: col-col, 2cols-col, 3cols-col, and sup-col updates.
- * Special processing on the supernodal portion of L\U[*,j]
+ * Special processing on the supernodal portion of L\\U[*,j]
  * Return value:   0 - successful return
  *               > 0 - number of bytes allocated when run out of space
  * </pre>

SRC/dgsisx.c

@@ -373,7 +373,7 @@ at the top-level directory.
  * mem_usage (output) mem_usage_t*
  *	   Record the memory usage statistics, consisting of following fields:
  *	   - for_lu (float)
- *	     The amount of space used in bytes for L\U data structures.
+ *	     The amount of space used in bytes for L\\U data structures.
  *	   - total_needed (float)
  *	     The amount of space needed in bytes to perform factorization.
  *	   - expansions (int)

SRC/dgssvx.c

@@ -324,7 +324,7 @@ at the top-level directory.
  * mem_usage (output) mem_usage_t*
  *         Record the memory usage statistics, consisting of following fields:
  *         - for_lu (float)
- *           The amount of space used in bytes for L\U data structures.
+ *           The amount of space used in bytes for L\\U data structures.
  *         - total_needed (float)
  *           The amount of space needed in bytes to perform factorization.
  *         - expansions (int)