Fix doxygen warnings in structs, lists headers (#10923)

Fixes parts of #9373
added missing documentation to fix doxygen warnings in `structs/*.hpp` and `lists/*.hpp`
fixes 67 warnings.

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

Approvers:
  - David Wendt (https://github.com/davidwendt)
  - Vyas Ramasubramani (https://github.com/vyasr)

URL: #10923

cpp/include/cudf/lists/drop_list_duplicates.hpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021, NVIDIA CORPORATION.
+ * Copyright (c) 2021-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.
@@ -97,7 +97,6 @@ std::pair<std::unique_ptr<column>, std::unique_ptr<column>> drop_list_duplicates
  * @param nulls_equal Flag to specify whether null key elements should be considered as equal.
  * @param nans_equal Flag to specify whether NaN key elements should be considered as equal
  *        (only applicable for floating point keys column).
- * @param keep_option Flag to specify which elements will be copied from the input to the output.
  * @param mr Device resource used to allocate memory.
  *
  * @code{.pseudo}

cpp/include/cudf/lists/list_device_view.cuh

@@ -36,6 +36,12 @@ class list_device_view {
  public:
   list_device_view() = default;
 
+  /**
+   * @brief Constructs a list_device_view from a list column and index.
+   *
+   * @param lists_column list column device view containing the list to view
+   * @param row_index index of the list row to view
+   */
   __device__ inline list_device_view(lists_column_device_view const& lists_column,
                                      size_type const& row_index)
     : lists_column(lists_column), _row_index(row_index)
@@ -72,6 +78,9 @@ class list_device_view {
    *
    * The offset of this element as stored in the child column (i.e. 5)
    * may be fetched using this method.
+   *
+   * @param idx The list index of the element to fetch the offset for
+   * @return The offset of the element at the specified list index
    */
   [[nodiscard]] __device__ inline size_type element_offset(size_type idx) const
   {
@@ -93,7 +102,10 @@ class list_device_view {
   }
 
   /**
-   * @brief Checks whether element is null at specified index in the list row.
+   * @brief Checks whether the element is null at the specified index in the list
+   *
+   * @param idx The index into the list row
+   * @return `true` if the element is null at the specified index in the list row
    */
   [[nodiscard]] __device__ inline bool is_null(size_type idx) const
   {
@@ -104,16 +116,22 @@ class list_device_view {
 
   /**
    * @brief Checks whether this list row is null.
+   *
+   * @return `true` if this list is null
    */
   [[nodiscard]] __device__ inline bool is_null() const { return lists_column.is_null(_row_index); }
 
   /**
    * @brief Fetches the number of elements in this list row.
+   *
+   * @return The number of elements in this list row
    */
   [[nodiscard]] __device__ inline size_type size() const { return _size; }
 
   /**
    * @brief Fetches the lists_column_device_view that contains this list.
+   *
+   * @return The lists_column_device_view that contains this list
    */
   [[nodiscard]] __device__ inline lists_column_device_view const& get_column() const
   {
@@ -126,10 +144,12 @@ class list_device_view {
   template <typename T>
   struct pair_rep_accessor;
 
+  /// const pair iterator for the list
   template <typename T>
   using const_pair_iterator =
     thrust::transform_iterator<pair_accessor<T>, thrust::counting_iterator<cudf::size_type>>;
 
+  /// const pair iterator type for the list
   template <typename T>
   using const_pair_rep_iterator =
     thrust::transform_iterator<pair_rep_accessor<T>, thrust::counting_iterator<cudf::size_type>>;
@@ -146,6 +166,9 @@ class list_device_view {
    * If the element at index `i` is null,
    *   1. `p.first` is undefined
    *   2. `p.second == false`
+   *
+   * @return A pair iterator to the first element in the list_device_view and whether or not the
+   * element is valid
    */
   template <typename T>
   [[nodiscard]] __device__ inline const_pair_iterator<T> pair_begin() const
@@ -156,6 +179,9 @@ class list_device_view {
   /**
    * @brief Fetcher for a pair iterator to one position past the last element in the
    * list_device_view.
+   *
+   * @return A pair iterator to one past the last element in the list_device_view and whether or not
+   * that element is valid
    */
   template <typename T>
   [[nodiscard]] __device__ inline const_pair_iterator<T> pair_end() const
@@ -178,6 +204,9 @@ class list_device_view {
    * If the element at index `i` is null,
    *   1. `p.first` is undefined
    *   2. `p.second == false`
+   *
+   * @return A pair iterator to the first element in the list_device_view and whether or not that
+   * element is valid
    */
   template <typename T>
   [[nodiscard]] __device__ inline const_pair_rep_iterator<T> pair_rep_begin() const
@@ -189,6 +218,9 @@ class list_device_view {
   /**
    * @brief Fetcher for a pair iterator to one position past the last element in the
    * list_device_view.
+   *
+   * @return A pair iterator one past the last element in the list_device_view and whether or not
+   * that element is valid
    */
   template <typename T>
   [[nodiscard]] __device__ inline const_pair_rep_iterator<T> pair_rep_end() const
@@ -215,7 +247,7 @@ class list_device_view {
    */
   template <typename T>
   struct pair_accessor {
-    list_device_view const& list;
+    list_device_view const& list;  ///< The list_device_view to access
 
     /**
      * @brief constructor
@@ -250,9 +282,9 @@ class list_device_view {
    */
   template <typename T>
   struct pair_rep_accessor {
-    list_device_view const& list;
+    list_device_view const& list;  ///< The list_device_view whose rows are being accessed
 
-    using rep_type = device_storage_type_t<T>;
+    using rep_type = device_storage_type_t<T>;  ///< The type used to store the value on the device
 
     /**
      * @brief constructor
@@ -290,15 +322,26 @@ class list_device_view {
 };
 
 /**
- * @brief returns size of the list by row index
+ * @brief Returns the size of the list by row index
  *
  */
 struct list_size_functor {
-  detail::lists_column_device_view const d_column;
+  detail::lists_column_device_view const d_column;  ///< The list column to access
+  /**
+   * @brief Constructor
+   *
+   * @param d_col The cudf::lists_column_device_view whose rows are being accessed
+   */
   CUDF_HOST_DEVICE inline list_size_functor(detail::lists_column_device_view const& d_col)
     : d_column(d_col)
   {
   }
+  /**
+   * @brief Returns size of the list by row index
+   *
+   * @param idx row index
+   * @return size of the list
+   */
   __device__ inline size_type operator()(size_type idx)
   {
     if (d_column.is_null(idx)) return size_type{0};
@@ -318,6 +361,8 @@ struct list_size_functor {
  * assert(it[2] == 4);
  * @endcode
  *
+ * @param c The list_column_device_view to iterate over
+ * @return An iterator that returns the size of the list by row index
  */
 CUDF_HOST_DEVICE auto inline make_list_size_iterator(detail::lists_column_device_view const& c)
 {

cpp/include/cudf/lists/lists_column_device_view.cuh

@@ -33,11 +33,26 @@ class lists_column_device_view : private column_device_view {
  public:
   lists_column_device_view()                                = delete;
   ~lists_column_device_view()                               = default;
-  lists_column_device_view(lists_column_device_view const&) = default;
-  lists_column_device_view(lists_column_device_view&&)      = default;
+  lists_column_device_view(lists_column_device_view const&) = default;  ///< Copy constructor
+  lists_column_device_view(lists_column_device_view&&)      = default;  ///< Move constructor
+  /**
+   * @brief Copy assignment operator
+   *
+   * @return The reference to this lists column device view
+   */
   lists_column_device_view& operator=(lists_column_device_view const&) = default;
+  /**
+   * @brief Move assignment operator
+   *
+   * @return The reference to this lists column device view
+   */
   lists_column_device_view& operator=(lists_column_device_view&&) = default;
 
+  /**
+   * @brief Construct a new lists column device view object from a column device view.
+   *
+   * @param underlying_ The column device view to wrap
+   */
   CUDF_HOST_DEVICE lists_column_device_view(column_device_view const& underlying_)
     : column_device_view(underlying_)
   {
@@ -57,6 +72,8 @@ class lists_column_device_view : private column_device_view {
 
   /**
    * @brief Fetches the offsets column of the underlying list column.
+   *
+   * @return The offsets column of the underlying list column
    */
   [[nodiscard]] __device__ inline column_device_view offsets() const
   {
@@ -66,6 +83,9 @@ class lists_column_device_view : private column_device_view {
   /**
    * @brief Fetches the list offset value at a given row index while taking column offset into
    * account.
+   *
+   * @param idx The row index to fetch the list offset value at
+   * @return The list offset value at a given row index while taking column offset into account
    */
   [[nodiscard]] __device__ inline size_type offset_at(size_type idx) const
   {
@@ -74,6 +94,8 @@ class lists_column_device_view : private column_device_view {
 
   /**
    * @brief Fetches the child column of the underlying list column.
+   *
+   * @return The child column of the underlying list column
    */
   [[nodiscard]] __device__ inline column_device_view child() const
   {
@@ -82,6 +104,8 @@ class lists_column_device_view : private column_device_view {
 
   /**
    * @brief Fetches the child column of the underlying list column with offset and size applied
+   *
+   * @return The child column sliced relative to the parent's offset and size
    */
   [[nodiscard]] __device__ inline column_device_view get_sliced_child() const
   {

cpp/include/cudf/lists/lists_column_view.hpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2020-2021, NVIDIA CORPORATION.
+ * Copyright (c) 2020-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.
@@ -38,15 +38,30 @@ namespace cudf {
  */
 class lists_column_view : private column_view {
  public:
+  /**
+   * @brief Construct a new lists column view object from a column view.
+   *
+   * @param lists_column The column view to wrap
+   */
   lists_column_view(column_view const& lists_column);
-  lists_column_view(lists_column_view&& lists_view)      = default;
-  lists_column_view(const lists_column_view& lists_view) = default;
-  ~lists_column_view()                                   = default;
+  lists_column_view(lists_column_view&&)      = default;  ///< Move constructor
+  lists_column_view(const lists_column_view&) = default;  ///< Copy constructor
+  ~lists_column_view()                        = default;
+  /**
+   * @brief Copy assignment operator
+   *
+   * @return The reference to this lists column
+   */
   lists_column_view& operator=(lists_column_view const&) = default;
+  /**
+   * @brief Move assignment operator
+   *
+   * @return The reference to this lists column
+   */
   lists_column_view& operator=(lists_column_view&&) = default;
 
-  static constexpr size_type offsets_column_index{0};
-  static constexpr size_type child_column_index{1};
+  static constexpr size_type offsets_column_index{0};  ///< The index of the offsets column
+  static constexpr size_type child_column_index{1};    ///< The index of the child column
 
   using column_view::child_begin;
   using column_view::child_end;
@@ -58,24 +73,28 @@ class lists_column_view : private column_view {
   using column_view::size;
   static_assert(std::is_same_v<offset_type, size_type>,
                 "offset_type is expected to be the same as size_type.");
-  using offset_iterator = offset_type const*;
+  using offset_iterator = offset_type const*;  ///< Iterator type for offsets
 
   /**
    * @brief Returns the parent column.
+   *
+   * @return The parent column
    */
   [[nodiscard]] column_view parent() const;
 
   /**
    * @brief Returns the internal column of offsets
    *
    * @throw cudf::logic error if this is an empty column
+   * @return The internal column of offsets
    */
   [[nodiscard]] column_view offsets() const;
 
   /**
    * @brief Returns the internal child column
    *
    * @throw cudf::logic error if this is an empty column
+   * @return The internal child column
    */
   [[nodiscard]] column_view child() const;
 
@@ -88,6 +107,8 @@ class lists_column_view : private column_view {
    * on lists columns should be using `get_sliced_child()` instead of `child()`.
    *
    * @throw cudf::logic error if this is an empty column
+   * @param stream CUDA stream used for device memory operations and kernel launches
+   * @return A sliced child column view
    */
   [[nodiscard]] column_view get_sliced_child(rmm::cuda_stream_view stream) const;
 

cpp/include/cudf/structs/structs_column_device_view.cuh

@@ -31,11 +31,27 @@ class structs_column_device_view : private column_device_view {
  public:
   structs_column_device_view()                                  = delete;
   ~structs_column_device_view()                                 = default;
-  structs_column_device_view(structs_column_device_view const&) = default;
-  structs_column_device_view(structs_column_device_view&&)      = default;
+  structs_column_device_view(structs_column_device_view const&) = default;  ///< Copy constructor
+  structs_column_device_view(structs_column_device_view&&)      = default;  ///< Move constructor
+  /**
+   * @brief Copy assignment operator
+   *
+   * @return The reference to this structs column
+   */
   structs_column_device_view& operator=(structs_column_device_view const&) = default;
+
+  /**
+   * @brief Move assignment operator
+   *
+   * @return The reference to this structs column
+   */
   structs_column_device_view& operator=(structs_column_device_view&&) = default;
 
+  /**
+   * @brief Construct a new structs column device view object from a column device view.
+   *
+   * @param underlying_ The column device view to wrap
+   */
   CUDF_HOST_DEVICE structs_column_device_view(column_device_view const& underlying_)
     : column_device_view(underlying_)
   {
@@ -56,6 +72,9 @@ class structs_column_device_view : private column_device_view {
 
   /**
    * @brief Fetches the child column of the underlying struct column.
+   *
+   * @param idx The index of the child column to fetch
+   * @return The child column sliced relative to the parent's offset and size
    */
   [[nodiscard]] __device__ inline column_device_view get_sliced_child(size_type idx) const
   {