From 3ab2c40b37c6cf26686f71c9b599a55d060a3223 Mon Sep 17 00:00:00 2001 From: Karthikeyan <6488848+karthikeyann@users.noreply.github.com> Date: Wed, 1 Jun 2022 14:48:56 +0530 Subject: [PATCH] Fix doxygen warnings in structs, lists headers (#10923) Fixes parts of https://github.com/rapidsai/cudf/issues/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: https://github.com/rapidsai/cudf/pull/10923 --- .../cudf/lists/drop_list_duplicates.hpp | 3 +- cpp/include/cudf/lists/list_device_view.cuh | 57 +++++++++++++++++-- .../cudf/lists/lists_column_device_view.cuh | 28 ++++++++- cpp/include/cudf/lists/lists_column_view.hpp | 35 +++++++++--- .../structs/structs_column_device_view.cuh | 23 +++++++- .../cudf/structs/structs_column_view.hpp | 30 +++++++++- 6 files changed, 154 insertions(+), 22 deletions(-) diff --git a/cpp/include/cudf/lists/drop_list_duplicates.hpp b/cpp/include/cudf/lists/drop_list_duplicates.hpp index baec8dfdc9f..25dee22d56c 100644 --- a/cpp/include/cudf/lists/drop_list_duplicates.hpp +++ b/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> 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} diff --git a/cpp/include/cudf/lists/list_device_view.cuh b/cpp/include/cudf/lists/list_device_view.cuh index 5cc1e3d166b..315bfd7dad3 100644 --- a/cpp/include/cudf/lists/list_device_view.cuh +++ b/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 struct pair_rep_accessor; + /// const pair iterator for the list template using const_pair_iterator = thrust::transform_iterator, thrust::counting_iterator>; + /// const pair iterator type for the list template using const_pair_rep_iterator = thrust::transform_iterator, thrust::counting_iterator>; @@ -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 [[nodiscard]] __device__ inline const_pair_iterator 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 [[nodiscard]] __device__ inline const_pair_iterator 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 [[nodiscard]] __device__ inline const_pair_rep_iterator 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 [[nodiscard]] __device__ inline const_pair_rep_iterator pair_rep_end() const @@ -215,7 +247,7 @@ class list_device_view { */ template 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 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; + using rep_type = device_storage_type_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) { diff --git a/cpp/include/cudf/lists/lists_column_device_view.cuh b/cpp/include/cudf/lists/lists_column_device_view.cuh index 9ca7ef041a2..943ccbfb2cd 100644 --- a/cpp/include/cudf/lists/lists_column_device_view.cuh +++ b/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 { diff --git a/cpp/include/cudf/lists/lists_column_view.hpp b/cpp/include/cudf/lists/lists_column_view.hpp index d09bc2c935f..6b74a0e600a 100644 --- a/cpp/include/cudf/lists/lists_column_view.hpp +++ b/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,10 +73,12 @@ class lists_column_view : private column_view { using column_view::size; static_assert(std::is_same_v, "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; @@ -69,6 +86,7 @@ class lists_column_view : private column_view { * @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; @@ -76,6 +94,7 @@ class lists_column_view : private column_view { * @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; diff --git a/cpp/include/cudf/structs/structs_column_device_view.cuh b/cpp/include/cudf/structs/structs_column_device_view.cuh index 1e8f644240b..7580582631f 100644 --- a/cpp/include/cudf/structs/structs_column_device_view.cuh +++ b/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 { diff --git a/cpp/include/cudf/structs/structs_column_view.hpp b/cpp/include/cudf/structs/structs_column_view.hpp index ca866d8555e..ffc035b36e3 100644 --- a/cpp/include/cudf/structs/structs_column_view.hpp +++ b/cpp/include/cudf/structs/structs_column_view.hpp @@ -30,19 +30,40 @@ namespace cudf { * @{ */ +/** + * @brief Given a column view of struct type, an instance of this class + * provides a wrapper on this compound column for struct operations. + */ class structs_column_view : public column_view { public: // Foundation members: - structs_column_view(structs_column_view const&) = default; - structs_column_view(structs_column_view&&) = default; + structs_column_view(structs_column_view const&) = default; ///< Copy constructor + structs_column_view(structs_column_view&&) = default; ///< Move constructor ~structs_column_view() = default; + /** + * @brief Copy assignment operator + * + * @return The reference to this structs column + */ structs_column_view& operator=(structs_column_view const&) = default; + /** + * @brief Move assignment operator + * + * @return The reference to this structs column + */ structs_column_view& operator=(structs_column_view&&) = default; - explicit structs_column_view(column_view const& rhs); + /** + * @brief Construct a new structs column view object from a column view. + * + * @param col The column view to wrap + */ + explicit structs_column_view(column_view const& col); /** * @brief Returns the parent column. + * + * @return The parent column */ [[nodiscard]] column_view parent() const; @@ -64,6 +85,9 @@ class structs_column_view : public column_view { * on struct columns should be using `get_sliced_child()` instead of `child()`. * * @throw cudf::logic error if this is an empty column + * + * @param index The index of the child column to return + * @return The child column sliced relative to the parent's offset and size */ [[nodiscard]] column_view get_sliced_child(int index) const; }; // class structs_column_view;