Fix C++ doxygen documentation (#426)

Make the doxygen docs buildable again. The changes:

1. A minimal set of changes required for `docs_raft` target to complete successfully
2. A `build.sh` section for building the docs target (as in cuml)
3. CI target to make sure new documentation errors do not slip in.

Authors:
  - Artem M. Chirkin (https://github.com/achirkin)

Approvers:
  - Corey J. Nolet (https://github.com/cjnolet)
  - AJ Schmidt (https://github.com/ajschmidt8)

URL: #426

build.sh

@@ -18,13 +18,14 @@ ARGS=$*
 # script, and that this script resides in the repo dir!
 REPODIR=$(cd $(dirname $0); pwd)
 
-VALIDARGS="clean cppraft pyraft -v -g --allgpuarch --nvtx --show_depr_warn -h --buildgtest --buildfaiss"
+VALIDARGS="clean cppraft pyraft cppdocs -v -g --allgpuarch --nvtx --show_depr_warn -h --buildgtest --buildfaiss"
 HELP="$0 [<target> ...] [<flag> ...]
  where <target> is:
    clean            - remove all existing build artifacts and configuration (start over)
    cppraft          - build the cuml C++ code only. Also builds the C-wrapper library
                       around the C++ code.
    pyraft             - build the cuml Python package
+   cppdocs            - build the C++ doxygen documentation
  and <flag> is:
    -v               - verbose build mode
    -g               - build for debug
@@ -130,6 +131,11 @@ if (( ${CLEAN} == 1 )); then
     cd ${REPODIR}
 fi
 
+if hasArg cppdocs; then
+    cd ${CPP_RAFT_BUILD_DIR}
+    cmake --build ${CPP_RAFT_BUILD_DIR} --target docs_raft
+fi
+
 ################################################################################
 # Configure for building all C++ targets
 if (( ${NUMARGS} == 0 )) || hasArg cppraft; then

ci/gpu/build.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
-# Copyright (c) 2020, NVIDIA CORPORATION.
+# Copyright (c) 2020-2021, NVIDIA CORPORATION.
 #########################################
 # cuML GPU build and test script for CI #
 #########################################
@@ -90,6 +90,9 @@ export LD_LIBRARY_PATH=$CONDA_PREFIX/lib:$LD_LIBRARY_PATH
 gpuci_logger "Build C++ and Python targets"
 "$WORKSPACE/build.sh" cppraft pyraft -v
 
+gpuci_logger "Building doxygen C++ docs"
+"$WORKSPACE/build.sh" cppdocs -v
+
 gpuci_logger "Resetting LD_LIBRARY_PATH"
 
 export LD_LIBRARY_PATH=$LD_LIBRARY_PATH_CACHED

cpp/include/raft/handle.hpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019-2020, NVIDIA CORPORATION.
+ * Copyright (c) 2019-2021, NVIDIA CORPORATION.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -58,7 +58,8 @@ class handle_t {
   /**
    * @brief Construct a handle with a stream view and stream pool
    *
-   * @param[in] stream the default stream (which has the default per-thread stream if unspecified)
+   * @param[in] stream_view the default stream (which has the default per-thread stream if
+   * unspecified)
    * @param[in] stream_pool the stream pool used (which has default of nullptr if unspecified)
    */
   handle_t(rmm::cuda_stream_view stream_view                  = rmm::cuda_stream_per_thread,
@@ -184,7 +185,7 @@ class handle_t {
   /**
    * @brief return stream from pool at index if size > 0, else main stream on handle
    *
-   * @param[in] stream_index the required index of the stream in the stream pool if available
+   * @param[in] stream_idx the required index of the stream in the stream pool if available
    */
   rmm::cuda_stream_view get_next_usable_stream(std::size_t stream_idx) const
   {

cpp/include/raft/matrix/math.hpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018-2020, NVIDIA CORPORATION.
+ * Copyright (c) 2018-2021, NVIDIA CORPORATION.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -308,6 +308,7 @@ void setValue(math_t* out, const math_t* in, math_t scalar, int len, cudaStream_
  * @brief ratio of every element over sum of input vector is calculated
  * @tparam math_t data-type upon which the math operation will be performed
  * @tparam IdxType Integer type used to for addressing
+ * @param handle
  * @param src: input matrix
  * @param dest: output matrix. The result is stored in the dest matrix
  * @param len: number elements of input matrix

cpp/include/raft/matrix/matrix.hpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018-2020, NVIDIA CORPORATION.
+ * Copyright (c) 2018-2021, NVIDIA CORPORATION.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -169,6 +169,7 @@ void rowReverse(m_t* inout, idx_t n_rows, idx_t n_cols, cudaStream_t stream)
  * @param n_cols: number of columns of input matrix
  * @param h_separator: horizontal separator character
  * @param v_separator: vertical separator character
+ * @param stream: cuda stream
  */
 template <typename m_t, typename idx_t = int>
 void print(const m_t* in,
@@ -275,9 +276,9 @@ void getDiagonalInverseMatrix(m_t* in, idx_t len, cudaStream_t stream)
 
 /**
  * @brief Get the L2/F-norm of a matrix/vector
+ * @param handle
  * @param in: input matrix/vector with totally size elements
  * @param size: size of the matrix/vector
- * @param cublasH cublas handle
  * @param stream: cuda stream
  */
 template <typename m_t, typename idx_t = int>

cpp/include/raft/random/rng.hpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018-2020, NVIDIA CORPORATION.
+ * Copyright (c) 2018-2021, NVIDIA CORPORATION.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -335,6 +335,7 @@ class Rng : public detail::RngImpl {
    * @tparam DataT data type
    * @tparam WeightsT weights type
    * @tparam IdxT index type
+   * @param handle
    * @param out output sampled array (of length 'sampledLen')
    * @param outIdx indices of the sampled array (of length 'sampledLen'). Pass
    * a nullptr if this is not required.

cpp/include/raft/sparse/op/filter.hpp

@@ -38,7 +38,6 @@ namespace op {
  * @param cur_cnnz array of counts per row
  * @param scalar: scalar to remove from arrays
  * @param n: number of rows in dense matrix
- * @param d_alloc device allocator for temporary buffers
  * @param stream: cuda stream to use
  */
 template <typename T>

cpp/include/raft/sparse/op/reduce.hpp

@@ -57,14 +57,14 @@ void compute_duplicates_mask(
  * the sorting of values.
  * @tparam value_idx
  * @tparam value_t
+ * @param[in] handle
  * @param[out] out output COO, the nnz will be computed allocate() will be called in this function.
  * @param[in] rows COO rows array, size nnz
  * @param[in] cols COO cols array, size nnz
  * @param[in] vals COO vals array, size nnz
  * @param[in] nnz number of nonzeros in COO input arrays
  * @param[in] m number of rows in COO input matrix
  * @param[in] n number of columns in COO input matrix
- * @param[in] stream cuda ops will be ordered wrt this stream
  */
 template <typename value_idx, typename value_t>
 void max_duplicates(const raft::handle_t& handle,

cpp/include/raft/sparse/op/slice.hpp

@@ -49,8 +49,8 @@ void csr_row_slice_indptr(value_idx start_row,
 
 /**
  * Slice rows from a CSR, populate column and data arrays
- * @tparam[in] value_idx : data type of CSR index arrays
- * @tparam[in] value_t : data type of CSR data array
+ * @tparam value_idx : data type of CSR index arrays
+ * @tparam value_t : data type of CSR data array
  * @param[in] start_offset : beginning column offset to slice
  * @param[in] stop_offset : ending column offset to slice
  * @param[in] indices : column indices array from input CSR
@@ -74,4 +74,4 @@ void csr_row_slice_populate(value_idx start_offset,
 
 };  // namespace op
 };  // end NAMESPACE sparse
-};  // end NAMESPACE raft
+};  // end NAMESPACE raft

cpp/include/raft/sparse/selection/connect_components.hpp

@@ -54,9 +54,11 @@ value_idx get_n_components(value_idx* colors, size_t n_rows, cudaStream_t stream
  * @param[out] out output edge list containing nearest cross-component
  *             edges.
  * @param[in] X original (row-major) dense matrix for which knn graph should be constructed.
- * @param[in] colors array containing component number for each row of X
+ * @param[in] orig_colors array containing component number for each row of X
  * @param[in] n_rows number of rows in X
  * @param[in] n_cols number of cols in X
+ * @param[in] reduction_op
+ * @param[in] metric
  */
 template <typename value_idx, typename value_t, typename red_op>
 void connect_components(
@@ -73,4 +75,4 @@ void connect_components(
 }
 
 };  // end namespace linkage
-};  // end namespace raft
+};  // end namespace raft

cpp/include/raft/sparse/selection/knn.hpp

@@ -30,8 +30,9 @@ namespace selection {
  * @param[in] idxIndptr csr indptr of the index matrix (size n_idx_rows + 1)
  * @param[in] idxIndices csr column indices array of the index matrix (size n_idx_nnz)
  * @param[in] idxData csr data array of the index matrix (size idxNNZ)
- * @param[in] idxNNA number of non-zeros for sparse index matrix
+ * @param[in] idxNNZ number of non-zeros for sparse index matrix
  * @param[in] n_idx_rows number of data samples in index matrix
+ * @param[in] n_idx_cols
  * @param[in] queryIndptr csr indptr of the query matrix (size n_query_rows + 1)
  * @param[in] queryIndices csr indices array of the query matrix (size queryNNZ)
  * @param[in] queryData csr data array of the query matrix (size queryNNZ)
@@ -41,7 +42,7 @@ namespace selection {
  * @param[out] output_indices dense matrix for output indices (size n_query_rows * k)
  * @param[out] output_dists dense matrix for output distances (size n_query_rows * k)
  * @param[in] k the number of neighbors to query
- * @param[in] handle.get_stream() CUDA handle.get_stream() to order operations with respect to
+ * @param[in] handle CUDA handle.get_stream() to order operations with respect to
  * @param[in] batch_size_index maximum number of rows to use from index matrix per batch
  * @param[in] batch_size_query maximum number of rows to use from query matrix per batch
  * @param[in] metric distance metric/measure to use

cpp/include/raft/sparse/selection/knn_graph.hpp

@@ -40,7 +40,6 @@ namespace selection {
  * @param[in] n number of observations (columns) in X
  * @param[in] metric distance metric to use when constructing neighborhoods
  * @param[out] out output edge list
- * @param[out] out output edge list
  * @param c
  */
 template <typename value_idx = int, typename value_t = float>