Fix doxygen warnings in utilities/ headers (#10974)

Fixes parts of #9373
added missing documentation to fix doxygen warnings in multiple files cpp/include/cudf/utilities/
fixes 167 warnings

Authors:
  - Karthikeyan (https://github.com/karthikeyann)

Approvers:
  - Ram (Ramakrishna Prabhu) (https://github.com/rgsl888prabhu)
  - David Wendt (https://github.com/davidwendt)

URL: #10974

cpp/include/cudf/utilities/bit.hpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019-2020, NVIDIA CORPORATION.
+ * Copyright (c) 2019-2022, NVIDIA CORPORATION.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -27,6 +27,7 @@
 
 namespace cudf {
 namespace detail {
+// @cond
 // Work around a bug in NVRTC that fails to compile assert() in constexpr
 // functions (fixed after CUDA 11.0)
 #if defined __GNUC__
@@ -40,7 +41,14 @@ namespace detail {
 #else
 #define constexpr_assert(CHECK) (LIKELY(CHECK) ? void(0) : [] { assert(!#CHECK); }())
 #endif
+// @endcond
 
+/**
+ * @brief Returns the number of bits the given type can hold.
+ *
+ * @tparam T The type to query
+ * @return `sizeof(T)` in bits
+ */
 template <typename T>
 constexpr CUDF_HOST_DEVICE inline std::size_t size_in_bits()
 {
@@ -57,6 +65,9 @@ constexpr CUDF_HOST_DEVICE inline std::size_t size_in_bits()
 
 /**
  * @brief Returns the index of the word containing the specified bit.
+ *
+ * @param bit_index The index of the bit to query
+ * @return The index of the word containing the specified bit
  */
 constexpr CUDF_HOST_DEVICE inline size_type word_index(size_type bit_index)
 {
@@ -65,6 +76,9 @@ constexpr CUDF_HOST_DEVICE inline size_type word_index(size_type bit_index)
 
 /**
  * @brief Returns the position within a word of the specified bit.
+ *
+ * @param bit_index The index of the bit to query
+ * @return The position within a word of the specified bit
  */
 constexpr CUDF_HOST_DEVICE inline size_type intra_word_index(size_type bit_index)
 {

cpp/include/cudf/utilities/error.hpp

@@ -35,38 +35,60 @@ namespace cudf {
  * CUDF_EXPECTS macro.
  */
 struct logic_error : public std::logic_error {
+  /**
+   * @brief Constructs a logic_error with the error message.
+   *
+   * @param message Message to be associated with the exception
+   */
   logic_error(char const* const message) : std::logic_error(message) {}
 
+  /**
+   * @brief Construct a new logic error object with error message
+   *
+   * @param message Message to be associated with the exception
+   */
   logic_error(std::string const& message) : std::logic_error(message) {}
 
   // TODO Add an error code member? This would be useful for translating an
   // exception to an error code in a pure-C API
 };
 /**
  * @brief Exception thrown when a CUDA error is encountered.
+ *
  */
 struct cuda_error : public std::runtime_error {
+  /**
+   * @brief Construct a new cuda error object with error message and code.
+   *
+   * @param message Error message
+   * @param error CUDA error code
+   */
   cuda_error(std::string const& message, cudaError_t const& error)
     : std::runtime_error(message), _cudaError(error)
   {
   }
 
  public:
+  /**
+   * @brief Returns the CUDA error code associated with the exception.
+   *
+   * @return CUDA error code
+   */
   cudaError_t error_code() const { return _cudaError; }
 
  protected:
-  cudaError_t _cudaError;
+  cudaError_t _cudaError;  //!< CUDA error code
 };
 
 struct fatal_cuda_error : public cuda_error {
-  using cuda_error::cuda_error;
+  using cuda_error::cuda_error;  // Inherit constructors
 };
 /** @} */
 
 }  // namespace cudf
 
-#define STRINGIFY_DETAIL(x) #x
-#define CUDF_STRINGIFY(x)   STRINGIFY_DETAIL(x)
+#define STRINGIFY_DETAIL(x) #x                   ///< Stringify a macro argument
+#define CUDF_STRINGIFY(x)   STRINGIFY_DETAIL(x)  ///< Stringify a macro argument
 
 /**
  * @addtogroup utility_error
@@ -111,7 +133,7 @@ struct fatal_cuda_error : public cuda_error {
 
 namespace cudf {
 namespace detail {
-
+// @cond
 inline void throw_cuda_error(cudaError_t error, const char* file, unsigned int line)
 {
   // Calls cudaGetLastError twice. It is nearly certain that a fatal error occurred if the second
@@ -129,6 +151,7 @@ inline void throw_cuda_error(cudaError_t error, const char* file, unsigned int l
     throw cuda_error{msg, error};
   }
 }
+// @endcond
 }  // namespace detail
 }  // namespace cudf