Fix many documentation errors in libcudf. (#9355)

This PR fixes many documentation errors in libcudf code. (include and src)
Many errors are found through doxygen warnings.

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

Approvers:
  - David Wendt (https://github.com/davidwendt)
  - Mark Harris (https://github.com/harrism)

URL: #9355

cpp/include/cudf/aggregation.hpp

@@ -231,11 +231,11 @@ std::unique_ptr<Base> make_median_aggregation();
  * @brief Factory to create a QUANTILE aggregation
  *
  * @param quantiles The desired quantiles
- * @param interpolation The desired interpolation
+ * @param interp The desired interpolation
  */
 template <typename Base = aggregation>
-std::unique_ptr<Base> make_quantile_aggregation(std::vector<double> const& q,
-                                                interpolation i = interpolation::LINEAR);
+std::unique_ptr<Base> make_quantile_aggregation(std::vector<double> const& quantiles,
+                                                interpolation interp = interpolation::LINEAR);
 
 /**
  * @brief Factory to create an `argmax` aggregation

cpp/include/cudf/column/column_device_view.cuh

@@ -241,7 +241,7 @@ class alignas(16) column_device_view_base {
    * @note It is undefined behavior to call this function if `nullable() ==
    * false`.
    *
-   * @param element_index
+   * @param word_index The index of the word to get
    * @return bitmask word for the given word_index
    */
   __device__ bitmask_type get_mask_word(size_type word_index) const noexcept
@@ -1115,8 +1115,8 @@ class alignas(16) mutable_column_device_view : public detail::column_device_view
    * @note It is undefined behavior to call this function if `nullable() ==
    * false`.
    *
-   * @param element_index The index of the element to update
-   * @param new_element The new bitmask element
+   * @param word_index The index of the word to update
+   * @param new_word The new bitmask word
    */
   __device__ void set_mask_word(size_type word_index, bitmask_type new_word) const noexcept
   {
@@ -1274,6 +1274,7 @@ struct optional_accessor<T, contains_nulls::DYNAMIC> {
   /**
    * @brief constructor
    * @param[in] _col column device view of cudf column
+   * @param[in] with_nulls Indicates if @p _col has nulls
    */
   optional_accessor(column_device_view const& _col, bool with_nulls)
     : col{_col}, has_nulls{with_nulls}
@@ -1419,7 +1420,7 @@ struct mutable_value_accessor {
  * @tparam ColumnDeviceView is either column_device_view or mutable_column_device_view
  *
  * @param child_begin Iterator pointing to begin of child columns to make into a device view
- * @param child_begin Iterator pointing to end   of child columns to make into a device view
+ * @param child_end   Iterator pointing to end   of child columns to make into a device view
  * @param h_ptr The host memory where to place any child data
  * @param d_ptr The device pointer for calculating the d_children member of any child data
  * @return The device pointer to be used for the d_children member of the given column

cpp/include/cudf/column/column_factories.hpp

@@ -494,7 +494,7 @@ std::unique_ptr<column> make_strings_column(size_type num_strings,
  * data    (depth 1)   {1, 2, 3, 4, 5, 6, 7}
  * @endcode
  *
- * @param[in] num_lists The number of lists the column represents.
+ * @param[in] num_rows The number of lists the column represents.
  * @param[in] offsets_column The column of offset values for this column. Each value should
  * represent the starting offset into the child elements that corresponds to the beginning of the
  * row, with the first row starting at 0. The length of row N can be determined by subtracting
@@ -512,7 +512,7 @@ std::unique_ptr<column> make_strings_column(size_type num_strings,
  *           allocation of the column's `null_mask` and children.
  */
 std::unique_ptr<cudf::column> make_lists_column(
-  size_type num_lists,
+  size_type num_rows,
   std::unique_ptr<column> offsets_column,
   std::unique_ptr<column> child_column,
   size_type null_count,

cpp/include/cudf/column/column_view.hpp

@@ -254,8 +254,6 @@ class column_view_base {
    * indicator bitmask
    * @param null_count Optional, the number of null elements.
    * @param offset optional, index of the first element
-   * @param children optional, depending on the element type, child columns may
-   * contain additional data
    */
   column_view_base(data_type type,
                    size_type size,

cpp/include/cudf/copying.hpp

@@ -91,6 +91,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
  */
 std::unique_ptr<table> reverse(
   table_view const& source_table,
@@ -106,6 +107,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
  */
 std::unique_ptr<column> reverse(
   column_view const& source_column,
@@ -638,7 +640,7 @@ packed_columns pack(cudf::table_view const& input,
  * construct a `packed_columns` or `packed_table` structure.  The caller is responsible for
  * guaranteeing that that all of the columns in the table point into `contiguous_buffer`.
  *
- * @param input View of the table to pack
+ * @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`.

cpp/include/cudf/datetime.hpp

@@ -37,7 +37,8 @@ namespace datetime {
  * @brief  Extracts year from any date time type and returns an int16_t
  * cudf::column.
  *
- * @param[in] cudf::column_view of the input datetime values
+ * @param column cudf::column_view of the input datetime values
+ * @param mr Device memory resource used to allocate device memory of the returned column.
  *
  * @returns cudf::column of the extracted int16_t years
  * @throw cudf::logic_error if input column datatype is not TIMESTAMP
@@ -50,7 +51,8 @@ std::unique_ptr<cudf::column> extract_year(
  * @brief  Extracts month from any date time type and returns an int16_t
  * cudf::column.
  *
- * @param[in] cudf::column_view of the input datetime values
+ * @param column cudf::column_view of the input datetime values
+ * @param mr Device memory resource used to allocate device memory of the returned column.
  *
  * @returns cudf::column of the extracted int16_t months
  * @throw cudf::logic_error if input column datatype is not TIMESTAMP
@@ -63,7 +65,8 @@ std::unique_ptr<cudf::column> extract_month(
  * @brief  Extracts day from any date time type and returns an int16_t
  * cudf::column.
  *
- * @param[in] cudf::column_view of the input datetime values
+ * @param column cudf::column_view of the input datetime values
+ * @param mr Device memory resource used to allocate device memory of the returned column.
  *
  * @returns cudf::column of the extracted int16_t days
  * @throw cudf::logic_error if input column datatype is not TIMESTAMP
@@ -76,7 +79,8 @@ std::unique_ptr<cudf::column> extract_day(
  * @brief  Extracts day from any date time type and returns an int16_t
  * cudf::column.
  *
- * @param[in] cudf::column_view of the input datetime values
+ * @param column cudf::column_view of the input datetime values
+ * @param mr Device memory resource used to allocate device memory of the returned column.
  *
  * @returns cudf::column of the extracted int16_t days
  * @throw cudf::logic_error if input column datatype is not TIMESTAMP
@@ -89,7 +93,8 @@ std::unique_ptr<cudf::column> extract_weekday(
  * @brief  Extracts hour from any date time type and returns an int16_t
  * cudf::column.
  *
- * @param[in] cudf::column_view of the input datetime values
+ * @param column cudf::column_view of the input datetime values
+ * @param mr Device memory resource used to allocate device memory of the returned column.
  *
  * @returns cudf::column of the extracted int16_t hours
  * @throw cudf::logic_error if input column datatype is not TIMESTAMP
@@ -102,7 +107,8 @@ std::unique_ptr<cudf::column> extract_hour(
  * @brief  Extracts minute from any date time type and returns an int16_t
  * cudf::column.
  *
- * @param[in] cudf::column_view of the input datetime values
+ * @param column cudf::column_view of the input datetime values
+ * @param mr Device memory resource used to allocate device memory of the returned column.
  *
  * @returns cudf::column of the extracted int16_t minutes
  * @throw cudf::logic_error if input column datatype is not TIMESTAMP
@@ -115,7 +121,8 @@ std::unique_ptr<cudf::column> extract_minute(
  * @brief  Extracts second from any date time type and returns an int16_t
  * cudf::column.
  *
- * @param[in] cudf::column_view of the input datetime values
+ * @param column cudf::column_view of the input datetime values
+ * @param mr Device memory resource used to allocate device memory of the returned column.
  *
  * @returns cudf::column of the extracted int16_t seconds
  * @throw cudf::logic_error if input column datatype is not TIMESTAMP
@@ -135,7 +142,8 @@ std::unique_ptr<cudf::column> extract_second(
  * @brief  Computes the last day of the month in date time type and returns a TIMESTAMP_DAYS
  * cudf::column.
  *
- * @param[in] cudf::column_view of the input datetime values
+ * @param column cudf::column_view of the input datetime values
+ * @param mr Device memory resource used to allocate device memory of the returned column.
  *
  * @returns cudf::column containing last day of the month as TIMESTAMP_DAYS
  * @throw cudf::logic_error if input column datatype is not TIMESTAMP
@@ -148,7 +156,8 @@ std::unique_ptr<cudf::column> last_day_of_month(
  * @brief  Computes the day number since the start of the year from the datetime and
  * returns an int16_t cudf::column. The value is between [1, {365-366}]
  *
- * @param[in] cudf::column_view of the input datetime values
+ * @param column cudf::column_view of the input datetime values
+ * @param mr Device memory resource used to allocate device memory of the returned column.
  *
  * @returns cudf::column of datatype INT16 containing the day number since the start of the year.
  * @throw cudf::logic_error if input column datatype is not a TIMESTAMP
@@ -183,6 +192,7 @@ std::unique_ptr<cudf::column> day_of_year(
  *
  * @param timestamps cudf::column_view of timestamp type.
  * @param months cudf::column_view of integer type containing the number of months to add.
+ * @param mr Device memory resource used to allocate device memory of the returned column.
  *
  * @returns cudf::column of timestamp type containing the computed timestamps.
  */
@@ -217,6 +227,7 @@ std::unique_ptr<cudf::column> add_calendrical_months(
  *
  * @param timestamps cudf::column_view of timestamp type.
  * @param months cudf::scalar of integer type containing the number of months to add.
+ * @param mr Device memory resource used to allocate device memory of the returned column.
  *
  * @return cudf::column of timestamp type containing the computed timestamps.
  */
@@ -232,7 +243,8 @@ std::unique_ptr<cudf::column> add_calendrical_months(
  * `output[i] == false` if year of `column[i]` is not a leap year
  * `output[i] is null` if `column[i]` is null
  *
- * @param[in] cudf::column_view of the input datetime values
+ * @param column cudf::column_view of the input datetime values
+ * @param mr Device memory resource used to allocate device memory of the returned column.
  *
  * @returns cudf::column of datatype BOOL8 truth value of the corresponding date
  * @throw cudf::logic_error if input column datatype is not a TIMESTAMP
@@ -249,7 +261,8 @@ std::unique_ptr<cudf::column> is_leap_year(
  *
  * @throw cudf::logic_error if input column datatype is not a TIMESTAMP
  *
- * @param cudf::column_view of the input datetime values
+ * @param column cudf::column_view of the input datetime values
+ * @param mr Device memory resource used to allocate device memory of the returned column.
  * @return cudf::column of datatype INT16 of days in month of the corresponding date
  */
 std::unique_ptr<cudf::column> days_in_month(
@@ -264,7 +277,8 @@ std::unique_ptr<cudf::column> days_in_month(
  *
  * @throw cudf::logic_error if input column datatype is not a TIMESTAMP
  *
- * @param The input column containing datetime values
+ * @param column The input column containing datetime values
+ * @param mr Device memory resource used to allocate device memory of the returned column.
  * @return A column of INT16 type indicating which quarter the date is in
  */
 std::unique_ptr<cudf::column> extract_quarter(
@@ -276,7 +290,8 @@ std::unique_ptr<cudf::column> extract_quarter(
 /**
  * @brief Round up to the nearest day
  *
- * @param cudf::column_view of the input datetime values
+ * @param column cudf::column_view of the input datetime values
+ * @param mr Device memory resource used to allocate device memory of the returned column.
  *
  * @throw cudf::logic_error if input column datatype is not TIMESTAMP
  * @return cudf::column of the same datetime resolution as the input column
@@ -288,7 +303,8 @@ std::unique_ptr<cudf::column> ceil_day(
 /**
  * @brief Round up to the nearest hour
  *
- * @param cudf::column_view of the input datetime values
+ * @param column cudf::column_view of the input datetime values
+ * @param mr Device memory resource used to allocate device memory of the returned column.
  *
  * @throw cudf::logic_error if input column datatype is not TIMESTAMP
  * @return cudf::column of the same datetime resolution as the input column
@@ -300,7 +316,8 @@ std::unique_ptr<cudf::column> ceil_hour(
 /**
  * @brief Round up to the nearest minute
  *
- * @param cudf::column_view of the input datetime values
+ * @param column cudf::column_view of the input datetime values
+ * @param mr Device memory resource used to allocate device memory of the returned column.
  *
  * @throw cudf::logic_error if input column datatype is not TIMESTAMP
  * @return cudf::column of the same datetime resolution as the input column
@@ -312,7 +329,8 @@ std::unique_ptr<cudf::column> ceil_minute(
 /**
  * @brief Round up to the nearest second
  *
- * @param cudf::column_view of the input datetime values
+ * @param column cudf::column_view of the input datetime values
+ * @param mr Device memory resource used to allocate device memory of the returned column.
  *
  * @throw cudf::logic_error if input column datatype is not TIMESTAMP
  * @return cudf::column of the same datetime resolution as the input column
@@ -324,7 +342,8 @@ std::unique_ptr<cudf::column> ceil_second(
 /**
  * @brief Round up to the nearest millisecond
  *
- * @param cudf::column_view of the input datetime values
+ * @param column cudf::column_view of the input datetime values
+ * @param mr Device memory resource used to allocate device memory of the returned column.
  *
  * @throw cudf::logic_error if input column datatype is not TIMESTAMP
  * @return cudf::column of the same datetime resolution as the input column
@@ -336,7 +355,8 @@ std::unique_ptr<column> ceil_millisecond(
 /**
  * @brief Round up to the nearest microsecond
  *
- * @param cudf::column_view of the input datetime values
+ * @param column cudf::column_view of the input datetime values
+ * @param mr Device memory resource used to allocate device memory of the returned column.
  *
  * @throw cudf::logic_error if input column datatype is not TIMESTAMP
  * @return cudf::column of the same datetime resolution as the input column
@@ -348,7 +368,8 @@ std::unique_ptr<column> ceil_microsecond(
 /**
  * @brief Round up to the nearest nanosecond
  *
- * @param cudf::column_view of the input datetime values
+ * @param column cudf::column_view of the input datetime values
+ * @param mr Device memory resource used to allocate device memory of the returned column.
  *
  * @throw cudf::logic_error if input column datatype is not TIMESTAMP
  * @return cudf::column of the same datetime resolution as the input column

cpp/include/cudf/detail/label_bins.hpp

@@ -39,8 +39,8 @@ namespace detail {
 
 /**
  * @copydoc cudf::label_bins(column_view const& input, column_view const& left_edges, inclusive
- * left_inclusive, column_view const& right_edges, inclusive right_inclusive, null_order
- * edge_null_precedence null_order::BEFORE, rmm::mr::device_memory_resource* mr)
+ * left_inclusive, column_view const& right_edges, inclusive right_inclusive, rmm::cuda_stream_view,
+ * rmm::mr::device_memory_resource* mr)
  *
  * @param stream Stream view on which to allocate resources and queue execution.
  */

cpp/include/cudf/dictionary/dictionary_factories.hpp

@@ -106,8 +106,8 @@ std::unique_ptr<column> make_dictionary_column(std::unique_ptr<column> keys_colu
  *
  * @throw cudf::logic_error if keys_column contains nulls
  *
- * @param keys Column of unique, ordered values to use as the new dictionary column's keys.
- * @param indices Indices values and null-mask to use for the new dictionary column.
+ * @param keys_column Column of unique, ordered values to use as the new dictionary column's keys.
+ * @param indices_column Indices values and null-mask to use for the new dictionary column.
  * @param stream CUDA stream used for device memory operations and kernel launches.
  * @param mr Device memory resource used to allocate the returned column's device memory.
  * @return New dictionary column.

cpp/include/cudf/dictionary/search.hpp

@@ -34,6 +34,7 @@ namespace dictionary {
  *
  * @param dictionary The dictionary to search for the key.
  * @param key The value to search for in the dictionary keyset.
+ * @param mr Device memory resource used to allocate the returned scalar's device memory.
  * @return Numeric scalar index value of the key within the dictionary
  */
 std::unique_ptr<scalar> get_index(

cpp/include/cudf/filling.hpp

@@ -52,7 +52,6 @@ namespace cudf {
  * @param begin The starting index of the fill range (inclusive)
  * @param end The index of the last element in the fill range (exclusive)
  * @param value The scalar value to fill
- * @return void
  */
 void fill_in_place(mutable_column_view& destination,
                    size_type begin,
@@ -162,7 +161,7 @@ std::unique_ptr<table> repeat(
  * step = 2
  * return = [0, 2, 4]
  * ```
- * @throws cudf::logic_error if @p init and @p @step are not the same type.
+ * @throws cudf::logic_error if @p init and @p step are not the same type.
  * @throws cudf::logic_error if scalar types are not numeric.
  * @throws cudf::logic_error if @p size is < 0.
  *

cpp/include/cudf/hashing.hpp

@@ -29,12 +29,14 @@ namespace cudf {
 /**
  * @brief Computes the hash value of each row in the input set of columns.
  *
- * @param input The table of columns to hash
+ * @param input The table of columns to hash.
+ * @param hash_function The hash function enum to use.
  * @param initial_hash Optional host_span of initial hash values for each column.
  * If this span is empty then each element will be hashed as-is.
+ * @param seed Optional seed value to use for the hash function.
  * @param mr Device memory resource used to allocate the returned column's device memory.
  *
- * @returns A column where each row is the hash of a column from the input
+ * @returns A column where each row is the hash of a column from the input.
  */
 std::unique_ptr<column> hash(
   table_view const& input,

cpp/include/cudf/io/avro.hpp

@@ -102,15 +102,13 @@ class avro_reader_options {
    * @brief Sets number of rows to skip.
    *
    * @param val Number of rows to skip from start.
-   * @return this for chaining.
    */
   void set_skip_rows(size_type val) { _skip_rows = val; }
 
   /**
    * @brief Sets number of rows to read.
    *
    * @param val Number of rows to read after skip.
-   * @return this for chaining.
    */
   void set_num_rows(size_type val) { _num_rows = val; }