Getting doxygen to run (#371)

Authors:
  - Corey J. Nolet (https://github.com/cjnolet)

Approvers:
  - Dante Gama Dessavre (https://github.com/dantegd)

URL: #371

cpp/Doxyfile.in

@@ -771,10 +771,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@/comms \
-                         @CMAKE_CURRENT_SOURCE_DIR@/include \
-                         @CMAKE_CURRENT_SOURCE_DIR@/src \
-                         @CMAKE_CURRENT_SOURCE_DIR@/src_prims
+INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@/include \
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -799,12 +796,7 @@ INPUT_ENCODING         = UTF-8
 # *.m, *.markdown, *.md, *.mm, *.dox, *.py, *.pyw, *.f90, *.f, *.for, *.tcl,
 # *.vhd, *.vhdl, *.ucf, *.qsf, *.as and *.js.
 
-FILE_PATTERNS          = *.cpp \
-                         *.h \
-                         *.hpp \
-                         *.hxx \
-                         *.cu \
-                         *.cuh
+FILE_PATTERNS          = *.hpp
 
 # The RECURSIVE tag can be used to specify whether or not subdirectories should
 # be searched for input files as well.
@@ -835,8 +827,8 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       = columnWiseSort.h \
-                         smoblocksolve.h
+EXCLUDE_PATTERNS       = **/detail/** \
+                         **/spectral/**
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the
@@ -873,7 +865,7 @@ EXAMPLE_RECURSIVE      = NO
 # that contain images that are to be included in the documentation (see the
 # \image command).
 
-IMAGE_PATH             = @CMAKE_CURRENT_SOURCE_DIR@/doxygen/images
+IMAGE_PATH             =
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program

cpp/cmake/doxygen.cmake

@@ -22,7 +22,7 @@ function(add_doxygen_target)
     set(multiValueArgs "")
     cmake_parse_arguments(dox "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
     configure_file(${dox_IN_DOXYFILE} ${dox_OUT_DOXYFILE} @ONLY)
-    add_custom_target(doc
+    add_custom_target(docs_raft
       ${DOXYGEN_EXECUTABLE} ${dox_OUT_DOXYFILE}
       WORKING_DIRECTORY ${dox_CWD}
       VERBATIM

cpp/include/raft/comms/comms.hpp

@@ -339,9 +339,9 @@ class comms_t {
 
   /**
    * Gathers data from all ranks and delivers to combined data to all ranks
-   * @param value_t datatype of underlying buffers
-   * @param sendbuff buffer containing data to send
-   * @param recvbuff buffer containing data to receive
+   * @tparam value_t datatype of underlying buffers
+   * @param sendbuf buffer containing data to send
+   * @param recvbuf buffer containing data to receive
    * @param recvcounts pointer to an array (of length num_ranks size) containing the number of
    *                   elements that are to be received from each rank
    * @param displs pointer to an array (of length num_ranks size) to specify the displacement
@@ -376,9 +376,9 @@ class comms_t {
 
   /**
    * Gathers data from all ranks and delivers to combined data to all ranks
-   * @param value_t datatype of underlying buffers
-   * @param sendbuff buffer containing data to send
-   * @param recvbuff buffer containing data to receive
+   * @tparam value_t datatype of underlying buffers
+   * @param sendbuf buffer containing data to send
+   * @param recvbuf buffer containing data to receive
    * @param sendcount number of elements in send buffer
    * @param recvcounts pointer to an array (of length num_ranks size) containing the number of
    *                   elements that are to be received from each rank
@@ -401,6 +401,7 @@ class comms_t {
    * @tparam value_t datatype of underlying buffers
    * @param sendbuff buffer containing data to send (size recvcount * num_ranks)
    * @param recvbuff buffer containing received data
+   * @param recvcount number of items to receive
    * @param op reduction operation to perform
    * @param stream CUDA stream to synchronize operation
    */
@@ -476,7 +477,7 @@ class comms_t {
    * @param sendbuf pointer to array of data to send
    * @param sendsizes numbers of elements to send
    * @param sendoffsets offsets in a number of elements from sendbuf
-   * @param dest destination ranks
+   * @param dests destination ranks
    * @param recvbuf pointer to (initialized) array that will hold received data
    * @param recvsizes numbers of elements to recv
    * @param recvoffsets offsets in a number of elements from recvbuf

cpp/include/raft/comms/std_comms.hpp

@@ -56,11 +56,13 @@ class std_comms : public comms_iface {
 
   /**
    * @brief Constructor for collective + point-to-point operation.
-   * @param comm initialized nccl comm
+   * @param nccl_comm initialized nccl comm
    * @param ucp_worker initialized ucp_worker instance
    * @param eps shared pointer to array of ucp endpoints
-   * @param size size of the cluster
+   * @param num_ranks number of ranks in the cluster
    * @param rank rank of the current worker
+   * @param stream cuda stream for synchronizing and ordering collective operations
+   * @param subcomms_ucp use ucp for subcommunicators
    */
   std_comms(ncclComm_t nccl_comm, ucp_worker_h ucp_worker,
             std::shared_ptr<ucp_ep_h *> eps, int num_ranks, int rank,
@@ -79,9 +81,10 @@ class std_comms : public comms_iface {
 
   /**
    * @brief constructor for collective-only operation
-   * @param comm initilized nccl communicator
-   * @param size size of the cluster
+   * @param nccl_comm initilized nccl communicator
+   * @param num_ranks size of the cluster
    * @param rank rank of the current worker
+   * @param stream stream for ordering collective operations
    */
   std_comms(const ncclComm_t nccl_comm, int num_ranks, int rank,
             cudaStream_t stream)

cpp/include/raft/comms/test.hpp

@@ -31,10 +31,11 @@ namespace raft {
 namespace comms {
 
 /**
- * A simple sanity check that NCCL is able to perform a collective operation
+ * @brief A simple sanity check that NCCL is able to perform a collective operation
  *
- * @param the raft handle to use. This is expected to already have an
+ * @param[in] handle the raft handle to use. This is expected to already have an
  *        initialized comms instance.
+*  @param[in] root the root rank id
  */
 bool test_collective_allreduce(const handle_t &handle, int root) {
   comms_t const &communicator = handle.get_comms();
@@ -62,10 +63,11 @@ bool test_collective_allreduce(const handle_t &handle, int root) {
 }
 
 /**
- * A simple sanity check that NCCL is able to perform a collective operation
+ * @brief A simple sanity check that NCCL is able to perform a collective operation
  *
- * @param the raft handle to use. This is expected to already have an
+ * @param[in] handle the raft handle to use. This is expected to already have an
  *        initialized comms instance.
+*  @param[in] root the root rank id
  */
 bool test_collective_broadcast(const handle_t &handle, int root) {
   comms_t const &communicator = handle.get_comms();
@@ -94,6 +96,13 @@ bool test_collective_broadcast(const handle_t &handle, int root) {
   return temp_h == root;
 }
 
+/**
+ * @brief A simple sanity check that NCCL is able to perform a collective reduce
+ *
+ * @param[in] handle the raft handle to use. This is expected to already have an
+ *        initialized comms instance.
+*  @param[in] root the root rank id
+ */
 bool test_collective_reduce(const handle_t &handle, int root) {
   comms_t const &communicator = handle.get_comms();
 
@@ -123,6 +132,13 @@ bool test_collective_reduce(const handle_t &handle, int root) {
     return true;
 }
 
+/**
+ * @brief A simple sanity check that NCCL is able to perform a collective allgather
+ *
+ * @param[in] handle the raft handle to use. This is expected to already have an
+ *        initialized comms instance.
+*  @param[in] root the root rank id
+ */
 bool test_collective_allgather(const handle_t &handle, int root) {
   comms_t const &communicator = handle.get_comms();
 
@@ -155,6 +171,13 @@ bool test_collective_allgather(const handle_t &handle, int root) {
   return true;
 }
 
+/**
+ * @brief A simple sanity check that NCCL is able to perform a collective gather
+ *
+ * @param[in] handle the raft handle to use. This is expected to already have an
+ *        initialized comms instance.
+*  @param[in] root the root rank id
+ */
 bool test_collective_gather(const handle_t &handle, int root) {
   comms_t const &communicator = handle.get_comms();
 
@@ -186,6 +209,13 @@ bool test_collective_gather(const handle_t &handle, int root) {
   return true;
 }
 
+/**
+ * @brief A simple sanity check that NCCL is able to perform a collective gatherv
+ *
+ * @param[in] handle the raft handle to use. This is expected to already have an
+ *        initialized comms instance.
+*  @param[in] root the root rank id
+ */
 bool test_collective_gatherv(const handle_t &handle, int root) {
   comms_t const &communicator = handle.get_comms();
 
@@ -236,6 +266,13 @@ bool test_collective_gatherv(const handle_t &handle, int root) {
   return true;
 }
 
+/**
+ * @brief A simple sanity check that NCCL is able to perform a collective reducescatter
+ *
+ * @param[in] handle the raft handle to use. This is expected to already have an
+ *        initialized comms instance.
+*  @param[in] root the root rank id
+ */
 bool test_collective_reducescatter(const handle_t &handle, int root) {
   comms_t const &communicator = handle.get_comms();
 
@@ -268,9 +305,9 @@ bool test_collective_reducescatter(const handle_t &handle, int root) {
 /**
  * A simple sanity check that UCX is able to send messages between all ranks
  *
- * @param the raft handle to use. This is expected to already have an
+ * @param[in] h the raft handle to use. This is expected to already have an
  *        initialized comms instance.
- * @param number of iterations of all-to-all messaging to perform
+ * @param[in] numTrials number of iterations of all-to-all messaging to perform
  */
 bool test_pointToPoint_simple_send_recv(const handle_t &h, int numTrials) {
   comms_t const &communicator = h.get_comms();
@@ -333,9 +370,9 @@ bool test_pointToPoint_simple_send_recv(const handle_t &h, int numTrials) {
 /**
  * A simple sanity check that device is able to send OR receive.
  *
- * @param the raft handle to use. This is expected to already have an
+ * @param h the raft handle to use. This is expected to already have an
  *        initialized comms instance.
- * @param number of iterations of send or receive messaging to perform
+ * @param numTrials number of iterations of send or receive messaging to perform
  */
 bool test_pointToPoint_device_send_or_recv(const handle_t &h, int numTrials) {
   comms_t const &communicator = h.get_comms();
@@ -378,9 +415,9 @@ bool test_pointToPoint_device_send_or_recv(const handle_t &h, int numTrials) {
 /**
  * A simple sanity check that device is able to send and receive at the same time.
  *
- * @param the raft handle to use. This is expected to already have an
+ * @param h the raft handle to use. This is expected to already have an
  *        initialized comms instance.
- * @param number of iterations of send or receive messaging to perform
+ * @param numTrials number of iterations of send or receive messaging to perform
  */
 bool test_pointToPoint_device_sendrecv(const handle_t &h, int numTrials) {
   comms_t const &communicator = h.get_comms();
@@ -425,9 +462,9 @@ bool test_pointToPoint_device_sendrecv(const handle_t &h, int numTrials) {
 /**
  * A simple sanity check that device is able to perform multiple concurrent sends and receives.
  *
- * @param the raft handle to use. This is expected to already have an
+ * @param h the raft handle to use. This is expected to already have an
  *        initialized comms instance.
- * @param number of iterations of send or receive messaging to perform
+ * @param numTrials number of iterations of send or receive messaging to perform
  */
 bool test_pointToPoint_device_multicast_sendrecv(const handle_t &h,
                                                  int numTrials) {
@@ -483,7 +520,7 @@ bool test_pointToPoint_device_multicast_sendrecv(const handle_t &h,
 /**
  * A simple test that the comms can be split into 2 separate subcommunicators
  *
- * @param the raft handle to use. This is expected to already have an
+ * @param h the raft handle to use. This is expected to already have an
  *        initialized comms instance.
  * @param n_colors number of different colors to test
  */

cpp/include/raft/distance/distance.hpp

@@ -43,6 +43,7 @@ namespace distance {
 * @param fin_op the final gemm epilogue lambda
 * @param stream cuda stream
 * @param isRowMajor whether the matrices are row-major or col-major
+* @param metric_arg metric argument (used for Minkowski distance)
 *
 * @note fin_op: This is a device lambda which is supposed to operate upon the
 * input which is AccType and returns the output in OutType. It's signature is
@@ -78,6 +79,7 @@ void distance(const InType *x, const InType *y, OutType *dist, Index_ m,
 * @param worksize number of bytes of the workspace
 * @param stream cuda stream
 * @param isRowMajor whether the matrices are row-major or col-major
+* @param metric_arg metric argument (used for Minkowski distance)
 *
 * @note if workspace is passed as nullptr, this will return in
 *  worksize, the number of bytes of workspace required
@@ -129,10 +131,9 @@ size_t getWorkspaceSize(const InType *x, const InType *y, Index_ m, Index_ n,
 * @param m number of points in x
 * @param n number of points in y
 * @param k dimensionality
-* @param workspace temporary workspace needed for computations
-* @param worksize number of bytes of the workspace
 * @param stream cuda stream
 * @param isRowMajor whether the matrices are row-major or col-major
+* @param metric_arg metric argument (used for Minkowski distance)
 *
 * @note if workspace is passed as nullptr, this will return in
 *  worksize, the number of bytes of workspace required

cpp/include/raft/distance/fused_l2_nn.hpp

@@ -76,6 +76,7 @@ void initialize(const raft::handle_t& handle, OutT* min, IdxT m, DataT maxVal,
  * @param[in]  k             gemm k
  * @param[in]  workspace     temp workspace. Size = sizeof(int)*m. (on device)
  * @param[in]  redOp         reduction operator in the epilogue
+ * @param[in] pairRedOp reduction operation on key value pairs
  * @param[in]  sqrt          Whether the output `minDist` should contain L2-sqrt
  * @param[in]  initOutBuffer whether to initialize the output buffer before the
  *                           main kernel launch

cpp/include/raft/handle.hpp

@@ -73,7 +73,8 @@ class handle_t {
    * @brief Construct a light handle copy from another 
    * user stream, cuda handles, comms and worker pool are not copied
    * The user_stream of the returned handle is set to the specified stream 
-   * of the other handle worker pool 
+   * of the other handle worker pool
+   * @param[in] other other handle for which to use streams
    * @param[in] stream_id stream id in `other` worker streams 
    * to be set as user stream in the constructed handle
    * @param[in] n_streams number worker streams to be created

cpp/include/raft/mr/buffer_base.hpp

@@ -98,7 +98,6 @@ class buffer_base {
    * removes the old one.
    *
    * @param[in] new_capacity new capacity (in number of elements)
-   * @param[in] stream       cuda stream where allocation operations are queued
    * @{
    */
   void reserve(size_type new_capacity) {
@@ -127,7 +126,6 @@ class buffer_base {
    * @brief Resize the underlying buffer (uses `reserve` method internally)
    *
    * @param[in] new_size new buffer size
-   * @param[in] stream   cuda stream where the work will be queued
    * @{
    */
   void resize(const size_type new_size) {
@@ -145,8 +143,6 @@ class buffer_base {
    * @brief Deletes the underlying buffer
    *
    * If this method is not explicitly called, it will be during the destructor
-   *
-   * @param[in] stream   cuda stream where the work will be queued
    * @{
    */
   void release() {

cpp/include/raft/sparse/distance/distance.hpp

@@ -71,6 +71,7 @@ static const std::unordered_set<raft::distance::DistanceType> supportedDistance{
  * @param[out] out dense output array (size A.nrows * B.nrows)
  * @param[in] input_config input argument configuration
  * @param[in] metric distance metric to use
+* @param[in] metric_arg metric argument (used for Minkowski distance)
  */
 template <typename value_idx = int, typename value_t = float>
 void pairwiseDistance(value_t *out,

cpp/include/raft/spatial/knn/ball_cover.hpp

@@ -125,10 +125,7 @@ void rbc_all_knn_query(const raft::handle_t &handle,
  *               based on how many relevant balls are ignored. Note that
  *               many datasets can still have great recall even by only
  *               looking in the closest landmark.
- * @param k
- * @param inds
- * @param dists
- * @param n_samples
+ * @param[in] n_query_pts number of query points
  */
 template <typename value_idx = std::int64_t, typename value_t,
           typename value_int = std::uint32_t>

cpp/include/raft/spatial/knn/knn.hpp

@@ -108,8 +108,8 @@ inline void select_k(value_t *inK, value_idx *inV, size_t n_rows, size_t n_cols,
  * 			   default
  * @param[in] metric_arg the value of `p` for Minkowski (l-p) distances. This
  * 					 is ignored if the metric_type is not Minkowski.
- * @param[in] expanded should lp-based distances be returned in their expanded
- * 					 form (e.g., without raising to the 1/p power).
+ * @param[in] translations starting offsets for partitions. should be the same size
+ *            as input vector.
  */
 inline void brute_force_knn(
   raft::handle_t const &handle, std::vector<float *> &input,