Fix doxygen warnings in cudf/*.hpp (#10896)

Fixes parts of #9373
added missing documentation to fix doxygen warnings in multiple files cpp/include/cudf/*.hpp
fixes 40 warnings

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

Approvers:
  - David Wendt (https://github.com/davidwendt)
  - Bradley Dice (https://github.com/bdice)

URL: #10896

cpp/include/cudf/concatenate.hpp

@@ -52,7 +52,7 @@ rmm::device_buffer concatenate_masks(
  * If types of the input columns mismatch
  *
  * @param columns_to_concat host_span of column views to be concatenated into a single column
- * @param mr Device memory resource used to allocate the returned column's device memory.
+ * @param mr Device memory resource used to allocate the returned column's device memory
  * @return A single column having all the rows from the elements of `columns_to_concat` respectively
  * in the same order.
  */
@@ -82,7 +82,7 @@ std::unique_ptr<column> concatenate(
  * If number of columns mismatch
  *
  * @param tables_to_concat host_span of table views to be concatenated into a single table
- * @param mr Device memory resource used to allocate the returned table's device memory.
+ * @param mr Device memory resource used to allocate the returned table's device memory
  * @return A single table having all the rows from the elements of `tables_to_concat` respectively
  * in the same order.
  */

cpp/include/cudf/copying.hpp

@@ -95,6 +95,7 @@ std::unique_ptr<table> gather(
  *
  * @param source_table Table that will be reversed
  * @param mr Device memory resource used to allocate the returned table's device memory
+ * @return Reversed table
  */
 std::unique_ptr<table> reverse(
   table_view const& source_table,
@@ -111,6 +112,7 @@ std::unique_ptr<table> reverse(
  *
  * @param source_column Column that will be reversed
  * @param mr Device memory resource used to allocate the returned table's device memory
+ * @return Reversed column
  */
 std::unique_ptr<column> reverse(
   column_view const& source_column,
@@ -150,7 +152,7 @@ std::unique_ptr<column> reverse(
  * are to be scattered
  * @param check_bounds Optionally perform bounds checking on the values of
  * `scatter_map` and throw an error if any of its values are out of bounds.
- * @param mr Device memory resource used to allocate the returned table's device memory.
+ * @param mr Device memory resource used to allocate the returned table's device memory
  * @return Result of scattering values from source to target
  */
 std::unique_ptr<table> scatter(
@@ -190,7 +192,7 @@ std::unique_ptr<table> scatter(
  * are to be scattered
  * @param check_bounds Optionally perform bounds checking on the values of
  * `scatter_map` and throw an error if any of its values are out of bounds.
- * @param mr Device memory resource used to allocate the returned table's device memory.
+ * @param mr Device memory resource used to allocate the returned table's device memory
  * @return Result of scattering values from source to target
  */
 std::unique_ptr<table> scatter(
@@ -230,7 +232,7 @@ std::unique_ptr<column> empty_like(scalar const& input);
  * Supports only fixed-width types.
  *
  * @param[in] input Immutable view of input column to emulate
- * @param[in] mask_alloc Optional, Policy for allocating null mask. Defaults to RETAIN.
+ * @param[in] mask_alloc Optional, Policy for allocating null mask. Defaults to RETAIN
  * @param[in] mr Device memory resource used to allocate the returned column's device memory
  * @return A column with sufficient uninitialized capacity to hold the same
  * number of elements as `input` of the same type as `input.type()`
@@ -246,7 +248,7 @@ std::unique_ptr<column> allocate_like(
  *
  * @param[in] input Immutable view of input column to emulate
  * @param[in] size The desired number of elements that the new column should have capacity for
- * @param[in] mask_alloc Optional, Policy for allocating null mask. Defaults to RETAIN.
+ * @param[in] mask_alloc Optional, Policy for allocating null mask. Defaults to RETAIN
  * @param[in] mr Device memory resource used to allocate the returned column's device memory
  * @return A column with sufficient uninitialized capacity to hold the specified number of elements
  * as `input` of the same type as `input.type()`
@@ -326,13 +328,13 @@ void copy_range_in_place(column_view const& source,
  * @p target_begin + (@p source_end - @p source_begin) > @p target.size()).
  * @throws cudf::logic_error if @p target and @p source have different types.
  *
- * @param source The column to copy from inside the range.
- * @param target The column to copy from outside the range.
+ * @param source The column to copy from inside the range
+ * @param target The column to copy from outside the range
  * @param source_begin The starting index of the source range (inclusive)
  * @param source_end The index of the last element in the source range
  * (exclusive)
  * @param target_begin The starting index of the target range (inclusive)
- * @param mr Device memory resource used to allocate the returned column's device memory.
+ * @param mr Device memory resource used to allocate the returned column's device memory
  * @return std::unique_ptr<column> The result target column
  */
 std::unique_ptr<column> copy_range(
@@ -369,13 +371,15 @@ std::unique_ptr<column> copy_range(
  * @note if the input is nullable, the output will be nullable.
  * @note if the fill value is null, the output will be nullable.
  *
- * @param input      Column to be shifted.
- * @param offset     The offset by which to shift the input.
- * @param fill_value Fill value for indeterminable outputs.
+ * @param input      Column to be shifted
+ * @param offset     The offset by which to shift the input
+ * @param fill_value Fill value for indeterminable outputs
  * @param mr         Device memory resource used to allocate the returned result's device memory
  *
  * @throw cudf::logic_error if @p input dtype is neither fixed-width nor string type
  * @throw cudf::logic_error if @p fill_value dtype does not match @p input dtype.
+ *
+ * @return The shifted column
  */
 std::unique_ptr<column> shift(
   column_view const& input,
@@ -410,8 +414,8 @@ std::unique_ptr<column> shift(
  * the range [0, input.size()).
  *
  * @param input View of column to slice
- * @param indices Indices used to take slices of `input`.
- * @return Vector of views of `input` indicated by the ranges in `indices`.
+ * @param indices Indices used to take slices of `input`
+ * @return Vector of views of `input` indicated by the ranges in `indices`
  */
 std::vector<column_view> slice(column_view const& input, host_span<size_type const> indices);
 /**
@@ -449,8 +453,8 @@ std::vector<column_view> slice(column_view const& input, std::initializer_list<s
  * the range [0, input.size()).
  *
  * @param input View of table to slice
- * @param indices Indices used to take slices of `input`.
- * @return Vector of views of `input` indicated by the ranges in `indices`.
+ * @param indices Indices used to take slices of `input`
+ * @return Vector of views of `input` indicated by the ranges in `indices`
  */
 std::vector<table_view> slice(table_view const& input, host_span<size_type const> indices);
 /**
@@ -489,7 +493,7 @@ std::vector<table_view> slice(table_view const& input, std::initializer_list<siz
  *
  * @param input View of column to split
  * @param splits Indices where the view will be split
- * @return The set of requested views of `input` indicated by the `splits`.
+ * @return The set of requested views of `input` indicated by the `splits`
  */
 std::vector<column_view> split(column_view const& input, host_span<size_type const> splits);
 /**
@@ -530,7 +534,7 @@ std::vector<column_view> split(column_view const& input, std::initializer_list<s
  *
  * @param input View of a table to split
  * @param splits Indices where the view will be split
- * @return The set of requested views of `input` indicated by the `splits`.
+ * @return The set of requested views of `input` indicated by the `splits`
  */
 std::vector<table_view> split(table_view const& input, host_span<size_type const> splits);
 /**
@@ -555,8 +559,26 @@ struct packed_columns {
    */
   struct metadata {
     metadata() = default;
+
+    /**
+     * @brief Construct a new metadata object
+     *
+     * @param v Host-side buffer containing metadata
+     */
     metadata(std::vector<uint8_t>&& v) : data_(std::move(v)) {}
+
+    /**
+     * @brief Returns pointer to the host-side metadata buffer data
+     *
+     * @return Pointer to the host-side metadata buffer
+     */
     [[nodiscard]] uint8_t const* data() const { return data_.data(); }
+
+    /**
+     * @brief Returns size of the metadata buffer
+     *
+     * @return Size of the metadata buffer
+     */
     [[nodiscard]] size_t size() const { return data_.size(); }
 
    private:
@@ -567,17 +589,24 @@ struct packed_columns {
     : metadata_(std::make_unique<metadata>()), gpu_data(std::make_unique<rmm::device_buffer>())
   {
   }
+
+  /**
+   * @brief Construct a new packed columns object
+   *
+   * @param md Host-side metadata buffer
+   * @param gd Device-side data buffer
+   */
   packed_columns(std::unique_ptr<metadata>&& md, std::unique_ptr<rmm::device_buffer>&& gd)
     : metadata_(std::move(md)), gpu_data(std::move(gd))
   {
   }
 
-  std::unique_ptr<metadata> metadata_;
-  std::unique_ptr<rmm::device_buffer> gpu_data;
+  std::unique_ptr<metadata> metadata_;           ///< Host-side metadata buffer
+  std::unique_ptr<rmm::device_buffer> gpu_data;  ///< Device-side data buffer
 };
 
 /**
- * @brief The result(s) of a `contiguous_split`
+ * @brief The result(s) of a cudf::contiguous_split
  *
  * @ingroup copy_split
  *
@@ -591,8 +620,8 @@ struct packed_columns {
  * not outlive the memory owned by `data`
  */
 struct packed_table {
-  cudf::table_view table;
-  packed_columns data;
+  cudf::table_view table;  ///< Result table_view of a cudf::contiguous_split
+  packed_columns data;     ///< Column data owned
 };
 
 /**
@@ -666,8 +695,8 @@ packed_columns pack(cudf::table_view const& input,
  * @param table View of the table to pack
  * @param contiguous_buffer A contiguous buffer of device memory which contains the data referenced
  * by the columns in `table`
- * @param buffer_size The size of `contiguous_buffer`.
- * @return Vector of bytes representing the metadata used to `unpack` a packed_columns struct.
+ * @param buffer_size The size of `contiguous_buffer`
+ * @return Vector of bytes representing the metadata used to `unpack` a packed_columns struct
  */
 packed_columns::metadata pack_metadata(table_view const& table,
                                        uint8_t const* contiguous_buffer,
@@ -834,10 +863,10 @@ std::unique_ptr<column> copy_if_else(
  *
  * @param[in] input table_view (set of dense columns) to scatter
  * @param[in] target table_view to modify with scattered values from `input`
- * @param[in] boolean_mask column_view which acts as boolean mask.
- * @param[in] mr Device memory resource used to allocate device memory of the returned table.
+ * @param[in] boolean_mask column_view which acts as boolean mask
+ * @param[in] mr Device memory resource used to allocate device memory of the returned table
  *
- * @returns Returns a table by scattering `input` into `target` as per `boolean_mask`.
+ * @returns Returns a table by scattering `input` into `target` as per `boolean_mask`
  */
 std::unique_ptr<table> boolean_mask_scatter(
   table_view const& input,
@@ -871,10 +900,10 @@ std::unique_ptr<table> boolean_mask_scatter(
  *
  * @param[in] input scalars to scatter
  * @param[in] target table_view to modify with scattered values from `input`
- * @param[in] boolean_mask column_view which acts as boolean mask.
- * @param[in] mr Device memory resource used to allocate device memory of the returned table.
+ * @param[in] boolean_mask column_view which acts as boolean mask
+ * @param[in] mr Device memory resource used to allocate device memory of the returned table
  *
- * @returns Returns a table by scattering `input` into `target` as per `boolean_mask`.
+ * @returns Returns a table by scattering `input` into `target` as per `boolean_mask`
  */
 std::unique_ptr<table> boolean_mask_scatter(
   std::vector<std::reference_wrapper<const scalar>> const& input,
@@ -892,7 +921,7 @@ std::unique_ptr<table> boolean_mask_scatter(
  *
  * @param input Column view to get the element from
  * @param index Index into `input` to get the element at
- * @param mr Device memory resource used to allocate the returned scalar's device memory.
+ * @param mr Device memory resource used to allocate the returned scalar's device memory
  * @return std::unique_ptr<scalar> Scalar containing the single value
  */
 std::unique_ptr<scalar> get_element(
@@ -927,10 +956,10 @@ enum class sample_with_replacement : bool {
  * @throws cudf::logic_error if `n` > `input.num_rows()` and `replacement` == FALSE.
  * @throws cudf::logic_error if `n` < 0.
  *
- * @param input View of a table to sample.
- * @param n non-negative number of samples expected from `input`.
- * @param replacement Allow or disallow sampling of the same row more than once.
- * @param seed Seed value to initiate random number generator.
+ * @param input View of a table to sample
+ * @param n non-negative number of samples expected from `input`
+ * @param replacement Allow or disallow sampling of the same row more than once
+ * @param seed Seed value to initiate random number generator
  * @param mr Device memory resource used to allocate the returned table's device memory
  *
  * @return std::unique_ptr<table> Table containing samples from `input`
@@ -955,8 +984,8 @@ std::unique_ptr<table> sample(
  *
  * @param input The column which is (and whose descendants are) to be checked for
  * non-empty null rows.
- * @return true If either the column or its descendants have non-empty null rows.
- * @return false If neither the column or its descendants have non-empty null rows.
+ * @return true If either the column or its descendants have non-empty null rows
+ * @return false If neither the column or its descendants have non-empty null rows
  */
 bool has_nonempty_nulls(column_view const& input);