From 75f667e37eae43a4838b9b2cedcfcec59af7ff09 Mon Sep 17 00:00:00 2001 From: Karthikeyan <6488848+karthikeyann@users.noreply.github.com> Date: Thu, 2 Jun 2022 06:37:55 +0530 Subject: [PATCH] Fix Doxygen warnings in strings / header files (#10937) Fixes parts of https://github.com/rapidsai/cudf/issues/9373 added missing documentation to fix doxygen warnings in multiple files ignored docs for `cudf::string_view::const_iterator` fixes 78 warnings. Authors: - Karthikeyan (https://github.com/karthikeyann) Approvers: - Conor Hoekstra (https://github.com/codereport) - David Wendt (https://github.com/davidwendt) URL: https://github.com/rapidsai/cudf/pull/10937 --- .../cudf/strings/char_types/char_types.hpp | 10 +++- .../strings/detail/convert/fixed_point.cuh | 2 +- cpp/include/cudf/strings/detail/utilities.cuh | 10 ++-- cpp/include/cudf/strings/json.hpp | 6 ++- cpp/include/cudf/strings/string_view.cuh | 2 + cpp/include/cudf/strings/string_view.hpp | 48 ++++++++++++++++++- .../cudf/strings/strings_column_view.hpp | 37 ++++++++++---- 7 files changed, 96 insertions(+), 19 deletions(-) diff --git a/cpp/include/cudf/strings/char_types/char_types.hpp b/cpp/include/cudf/strings/char_types/char_types.hpp index 04d65065bd3..a5a90f74c21 100644 --- a/cpp/include/cudf/strings/char_types/char_types.hpp +++ b/cpp/include/cudf/strings/char_types/char_types.hpp @@ -1,5 +1,5 @@ /* - * Copyright (c) 2019-2021, NVIDIA CORPORATION. + * Copyright (c) 2019-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. @@ -51,11 +51,19 @@ enum string_character_types : uint32_t { /** * @brief OR operator for combining string_character_types + * + * @param lhs left-hand side of OR operation + * @param rhs right-hand side of OR operation + * @return combined string_character_types */ string_character_types operator|(string_character_types lhs, string_character_types rhs); /** * @brief Compound assignment OR operator for combining string_character_types + * + * @param lhs left-hand side of OR operation + * @param rhs right-hand side of OR operation + * @return Reference to `lhs` after combining `lhs` and `rhs` */ string_character_types& operator|=(string_character_types& lhs, string_character_types rhs); diff --git a/cpp/include/cudf/strings/detail/convert/fixed_point.cuh b/cpp/include/cudf/strings/detail/convert/fixed_point.cuh index 075f1d07a80..185754a00c8 100644 --- a/cpp/include/cudf/strings/detail/convert/fixed_point.cuh +++ b/cpp/include/cudf/strings/detail/convert/fixed_point.cuh @@ -122,7 +122,7 @@ __device__ thrust::optional parse_exponent(char const* iter, char const * @brief Converts the string in the range [iter, iter_end) into a decimal. * * @tparam DecimalType The decimal type to be returned - * @param iter The beginning of the string. Unless iter >= iter_end, iter is dereferenced + * @param iter The beginning of the string * @param iter_end The end of the characters to parse * @param scale The scale to be applied * @return diff --git a/cpp/include/cudf/strings/detail/utilities.cuh b/cpp/include/cudf/strings/detail/utilities.cuh index e6dba5147b5..76a0ce721c0 100644 --- a/cpp/include/cudf/strings/detail/utilities.cuh +++ b/cpp/include/cudf/strings/detail/utilities.cuh @@ -107,9 +107,8 @@ __device__ inline char* copy_string(char* buffer, const string_view& d_string) * It must also have members d_offsets and d_chars which are set to * memory containing the offsets and chars columns during write. * - * @param size_and_exec_fn This is called twice. Once for the output size of each string. - * After that, the d_offsets and d_chars are set and this is called again to fill in the - * chars memory. + * @param size_and_exec_fn This is called twice. Once for the output size of each string + * and once again to fill in the memory pointed to by d_chars. * @param exec_size Number of rows for executing the `size_and_exec_fn` function. * @param strings_count Number of strings. * @param stream CUDA stream used for device memory operations and kernel launches. @@ -167,9 +166,8 @@ auto make_strings_children( * It must also have members d_offsets and d_chars which are set to * memory containing the offsets and chars columns during write. * - * @param size_and_exec_fn This is called twice. Once for the output size of each string. - * After that, the d_offsets and d_chars are set and this is called again to fill in the - * chars memory. + * @param size_and_exec_fn This is called twice. Once for the output size of each string + * and once again to fill in the memory pointed to by d_chars. * @param strings_count Number of strings. * @param stream CUDA stream used for device memory operations and kernel launches. * @param mr Device memory resource used to allocate the returned columns' device memory. diff --git a/cpp/include/cudf/strings/json.hpp b/cpp/include/cudf/strings/json.hpp index f6645f2e029..2b66bcb807e 100644 --- a/cpp/include/cudf/strings/json.hpp +++ b/cpp/include/cudf/strings/json.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. @@ -47,6 +47,8 @@ class get_json_object_options { /** * @brief Returns true/false depending on whether single-quotes for representing strings * are allowed. + * + * @return true if single-quotes are allowed, false otherwise. */ [[nodiscard]] CUDF_HOST_DEVICE inline bool get_allow_single_quotes() const { @@ -74,6 +76,8 @@ class get_json_object_options { * Output = b * * @endcode + * + * @return true if individually returned string values have their quotes stripped. */ [[nodiscard]] CUDF_HOST_DEVICE inline bool get_strip_quotes_from_single_strings() const { diff --git a/cpp/include/cudf/strings/string_view.cuh b/cpp/include/cudf/strings/string_view.cuh index a486a5a765c..57d082cf11c 100644 --- a/cpp/include/cudf/strings/string_view.cuh +++ b/cpp/include/cudf/strings/string_view.cuh @@ -112,6 +112,7 @@ __device__ inline size_type string_view::length() const return _length; } +// @cond // this custom iterator knows about UTF8 encoding __device__ inline string_view::const_iterator::const_iterator(const string_view& str, size_type pos) : p{str.data()}, bytes{str.size_bytes()}, char_pos{pos}, byte_pos{str.byte_offset(pos)} @@ -243,6 +244,7 @@ __device__ inline string_view::const_iterator string_view::end() const { return const_iterator(*this, length()); } +// @endcond __device__ inline char_utf8 string_view::operator[](size_type pos) const { diff --git a/cpp/include/cudf/strings/string_view.hpp b/cpp/include/cudf/strings/string_view.hpp index 0c76f7d818d..fbe2253bf25 100644 --- a/cpp/include/cudf/strings/string_view.hpp +++ b/cpp/include/cudf/strings/string_view.hpp @@ -50,19 +50,27 @@ class string_view { public: /** * @brief Return the number of bytes in this string + * + * @return The number of bytes in this string */ CUDF_HOST_DEVICE [[nodiscard]] inline size_type size_bytes() const { return _bytes; } /** * @brief Return the number of characters in this string + * + * @return The number of characters in this string */ __device__ [[nodiscard]] inline size_type length() const; /** * @brief Return a pointer to the internal device array + * + * @return A pointer to the internal device array */ CUDF_HOST_DEVICE [[nodiscard]] inline const char* data() const { return _data; } /** * @brief Return true if string has no characters + * + * @return true if string has no characters */ CUDF_HOST_DEVICE [[nodiscard]] inline bool empty() const { return size_bytes() == 0; } @@ -70,6 +78,7 @@ class string_view { * @brief Handy iterator for navigating through encoded characters. */ class const_iterator { + /// @cond public: using difference_type = ptrdiff_t; using value_type = char_utf8; @@ -104,14 +113,19 @@ class string_view { size_type bytes{}; size_type char_pos{}; size_type byte_pos{}; + /// @endcond }; /** * @brief Return new iterator pointing to the beginning of this string + * + * @return new iterator pointing to the beginning of this string */ __device__ [[nodiscard]] inline const_iterator begin() const; /** * @brief Return new iterator pointing past the end of this string + * + * @return new iterator pointing past the end of this string */ __device__ [[nodiscard]] inline const_iterator end() const; @@ -119,12 +133,14 @@ class string_view { * @brief Return single UTF-8 character at the given character position * * @param pos Character position + * @return UTF-8 character at the given character position */ __device__ inline char_utf8 operator[](size_type pos) const; /** * @brief Return the byte offset from data() for a given character position * * @param pos Character position + * @return Byte offset from data() for a given character position */ __device__ [[nodiscard]] inline size_type byte_offset(size_type pos) const; @@ -160,26 +176,44 @@ class string_view { /** * @brief Returns true if rhs matches this string exactly. + * + * @param rhs Target string to compare with this string. + * @return true if rhs matches this string exactly */ __device__ inline bool operator==(const string_view& rhs) const; /** * @brief Returns true if rhs does not match this string. + * + * @param rhs Target string to compare with this string. + * @return true if rhs does not match this string */ __device__ inline bool operator!=(const string_view& rhs) const; /** * @brief Returns true if this string is ordered before rhs. + * + * @param rhs Target string to compare with this string. + * @return true if this string is ordered before rhs */ __device__ inline bool operator<(const string_view& rhs) const; /** * @brief Returns true if rhs is ordered before this string. + * + * @param rhs Target string to compare with this string. + * @return true if rhs is ordered before this string */ __device__ inline bool operator>(const string_view& rhs) const; /** * @brief Returns true if this string matches or is ordered before rhs. + * + * @param rhs Target string to compare with this string. + * @return true if this string matches or is ordered before rhs */ __device__ inline bool operator<=(const string_view& rhs) const; /** * @brief Returns true if rhs matches or is ordered before this string. + * + * @param rhs Target string to compare with this string. + * @return true if rhs matches or is ordered before this string */ __device__ inline bool operator>=(const string_view& rhs) const; @@ -313,10 +347,20 @@ class string_view { { } - string_view(const string_view&) = default; - string_view(string_view&&) = default; + string_view(const string_view&) = default; ///< Copy constructor + string_view(string_view&&) = default; ///< Move constructor ~string_view() = default; + /** + * @brief Copy assignment operator + * + * @return Reference to this instance + */ string_view& operator=(const string_view&) = default; + /** + * @brief Move assignment operator + * + * @return Reference to this instance (after transferring ownership) + */ string_view& operator=(string_view&&) = default; private: diff --git a/cpp/include/cudf/strings/strings_column_view.hpp b/cpp/include/cudf/strings/strings_column_view.hpp index aab898932de..e617dbde024 100644 --- a/cpp/include/cudf/strings/strings_column_view.hpp +++ b/cpp/include/cudf/strings/strings_column_view.hpp @@ -1,5 +1,5 @@ /* - * Copyright (c) 2019-2021, NVIDIA CORPORATION. + * Copyright (c) 2019-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. @@ -35,15 +35,30 @@ namespace cudf { */ class strings_column_view : private column_view { public: + /** + * @brief Construct a new strings column view object from a column view.s + * + * @param strings_column The column view to wrap. + */ strings_column_view(column_view strings_column); - strings_column_view(strings_column_view&& strings_view) = default; - strings_column_view(const strings_column_view& strings_view) = default; - ~strings_column_view() = default; + strings_column_view(strings_column_view&&) = default; ///< Move constructor + strings_column_view(strings_column_view const&) = default; ///< Copy constructor + ~strings_column_view() = default; + /** + * @brief Copy assignment operator + * + * @return Reference to this instance + */ strings_column_view& operator=(strings_column_view const&) = default; + /** + * @brief Move assignment operator + * + * @return Reference to this instance (after transferring ownership) + */ strings_column_view& operator=(strings_column_view&&) = default; - static constexpr size_type offsets_column_index{0}; - static constexpr size_type chars_column_index{1}; + static constexpr size_type offsets_column_index{0}; ///< Child index of the offsets column + static constexpr size_type chars_column_index{1}; ///< Child index of the characters column using column_view::has_nulls; using column_view::is_empty; @@ -52,11 +67,13 @@ class strings_column_view : private column_view { using column_view::offset; using column_view::size; - using offset_iterator = offset_type const*; - using chars_iterator = char const*; + using offset_iterator = offset_type const*; ///< offsets iterator type + using chars_iterator = char const*; ///< character iterator type /** * @brief Returns the parent column. + * + * @return The parents column */ [[nodiscard]] column_view parent() const; @@ -64,6 +81,7 @@ class strings_column_view : private column_view { * @brief Returns the internal column of offsets * * @throw cudf::logic error if this is an empty column + * @return The offsets column */ [[nodiscard]] column_view offsets() const; @@ -89,6 +107,7 @@ class strings_column_view : private column_view { * @brief Returns the internal column of chars * * @throw cudf::logic error if this is an empty column + * @return The chars column */ [[nodiscard]] column_view chars() const; @@ -97,6 +116,8 @@ class strings_column_view : private column_view { * * This accounts for empty columns but does not reflect a sliced parent column * view (i.e.: non-zero offset or reduced row count). + * + * @return Number of bytes in the chars child column */ [[nodiscard]] size_type chars_size() const noexcept;