API Documentation (#44)

Building out initial API documentation for all the supported languages and algorithms.

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

Approvers:
  - Ben Frederickson (https://github.com/benfred)

URL: #44

build.sh

@@ -403,7 +403,7 @@ fi
 # Initiate build for c++ examples (if needed)
 
 if hasArg examples; then
-    pushd ${REPODIR}/cpp/examples
+    pushd ${REPODIR}/examples/cpp
     ./build.sh
     popd
 fi

cpp/doxygen/Doxyfile

@@ -864,6 +864,7 @@ INPUT_ENCODING         = UTF-8
 # *.vhdl, *.ucf, *.qsf and *.ice.
 
 FILE_PATTERNS          = *.hpp \
+                         *.h \
                          *.cuh
 
 # The RECURSIVE tag can be used to specify whether or not subdirectories should

cpp/include/cuvs/core/c_api.h

@@ -16,30 +16,46 @@
 
 #pragma once
 
+#include <cuda_runtime.h>
 #include <stdint.h>
 
-#include <cuda_runtime.h>
+#ifdef __cplusplus
+extern "C" {
+#endif
 
 /**
- * @defgroup c_api C API Core Types and Functions
+ * @defgroup error_c cuVS Error Messages
  * @{
  */
+/**
+ * @brief An enum denoting return values for function calls
+ *
+ */
+typedef enum { CUVS_ERROR, CUVS_SUCCESS } cuvsError_t;
 
-#ifdef __cplusplus
-extern "C" {
-#endif
+/** @brief Returns a string describing the last seen error on this thread, or
+ *         NULL if the last function succeeded.
+ */
+const char* cuvsGetLastErrorText();
 
 /**
- * @brief An opaque C handle for C++ type `raft::resources`
- *
+ * @brief Sets a string describing an error seen on the thread. Passing NULL
+ *        clears any previously seen error message.
  */
-typedef uintptr_t cuvsResources_t;
+void cuvsSetLastErrorText(const char* error);
+
+/** @} */
 
 /**
- * @brief An enum denoting return values for function calls
+ * @defgroup resources_c cuVS Resources Handle
+ * @{
+ */
+
+/**
+ * @brief An opaque C handle for C++ type `raft::resources`
  *
  */
-typedef enum { CUVS_ERROR, CUVS_SUCCESS } cuvsError_t;
+typedef uintptr_t cuvsResources_t;
 
 /**
  * @brief Create an Initialized opaque C handle for C++ type `raft::resources`
@@ -67,18 +83,8 @@ cuvsError_t cuvsResourcesDestroy(cuvsResources_t res);
  */
 cuvsError_t cuvsStreamSet(cuvsResources_t res, cudaStream_t stream);
 
-/** @brief Returns a string describing the last seen error on this thread, or
- *         NULL if the last function succeeded.
- */
-const char* cuvsGetLastErrorText();
+/** @} */
 
-/**
- * @brief Sets a string describing an error seen on the thread. Passing NULL
- *        clears any previously seen error message.
- */
-void cuvsSetLastErrorText(const char* error);
 #ifdef __cplusplus
 }
 #endif
-
-/** @} */

cpp/include/cuvs/neighbors/cagra.h

@@ -20,15 +20,15 @@
 #include <dlpack/dlpack.h>
 #include <stdint.h>
 
-/**
- * @defgroup cagra_c C API for CUDA ANN Graph-based nearest neighbor search
- * @{
- */
-
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/**
+ * @defgroup cagra_c_index_params C API for CUDA ANN Graph-based nearest neighbor search
+ * @{
+ */
+
 /**
  * @brief Enum to denote which ANN algorithm is used to build CAGRA graph
  *
@@ -71,7 +71,16 @@ cuvsError_t cuvsCagraIndexParamsCreate(cuvsCagraIndexParams_t* params);
  * @param[in] params
  * @return cuvsError_t
  */
-cuvsError_t cuvsCagraIndexParamsDestroy(cuvsCagraIndexParams_t index);
+cuvsError_t cuvsCagraIndexParamsDestroy(cuvsCagraIndexParams_t params);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup cagra_c_search_params C API for CUDA ANN Graph-based nearest neighbor search
+ * @{
+ */
 
 /**
  * @brief Enum to denote algorithm used to search CAGRA Index
@@ -158,6 +167,15 @@ cuvsError_t cuvsCagraSearchParamsCreate(cuvsCagraSearchParams_t* params);
  */
 cuvsError_t cuvsCagraSearchParamsDestroy(cuvsCagraSearchParams_t params);
 
+/**
+ * @}
+ */
+
+/**
+ * @defgroup cagra_c_index C API for CUDA ANN Graph-based nearest neighbor search
+ * @{
+ */
+
 /**
  * @brief Struct to hold address of cuvs::neighbors::cagra::index and its active trained dtype
  *
@@ -185,6 +203,15 @@ cuvsError_t cuvsCagraIndexCreate(cuvsCagraIndex_t* index);
  */
 cuvsError_t cuvsCagraIndexDestroy(cuvsCagraIndex_t index);
 
+/**
+ * @}
+ */
+
+/**
+ * @defgroup cagra_c_index_build C API for CUDA ANN Graph-based nearest neighbor search
+ * @{
+ */
+
 /**
  * @brief Build a CAGRA index with a `DLManagedTensor` which has underlying
  *        `DLDeviceType` equal to `kDLCUDA`, `kDLCUDAHost`, `kDLCUDAManaged`,
@@ -232,6 +259,14 @@ cuvsError_t cuvsCagraBuild(cuvsResources_t res,
                            DLManagedTensor* dataset,
                            cuvsCagraIndex_t index);
 
+/**
+ * @}
+ */
+
+/**
+ * @defgroup cagra_c_index_search C API for CUDA ANN Graph-based nearest neighbor search
+ * @{
+ */
 /**
  * @brief Search a CAGRA index with a `DLManagedTensor` which has underlying
  *        `DLDeviceType` equal to `kDLCUDA`, `kDLCUDAHost`, `kDLCUDAManaged`.
@@ -281,10 +316,10 @@ cuvsError_t cuvsCagraSearch(cuvsResources_t res,
                             DLManagedTensor* neighbors,
                             DLManagedTensor* distances);
 
-#ifdef __cplusplus
-}
-#endif
-
 /**
  * @}
  */
+
+#ifdef __cplusplus
+}
+#endif