From 0e2e79d0df0ec82f390bae491fe45832ea14f623 Mon Sep 17 00:00:00 2001 From: Karthikeyan <6488848+karthikeyann@users.noreply.github.com> Date: Wed, 1 Jun 2022 14:49:28 +0530 Subject: [PATCH] Fix doxygen warnings in ast/, rolling, tdigest/, wrappers/, dictionary/ headers (#10921) Fixes parts of https://github.com/rapidsai/cudf/issues/9373 added missing documentation to fix doxygen warnings in multiple files ast/, rolling, tdigest/, wrappers, dictionary/ headers fixes 82 warnings. Authors: - Karthikeyan (https://github.com/karthikeyann) Approvers: - Conor Hoekstra (https://github.com/codereport) - Vyas Ramasubramani (https://github.com/vyasr) URL: https://github.com/rapidsai/cudf/pull/10921 --- cpp/include/cudf/ast/expressions.hpp | 72 +++++++---- .../dictionary/dictionary_column_view.hpp | 41 ++++++- .../cudf/rolling/range_window_bounds.hpp | 10 +- .../cudf/tdigest/tdigest_column_view.cuh | 58 +++++++-- cpp/include/cudf/wrappers/dictionary.hpp | 114 ++++++++++++++++-- cpp/include/cudf/wrappers/timestamps.hpp | 7 +- 6 files changed, 243 insertions(+), 59 deletions(-) diff --git a/cpp/include/cudf/ast/expressions.hpp b/cpp/include/cudf/ast/expressions.hpp index 96c99e054a5..d29b0787e8e 100644 --- a/cpp/include/cudf/ast/expressions.hpp +++ b/cpp/include/cudf/ast/expressions.hpp @@ -38,13 +38,34 @@ class expression_parser; * Expressions inheriting from this class can accept parsers as visitors. */ struct expression { + /** + * @brief Accepts a visitor class. + * + * @param visitor The `expression_parser` parsing this expression tree + * @return Index of device data reference for this instance + */ virtual cudf::size_type accept(detail::expression_parser& visitor) const = 0; + /** + * @brief Returns true if the expression may evaluate to null. + * + * @param left The left operand of the expression (The same is used as right operand) + * @param stream CUDA stream used for device memory operations and kernel launches + * @return `true` if the expression may evaluate to null, otherwise false + */ [[nodiscard]] bool may_evaluate_null(table_view const& left, rmm::cuda_stream_view stream) const { return may_evaluate_null(left, left, stream); } + /** + * @brief Returns true if the expression may evaluate to null. + * + * @param left The left operand of the expression + * @param right The right operand of the expression + * @param stream CUDA stream used for device memory operations and kernel launches + * @return `true` if the expression may evaluate to null, otherwise false + */ [[nodiscard]] virtual bool may_evaluate_null(table_view const& left, table_view const& right, rmm::cuda_stream_view stream) const = 0; @@ -137,8 +158,8 @@ class literal : public expression { /** * @brief Construct a new literal object. * - * @tparam T Numeric scalar template type. - * @param value A numeric scalar value. + * @tparam T Numeric scalar template type + * @param value A numeric scalar value */ template literal(cudf::numeric_scalar& value) @@ -149,8 +170,8 @@ class literal : public expression { /** * @brief Construct a new literal object. * - * @tparam T Timestamp scalar template type. - * @param value A timestamp scalar value. + * @tparam T Timestamp scalar template type + * @param value A timestamp scalar value */ template literal(cudf::timestamp_scalar& value) @@ -161,8 +182,8 @@ class literal : public expression { /** * @brief Construct a new literal object. * - * @tparam T Duration scalar template type. - * @param value A duration scalar value. + * @tparam T Duration scalar template type + * @param value A duration scalar value */ template literal(cudf::duration_scalar& value) @@ -173,14 +194,14 @@ class literal : public expression { /** * @brief Get the data type. * - * @return cudf::data_type + * @return The data type of the literal */ [[nodiscard]] cudf::data_type get_data_type() const { return get_value().type(); } /** * @brief Get the value object. * - * @return cudf::detail::fixed_width_scalar_device_view_base + * @return The device scalar object */ [[nodiscard]] cudf::detail::fixed_width_scalar_device_view_base get_value() const { @@ -190,8 +211,8 @@ class literal : public expression { /** * @brief Accepts a visitor class. * - * @param visitor Visitor. - * @return cudf::size_type Index of device data reference for this instance. + * @param visitor The `expression_parser` parsing this expression tree + * @return Index of device data reference for this instance */ cudf::size_type accept(detail::expression_parser& visitor) const override; @@ -205,7 +226,8 @@ class literal : public expression { /** * @brief Check if the underlying scalar is valid. * - * @return bool + * @param stream CUDA stream used for device memory operations and kernel launches + * @return true if the underlying scalar is valid */ [[nodiscard]] bool is_valid(rmm::cuda_stream_view stream) const { @@ -227,7 +249,7 @@ class column_reference : public expression { * * @param column_index Index of this column in the table (provided when the expression is * evaluated). - * @param table_source Which table to use in cases with two tables (e.g. joins). + * @param table_source Which table to use in cases with two tables (e.g. joins) */ column_reference(cudf::size_type column_index, table_reference table_source = table_reference::LEFT) @@ -238,22 +260,22 @@ class column_reference : public expression { /** * @brief Get the column index. * - * @return cudf::size_type + * @return The column index of the column reference */ [[nodiscard]] cudf::size_type get_column_index() const { return column_index; } /** * @brief Get the table source. * - * @return table_reference + * @return table_reference The reference to the table containing this column */ [[nodiscard]] table_reference get_table_source() const { return table_source; } /** * @brief Get the data type. * - * @param table Table used to determine types. - * @return cudf::data_type + * @param table Table used to determine types + * @return The data type of the column */ [[nodiscard]] cudf::data_type get_data_type(table_view const& table) const { @@ -263,9 +285,9 @@ class column_reference : public expression { /** * @brief Get the data type. * - * @param left_table Left table used to determine types. - * @param right_table Right table used to determine types. - * @return cudf::data_type + * @param left_table Left table used to determine types + * @param right_table Right table used to determine types + * @return The data type of the column */ [[nodiscard]] cudf::data_type get_data_type(table_view const& left_table, table_view const& right_table) const @@ -285,8 +307,8 @@ class column_reference : public expression { /** * @brief Accepts a visitor class. * - * @param visitor Visitor. - * @return cudf::size_type Index of device data reference for this instance. + * @param visitor The `expression_parser` parsing this expression tree + * @return Index of device data reference for this instance */ cudf::size_type accept(detail::expression_parser& visitor) const override; @@ -334,22 +356,22 @@ class operation : public expression { /** * @brief Get the operator. * - * @return ast_operator + * @return The operator */ [[nodiscard]] ast_operator get_operator() const { return op; } /** * @brief Get the operands. * - * @return std::vector> + * @return Vector of operands */ std::vector> get_operands() const { return operands; } /** * @brief Accepts a visitor class. * - * @param visitor Visitor. - * @return cudf::size_type Index of device data reference for this instance. + * @param visitor The `expression_parser` parsing this expression tree + * @return Index of device data reference for this instance */ cudf::size_type accept(detail::expression_parser& visitor) const override; diff --git a/cpp/include/cudf/dictionary/dictionary_column_view.hpp b/cpp/include/cudf/dictionary/dictionary_column_view.hpp index 33e29e70304..9f2bc90c0b2 100644 --- a/cpp/include/cudf/dictionary/dictionary_column_view.hpp +++ b/cpp/include/cudf/dictionary/dictionary_column_view.hpp @@ -1,5 +1,5 @@ /* - * Copyright (c) 2020, 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. @@ -39,14 +39,33 @@ namespace cudf { */ class dictionary_column_view : private column_view { public: + /** + * @brief Construct a new dictionary column view object from a column view. + * + * @param dictionary_column The column view to wrap + */ dictionary_column_view(column_view const& dictionary_column); - dictionary_column_view(dictionary_column_view&& dictionary_view) = default; - dictionary_column_view(const dictionary_column_view& dictionary_view) = default; - ~dictionary_column_view() = default; + dictionary_column_view(dictionary_column_view&&) = default; ///< Move constructor + dictionary_column_view(dictionary_column_view const&) = default; ///< Copy constructor + ~dictionary_column_view() = default; + + /** + * @brief Move assignment operator + * + * @return The reference to this dictionary column + */ dictionary_column_view& operator=(dictionary_column_view const&) = default; + + /** + * @brief Copy assignment operator + * + * @return The reference to this dictionary column + */ dictionary_column_view& operator=(dictionary_column_view&&) = default; + /// Index of the indices column of the dictionary column static constexpr size_type indices_column_index{0}; + /// Index of the keys column of the dictionary column static constexpr size_type keys_column_index{1}; using column_view::has_nulls; @@ -58,32 +77,44 @@ class dictionary_column_view : private column_view { /** * @brief Returns the parent column. + * + * @return The parent column */ [[nodiscard]] column_view parent() const noexcept; /** * @brief Returns the column of indices + * + * @return The indices column */ [[nodiscard]] column_view indices() const noexcept; /** * @brief Returns a column_view combining the indices data * with offset, size, and nulls from the parent. + * + * @return A sliced indices column view with nulls from the parent */ [[nodiscard]] column_view get_indices_annotated() const noexcept; /** * @brief Returns the column of keys + * + * @return The keys column */ [[nodiscard]] column_view keys() const noexcept; /** - * @brief Returns the `data_type` of the keys child column. + * @brief Returns the cudf::data_type of the keys child column. + * + * @return The cudf::data_type of the keys child column */ [[nodiscard]] data_type keys_type() const noexcept; /** * @brief Returns the number of rows in the keys column. + * + * @return The number of rows in the keys column */ [[nodiscard]] size_type keys_size() const noexcept; }; diff --git a/cpp/include/cudf/rolling/range_window_bounds.hpp b/cpp/include/cudf/rolling/range_window_bounds.hpp index 4d31bb98f9c..ecb485581a5 100644 --- a/cpp/include/cudf/rolling/range_window_bounds.hpp +++ b/cpp/include/cudf/rolling/range_window_bounds.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. @@ -39,7 +39,7 @@ struct range_window_bounds { * @brief Factory method to construct a bounded window boundary. * * @param boundary Finite window boundary - * + * @return A bounded window boundary object */ static range_window_bounds get(scalar const& boundary); @@ -47,6 +47,7 @@ struct range_window_bounds { * @brief Factory method to construct an unbounded window boundary. * * @param type type The datatype of the window boundary + * @return An unbounded window boundary object */ static range_window_bounds unbounded(data_type type); @@ -60,11 +61,12 @@ struct range_window_bounds { /** * @brief Returns the underlying scalar value for the bounds + * + * @return The underlying scalar value for the bounds */ [[nodiscard]] scalar const& range_scalar() const { return *_range_scalar; } - range_window_bounds(range_window_bounds const&) = - default; // Required to return (by copy) from functions. + range_window_bounds(range_window_bounds const&) = default; ///< Copy constructor range_window_bounds() = default; // Required for use as return types from dispatch functors. private: diff --git a/cpp/include/cudf/tdigest/tdigest_column_view.cuh b/cpp/include/cudf/tdigest/tdigest_column_view.cuh index 696657191ca..64371fd5c45 100644 --- a/cpp/include/cudf/tdigest/tdigest_column_view.cuh +++ b/cpp/include/cudf/tdigest/tdigest_column_view.cuh @@ -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. @@ -22,8 +22,18 @@ namespace cudf { namespace tdigest { +/** + * @brief Functor to compute the size of each tdigest of a column. + * + */ struct tdigest_size { - size_type const* offsets; + size_type const* offsets; ///< Offsets of the t-digest column + /** + * @brief Returns size of the each tdigest in the column + * + * @param tdigest_index Index of the tdigest in the column + * @return Size of the tdigest + */ __device__ size_type operator()(size_type tdigest_index) { return offsets[tdigest_index + 1] - offsets[tdigest_index]; @@ -58,50 +68,70 @@ struct tdigest_size { */ class tdigest_column_view : private column_view { public: - tdigest_column_view(column_view const& col); - tdigest_column_view(tdigest_column_view&& tdigest_view) = default; - tdigest_column_view(const tdigest_column_view& tdigest_view) = default; - ~tdigest_column_view() = default; + tdigest_column_view(column_view const&); ///< Construct tdigest_column_view from a column_view + tdigest_column_view(tdigest_column_view&&) = default; ///< Move constructor + tdigest_column_view(const tdigest_column_view&) = default; ///< Copy constructor + ~tdigest_column_view() = default; + /** + * @brief Copy assignment operator + * + * @return this object after copying the contents of the other object (copy) + */ tdigest_column_view& operator=(tdigest_column_view const&) = default; + /** + * @brief Move assignment operator + * + * @return this object after moving the contents of the other object (transfer ownership) + */ tdigest_column_view& operator=(tdigest_column_view&&) = default; 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 over offsets // mean and weight column indices within tdigest inner struct columns - static constexpr size_type mean_column_index{0}; - static constexpr size_type weight_column_index{1}; + static constexpr size_type mean_column_index{0}; ///< Mean column index + static constexpr size_type weight_column_index{1}; ///< Weight column index // min and max column indices within tdigest outer struct columns - static constexpr size_type centroid_column_index{0}; - static constexpr size_type min_column_index{1}; - static constexpr size_type max_column_index{2}; + static constexpr size_type centroid_column_index{0}; ///< Centroid column index + static constexpr size_type min_column_index{1}; ///< Min column index + static constexpr size_type max_column_index{2}; ///< Max column index /** * @brief Returns the parent column. + * + * @return The parent column */ [[nodiscard]] column_view parent() const; /** * @brief Returns the column of centroids + * + * @return The list column of centroids */ [[nodiscard]] lists_column_view centroids() const; /** * @brief Returns the internal column of mean values + * + * @return The internal column of mean values */ [[nodiscard]] column_view means() const; /** * @brief Returns the internal column of weight values + * + * @return The internal column of weight values */ [[nodiscard]] column_view weights() const; /** * @brief Returns an iterator that returns the size of each tdigest * in the column (each row is 1 digest) + * + * @return An iterator that returns the size of each tdigest in the column */ [[nodiscard]] auto size_begin() const { @@ -112,12 +142,16 @@ class tdigest_column_view : private column_view { /** * @brief Returns the first min value for the column. Each row corresponds * to the minimum value for the accompanying digest. + * + * @return const pointer to the first min value for the column */ [[nodiscard]] double const* min_begin() const; /** * @brief Returns the first max value for the column. Each row corresponds * to the maximum value for the accompanying digest. + * + * @return const pointer to the first max value for the column */ [[nodiscard]] double const* max_begin() const; }; diff --git a/cpp/include/cudf/wrappers/dictionary.hpp b/cpp/include/cudf/wrappers/dictionary.hpp index 9f1c1534e9a..75df1fd6abb 100644 --- a/cpp/include/cudf/wrappers/dictionary.hpp +++ b/cpp/include/cudf/wrappers/dictionary.hpp @@ -1,5 +1,5 @@ /* - * Copyright (c) 2020, 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. @@ -46,34 +46,76 @@ namespace cudf { */ template struct dictionary_wrapper { - using value_type = IndexType; - - dictionary_wrapper() = default; - ~dictionary_wrapper() = default; - dictionary_wrapper(dictionary_wrapper&&) = default; - dictionary_wrapper(dictionary_wrapper const& v) = default; + using value_type = IndexType; ///< The underlying type of the dictionary + + dictionary_wrapper() = default; + ~dictionary_wrapper() = default; + dictionary_wrapper(dictionary_wrapper&&) = default; ///< Move constructor + dictionary_wrapper(dictionary_wrapper const&) = default; ///< Copy constructor + + /** + * @brief Move assignment operator + * + * @return The reference to this dictionary wrapper object + */ dictionary_wrapper& operator=(dictionary_wrapper&&) = default; + + /** + * @brief Copy assignment operator + * + * @return The reference to this dictionary wrapper object + */ dictionary_wrapper& operator=(const dictionary_wrapper&) = default; - // construct object from type + /** + * @brief Construct dictionary_wrapper from a value + * + * @param v The value to construct the dictionary_wrapper from + */ CUDF_HOST_DEVICE inline constexpr explicit dictionary_wrapper(value_type v) : _value{v} {} - // conversion operator + /** + * @brief Conversion operator + * + * @return The value of this dictionary wrapper + */ CUDF_HOST_DEVICE inline explicit operator value_type() const { return _value; } - // simple accessor + + /** + * @brief Simple accessor + * + * @return The value of this dictionary wrapper + */ CUDF_HOST_DEVICE inline value_type value() const { return _value; } + /** + * @brief Returns the maximum value of the value type. + * + * @return The maximum value of the value type + */ static CUDF_HOST_DEVICE inline constexpr value_type max_value() { return std::numeric_limits::max(); } + + /** + * @brief Returns the minimum value of the value type. + * + * @return The minimum value of the value type + */ static CUDF_HOST_DEVICE inline constexpr value_type min_value() { return std::numeric_limits::min(); } + + /** + * @brief Returns the lowest value of the value type. + * + * @return The lowest value of the value type + */ static CUDF_HOST_DEVICE inline constexpr value_type lowest_value() { - return std::numeric_limits::lowest(); + return std::numeric_limits::lowest(); } private: @@ -81,6 +123,14 @@ struct dictionary_wrapper { }; // comparison operators +/** + * @brief Wqual to operator for dictionary_wrapper + * + * @tparam Integer Index type + * @param lhs Left hand side of comparison + * @param rhs Right hand side of comparison + * @return Returns true if lhs is equal to rhs, false otherwise + */ template CUDF_HOST_DEVICE inline bool operator==(dictionary_wrapper const& lhs, dictionary_wrapper const& rhs) @@ -88,6 +138,14 @@ CUDF_HOST_DEVICE inline bool operator==(dictionary_wrapper const& lhs, return lhs.value() == rhs.value(); } +/** + * @brief Not equal to operator for dictionary_wrapper + * + * @tparam Integer Index type + * @param lhs Left hand side of comparison + * @param rhs Right hand side of comparison + * @return Returns true if lhs is not equal to rhs, false otherwise + */ template CUDF_HOST_DEVICE inline bool operator!=(dictionary_wrapper const& lhs, dictionary_wrapper const& rhs) @@ -95,6 +153,14 @@ CUDF_HOST_DEVICE inline bool operator!=(dictionary_wrapper const& lhs, return lhs.value() != rhs.value(); } +/** + * @brief Less than or equal to operator for dictionary_wrapper + * + * @tparam Integer Index type + * @param lhs Left hand side of comparison + * @param rhs Right hand side of comparison + * @return Returns true if lhs is less than or equal to rhs, false otherwise + */ template CUDF_HOST_DEVICE inline bool operator<=(dictionary_wrapper const& lhs, dictionary_wrapper const& rhs) @@ -102,6 +168,14 @@ CUDF_HOST_DEVICE inline bool operator<=(dictionary_wrapper const& lhs, return lhs.value() <= rhs.value(); } +/** + * @brief Greater than or equal to operator for dictionary_wrapper + * + * @tparam Integer Index type + * @param lhs Left hand side of comparison + * @param rhs Right hand side of comparison + * @return Returns true if lhs is greater than or equal to rhs, false otherwise + */ template CUDF_HOST_DEVICE inline bool operator>=(dictionary_wrapper const& lhs, dictionary_wrapper const& rhs) @@ -109,6 +183,14 @@ CUDF_HOST_DEVICE inline bool operator>=(dictionary_wrapper const& lhs, return lhs.value() >= rhs.value(); } +/** + * @brief Less than operator for dictionary_wrapper + * + * @tparam Integer Index type + * @param lhs Left hand side of comparison + * @param rhs Right hand side of comparison + * @return Returns true if lhs is less than rhs, false otherwise + */ template CUDF_HOST_DEVICE inline constexpr bool operator<(dictionary_wrapper const& lhs, dictionary_wrapper const& rhs) @@ -116,6 +198,14 @@ CUDF_HOST_DEVICE inline constexpr bool operator<(dictionary_wrapper con return lhs.value() < rhs.value(); } +/** + * @brief Greater than operator for dictionary_wrapper + * + * @tparam Integer Index type + * @param lhs Left hand side of comparison + * @param rhs Right hand side of comparison + * @return Returns true if lhs is greater than rhs, false otherwise + */ template CUDF_HOST_DEVICE inline bool operator>(dictionary_wrapper const& lhs, dictionary_wrapper const& rhs) @@ -123,7 +213,7 @@ CUDF_HOST_DEVICE inline bool operator>(dictionary_wrapper const& lhs, return lhs.value() > rhs.value(); } -using dictionary32 = dictionary_wrapper; +using dictionary32 = dictionary_wrapper; ///< 32-bit integer indexed dictionary wrapper /** @} */ // end of group } // namespace cudf diff --git a/cpp/include/cudf/wrappers/timestamps.hpp b/cpp/include/cudf/wrappers/timestamps.hpp index 5a4424112de..0341ac6ede4 100644 --- a/cpp/include/cudf/wrappers/timestamps.hpp +++ b/cpp/include/cudf/wrappers/timestamps.hpp @@ -27,8 +27,13 @@ namespace cudf { namespace detail { // TODO: Use chrono::utc_clock when available in libcu++? template -using time_point = cuda::std::chrono::sys_time; +using time_point = cuda::std::chrono::sys_time; ///< Time point type +/** + * @brief A wrapper around a column of time_point in varying resolutions + * + * @tparam Duration The underlying duration type + */ template using timestamp = time_point; } // namespace detail