Fix Doxygen warnings in strings / header files (#10937)

Fixes parts of #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: #10937

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);
 

cpp/include/cudf/strings/detail/convert/fixed_point.cuh

@@ -122,7 +122,7 @@ __device__ thrust::optional<int32_t> 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

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.

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
   {

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
 {

cpp/include/cudf/strings/string_view.hpp

@@ -50,26 +50,35 @@ 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; }
 
   /**
    * @brief Handy iterator for navigating through encoded characters.
    */
   class const_iterator {
+    /// @cond
    public:
     using difference_type   = ptrdiff_t;
     using value_type        = char_utf8;
@@ -104,27 +113,34 @@ 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;
 
   /**
    * @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:

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,18 +67,21 @@ 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;
 
   /**
    * @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;