Fix Doxygen warnings in multiple headers files (#11003)

Fixes parts of #9373
added missing documentation to fix doxygen warnings in multiple headers
cudf_test/, nvtext/, cudf_kafka/, ipc.hpp

With this PR, there are _zero doxygen warnings_!  ☺️

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

Approvers:
  - Yunsong Wang (https://github.com/PointKernel)
  - Nghia Truong (https://github.com/ttnghia)
  - David Wendt (https://github.com/davidwendt)

URL: #11003

cpp/doxygen/Doxyfile

@@ -818,6 +818,12 @@ INPUT                  = main_page.md \
                          regex.md \
                          unicode.md \
                          ../include \
+                         ../include/cudf_test/column_wrapper.hpp \
+                         ../include/cudf_test/column_utilities.hpp \
+                          ../include/cudf_test/iterator_utilities.hpp \
+                          ../include/cudf_test/table_utilities.hpp \
+                          ../include/cudf_test/type_lists.hpp \
+                          ../include/cudf_test/type_list_utilities.hpp \
                          ../libcudf_kafka/include
 
 # This tag can be used to specify the character encoding of the source files
@@ -881,7 +887,7 @@ 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       = */nvtx/* */detail/*
+EXCLUDE_PATTERNS       = */nvtx/* */detail/* */cudf_test/*
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the

cpp/include/cudf/column/column_device_view.cuh

@@ -1232,6 +1232,7 @@ __device__ inline bitmask_type get_mask_offset_word(bitmask_type const* __restri
 
 /**
  * @brief value accessor of column without null bitmask
+ *
  * A unary functor returns scalar value at `id`.
  * `operator() (cudf::size_type id)` computes `element`
  * This functor is only allowed for non-nullable columns.
@@ -1249,6 +1250,7 @@ struct value_accessor {
 
   /**
    * @brief constructor
+   *
    * @param[in] _col column device view of cudf column
    */
   value_accessor(column_device_view const& _col) : col{_col}
@@ -1328,6 +1330,7 @@ struct optional_accessor {
 
 /**
  * @brief pair accessor of column with/without null bitmask
+ *
  * A unary functor returns pair with scalar value at `id` and boolean validity
  * `operator() (cudf::size_type id)` computes `element`  and
  * returns a `pair(element, validity)`
@@ -1350,6 +1353,7 @@ struct pair_accessor {
 
   /**
    * @brief constructor
+   *
    * @param[in] _col column device view of cudf column
    */
   pair_accessor(column_device_view const& _col) : col{_col}
@@ -1372,6 +1376,7 @@ struct pair_accessor {
 
 /**
  * @brief pair accessor of column with/without null bitmask
+ *
  * A unary functor returns pair with representative scalar value at `id` and boolean validity
  * `operator() (cudf::size_type id)` computes `element`  and
  * returns a `pair(element, validity)`
@@ -1396,6 +1401,7 @@ struct pair_rep_accessor {
 
   /**
    * @brief constructor
+   *
    * @param[in] _col column device view of cudf column
    */
   pair_rep_accessor(column_device_view const& _col) : col{_col}
@@ -1446,6 +1452,7 @@ struct mutable_value_accessor {
 
   /**
    * @brief Constructor
+   *
    * @param[in] _col mutable column device view of cudf column
    */
   mutable_value_accessor(mutable_column_device_view& _col) : col{_col}

cpp/include/cudf/copying.hpp

@@ -86,6 +86,7 @@ std::unique_ptr<table> gather(
 
 /**
  * @brief Reverses the rows within a table.
+ *
  * Creates a new table that is the reverse of @p source_table.
  * Example:
  * ```
@@ -103,6 +104,7 @@ std::unique_ptr<table> reverse(
 
 /**
  * @brief Reverses the elements of a column
+ *
  * Creates a new column that is the reverse of @p source_column.
  * Example:
  * ```
@@ -229,6 +231,7 @@ std::unique_ptr<column> empty_like(scalar const& input);
 
 /**
  * @brief Creates an uninitialized new column of the same size and type as the `input`.
+ *
  * Supports only fixed-width types.
  *
  * @param[in] input Immutable view of input column to emulate
@@ -244,6 +247,7 @@ std::unique_ptr<column> allocate_like(
 
 /**
  * @brief Creates an uninitialized new column of the specified size and same type as the `input`.
+ *
  * Supports only fixed-width types.
  *
  * @param[in] input Immutable view of input column to emulate

cpp/include/cudf/io/parquet.hpp

@@ -526,17 +526,23 @@ class parquet_writer_options {
   auto get_row_group_size_rows() const { return _row_group_size_rows; }
 
   /**
-   * @brief Returns the maximum uncompressed page size, in bytes. If set larger than the row group
-   * size, then this will return the row group size.
+   * @brief Returns the maximum uncompressed page size, in bytes.
+   *
+   * If set larger than the row group size, then this will return the row group size.
+   *
+   * @return Maximum uncompressed page size, in bytes
    */
   auto get_max_page_size_bytes() const
   {
     return std::min(_max_page_size_bytes, get_row_group_size_bytes());
   }
 
   /**
-   * @brief Returns maximum page size, in rows. If set larger than the row group size, then this
-   * will return the row group size.
+   * @brief Returns maximum page size, in rows.
+   *
+   * If set larger than the row group size, then this will return the row group size.
+   *
+   * @return Maximum page size, in rows
    */
   auto get_max_page_size_rows() const
   {
@@ -638,6 +644,8 @@ class parquet_writer_options {
 
   /**
    * @brief Sets the maximum uncompressed page size, in bytes.
+   *
+   * @param size_bytes Maximum uncompressed page size, in bytes to set
    */
   void set_max_page_size_bytes(size_t size_bytes)
   {
@@ -647,6 +655,8 @@ class parquet_writer_options {
 
   /**
    * @brief Sets the maximum page size, in rows.
+   *
+   * @param size_rows Maximum page size, in rows to set
    */
   void set_max_page_size_rows(size_type size_rows)
   {
@@ -788,9 +798,11 @@ class parquet_writer_options_builder {
   }
 
   /**
-   * @brief Sets the maximum uncompressed page size, in bytes. Serves as a hint to the writer,
-   * and can be exceeded under certain circumstances. Cannot be larger than the row group size in
-   * bytes, and will be adjusted to match if it is.
+   * @brief Sets the maximum uncompressed page size, in bytes.
+   *
+   * Serves as a hint to the writer, * and can be exceeded under certain circumstances.
+   * Cannot be larger than the row group size in bytes, and will be adjusted to
+   * match if it is.
    *
    * @param val maximum page size
    * @return this for chaining
@@ -979,17 +991,24 @@ class chunked_parquet_writer_options {
   auto get_row_group_size_rows() const { return _row_group_size_rows; }
 
   /**
-   * @brief Returns maximum uncompressed page size, in bytes. If set larger than the row group size,
-   * then this will return the row group size.
+   * @brief Returns maximum uncompressed page size, in bytes.
+   *
+   * If set larger than the row group size, then this will return the
+   * row group size.
+   *
+   * @return Maximum uncompressed page size, in bytes
    */
   auto get_max_page_size_bytes() const
   {
     return std::min(_max_page_size_bytes, get_row_group_size_bytes());
   }
 
   /**
-   * @brief Returns maximum page size, in rows. If set larger than the row group size, then this
-   * will return the row group size.
+   * @brief Returns maximum page size, in rows.
+   *
+   * If set larger than the row group size, then this will return the row group size.
+   *
+   * @return Maximum page size, in rows
    */
   auto get_max_page_size_rows() const
   {
@@ -1030,8 +1049,9 @@ class chunked_parquet_writer_options {
   void set_compression(compression_type compression) { _compression = compression; }
 
   /**
-   * @brief Sets timestamp writing preferences. INT96 timestamps will be written
-   * if `true` and TIMESTAMP_MICROS will be written if `false`.
+   * @brief Sets timestamp writing preferences.
+   *
+   * INT96 timestamps will be written if `true` and TIMESTAMP_MICROS will be written if `false`.
    *
    * @param req Boolean value to enable/disable writing of INT96 timestamps
    */
@@ -1065,6 +1085,8 @@ class chunked_parquet_writer_options {
 
   /**
    * @brief Sets the maximum uncompressed page size, in bytes.
+   *
+   * @param size_bytes Maximum uncompressed page size, in bytes to set
    */
   void set_max_page_size_bytes(size_t size_bytes)
   {
@@ -1074,6 +1096,8 @@ class chunked_parquet_writer_options {
 
   /**
    * @brief Sets the maximum page size, in rows.
+   *
+   * @param size_rows The maximum page size, in rows to set
    */
   void set_max_page_size_rows(size_type size_rows)
   {
@@ -1205,9 +1229,10 @@ class chunked_parquet_writer_options_builder {
   }
 
   /**
-   * @brief Sets the maximum uncompressed page size, in bytes. Serves as a hint to the writer,
-   * and can be exceeded under certain circumstances. Cannot be larger than the row group size in
-   * bytes, and will be adjusted to match if it is.
+   * @brief Sets the maximum uncompressed page size, in bytes.
+   *
+   * Serves as a hint to the writer, and can be exceeded under certain circumstances. Cannot be
+   * larger than the row group size in bytes, and will be adjusted to match if it is.
    *
    * @param val maximum page size
    * @return this for chaining

cpp/include/cudf/io/types.hpp

@@ -116,6 +116,7 @@ struct column_name_info {
 
 /**
  * @brief Table metadata for io readers/writers (primarily column names)
+ *
  * For nested types (structs, maps, unions), the ordering of names in the column_names vector
  * corresponds to a pre-order traversal of the column tree.
  * In the example below (2 top-level columns: struct column "col1" and string column "col2"),
@@ -519,6 +520,7 @@ class column_in_metadata {
 
   /**
    * @brief Gets the explicitly set nullability for this column.
+   *
    * @throws If nullability is not explicitly defined for this column.
    *         Check using `is_nullability_defined()` first.
    * @return Boolean indicating whether this column is nullable
@@ -549,6 +551,7 @@ class column_in_metadata {
 
   /**
    * @brief Get the decimal precision that was set for this column.
+   *
    * @throws If decimal precision was not set for this column.
    *         Check using `is_decimal_precision_set()` first.
    * @return The decimal precision that was set for this column
@@ -564,6 +567,7 @@ class column_in_metadata {
 
   /**
    * @brief Get the parquet field id that was set for this column.
+   *
    * @throws If parquet field id was not set for this column.
    *         Check using `is_parquet_field_id_set()` first.
    * @return The parquet field id that was set for this column

cpp/include/cudf/ipc.hpp

@@ -1,15 +1,55 @@
+/*
+ * Copyright (c) 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.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
 #include <arrow/api.h>
 #include <arrow/gpu/cuda_api.h>
 #include <arrow/io/memory.h>
 #include <arrow/ipc/api.h>
 
+/**
+ * @brief Reads Message objects from cuda buffer source
+ *
+ */
 class CudaMessageReader : arrow::ipc::MessageReader {
  public:
+  /**
+   * @brief Construct a new Cuda Message Reader object from a cuda buffer stream
+   *
+   * @param stream The cuda buffer reader stream
+   * @param schema The schema of the stream
+   */
   CudaMessageReader(arrow::cuda::CudaBufferReader* stream, arrow::io::BufferReader* schema);
 
+  /**
+   * @brief Open stream from source.
+   *
+   * @param stream The cuda buffer reader stream
+   * @param schema The schema of the stream
+   * @return arrow::ipc::MessageReader object
+   */
   static std::unique_ptr<arrow::ipc::MessageReader> Open(arrow::cuda::CudaBufferReader* stream,
                                                          arrow::io::BufferReader* schema);
 
+  /**
+   * @brief Read next Message from the stream.
+   *
+   * @return arrow::ipc::Message object
+   */
   arrow::Result<std::unique_ptr<arrow::ipc::Message>> ReadNextMessage() override;
 
  private:

cpp/include/cudf/quantiles.hpp

@@ -30,7 +30,7 @@ namespace cudf {
 
 /**
  * @brief Computes quantiles with interpolation.
-
+ *
  * Computes the specified quantiles by interpolating values between which they
  * lie, using the interpolation strategy specified in `interp`.
  *

cpp/include/cudf/scalar/scalar_device_view.cuh

@@ -36,6 +36,7 @@ class scalar_device_view_base {
 
   /**
    * @brief Returns the value type
+   *
    * @returns The value type
    */
   [[nodiscard]] __host__ __device__ data_type type() const noexcept { return _type; }

cpp/include/cudf_test/base_fixture.hpp

@@ -123,7 +123,7 @@ uint64_t random_generator_incrementing_seed();
 template <typename T = cudf::size_type, typename Engine = std::default_random_engine>
 class UniformRandomGenerator {
  public:
-  using uniform_distribution = uniform_distribution_t<T>;
+  using uniform_distribution = uniform_distribution_t<T>;  ///< The uniform distribution type for T.
 
   UniformRandomGenerator() : rng{std::mt19937_64{detail::random_generator_incrementing_seed()}()} {}
 
@@ -144,6 +144,13 @@ class UniformRandomGenerator {
   {
   }
 
+  /**
+   * @brief Construct a new Uniform Random Generator to generate uniformly random booleans
+   *
+   * @param lower ignored
+   * @param upper ignored
+   * @param seed  seed to initialize generator with
+   */
   template <typename TL = T, std::enable_if_t<cudf::is_boolean<TL>()>* = nullptr>
   UniformRandomGenerator(T lower,
                          T upper,
@@ -171,6 +178,7 @@ class UniformRandomGenerator {
 
   /**
    * @brief Returns the next random number.
+   *
    * @return generated random number
    */
   template <typename TL = T, std::enable_if_t<!cudf::is_timestamp<TL>()>* = nullptr>
@@ -179,6 +187,10 @@ class UniformRandomGenerator {
     return T{dist(rng)};
   }
 
+  /**
+   * @brief Returns the next random number.
+   * @return generated random number
+   */
   template <typename TL = T, std::enable_if_t<cudf::is_timestamp<TL>()>* = nullptr>
   T generate()
   {