fix doxygen warnings in cudf/io/types.hpp, other header files (#10913)

Fixes parts of #9373
added missing documentation to fix doxygen warnings in multiple files

fixes 93 warnings.

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

Approvers:
  - Vukasin Milovanovic (https://github.com/vuule)
  - Vyas Ramasubramani (https://github.com/vyasr)

URL: #10913

cpp/include/cudf/io/data_sink.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,13 +38,15 @@ class data_sink {
    * @brief Create a sink from a file path
    *
    * @param[in] filepath Path to the file to use
+   * @return Constructed data_sink object
    */
   static std::unique_ptr<data_sink> create(const std::string& filepath);
 
   /**
    * @brief Create a sink from a std::vector
    *
    * @param[in,out] buffer Pointer to the output vector
+   * @return Constructed data_sink object
    */
   static std::unique_ptr<data_sink> create(std::vector<char>* buffer);
 
@@ -54,6 +56,7 @@ class data_sink {
    * A useful code path for benchmarking, to eliminate physical
    * hardware randomness from profiling.
    *
+   * @return Constructed data_sink object
    */
   static std::unique_ptr<data_sink> create();
 
@@ -66,13 +69,15 @@ class data_sink {
    * class that wraps the user pointer.  The principle is to allow the user to declare
    * a custom sink instance and use it across multiple write() calls.
    *
+   * @return Constructed data_sink object
    */
   static std::unique_ptr<data_sink> create(cudf::io::data_sink* const user_sink);
 
   /**
    * @brief Creates a vector of data sinks, one per element in the input vector.
    *
    * @param[in] args vector of parameters
+   * @return Constructed vector of data sinks
    */
   template <typename T>
   static std::vector<std::unique_ptr<data_sink>> create(std::vector<T> const& args)
@@ -91,7 +96,7 @@ class data_sink {
   virtual ~data_sink(){};
 
   /**
-   * @brief Append the buffer content to the sink
+   * @pure @brief Append the buffer content to the sink
    *
    * @param[in] data Pointer to the buffer to be written into the sink object
    * @param[in] size Number of bytes to write
@@ -118,7 +123,7 @@ class data_sink {
    * instead of write() when possible.  However, it is still possible to receive
    * write() calls as well.
    *
-   * @return bool If this writer supports device_write() calls.
+   * @return bool If this writer supports device_write() calls
    */
   [[nodiscard]] virtual bool supports_device_write() const { return false; }
 
@@ -172,6 +177,7 @@ class data_sink {
    * @param gpu_data Pointer to the buffer to be written into the sink object
    * @param size Number of bytes to write
    * @param stream CUDA stream to use
+   * @return a future that can be used to synchronize the call
    */
   virtual std::future<void> device_write_async(void const* gpu_data,
                                                size_t size,
@@ -181,12 +187,12 @@ class data_sink {
   }
 
   /**
-   * @brief Flush the data written into the sink
+   * @pure @brief Flush the data written into the sink
    */
   virtual void flush() = 0;
 
   /**
-   * @brief Returns the total number of bytes written into this sink
+   * @pure @brief Returns the total number of bytes written into this sink
    *
    * @return size_t Total number of bytes written into this sink
    */

cpp/include/cudf/io/datasource.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.
@@ -42,6 +42,8 @@ namespace io {
  */
 class datasource {
  public:
+  template <typename Container>
+  class owning_buffer;  // forward declaration
   /**
    * @brief Interface class for buffers that the datasource returns to the caller.
    *
@@ -50,12 +52,16 @@ class datasource {
   class buffer {
    public:
     /**
-     * @brief Returns the buffer size in bytes.
+     * @pure @brief Returns the buffer size in bytes.
+     *
+     * @return Buffer size in bytes
      */
     [[nodiscard]] virtual size_t size() const = 0;
 
     /**
-     * @brief Returns the address of the data in the buffer.
+     * @pure @brief Returns the address of the data in the buffer.
+     *
+     * @return Address of the data in the buffer
      */
     [[nodiscard]] virtual uint8_t const* data() const = 0;
 
@@ -64,8 +70,18 @@ class datasource {
      */
     virtual ~buffer() {}
 
+    /**
+     * @brief Factory to construct a datasource buffer object from a container.
+     *
+     * @tparam Container Type of the container to construct the buffer from
+     * @param data_owner The container to construct the buffer from (ownership is transferred)
+     * @return Constructed buffer object
+     */
     template <typename Container>
-    static std::unique_ptr<buffer> create(Container&& data_owner);
+    static std::unique_ptr<buffer> create(Container&& data_owner)
+    {
+      return std::make_unique<owning_buffer<Container>>(std::move(data_owner));
+    }
   };
 
   /**
@@ -74,6 +90,7 @@ class datasource {
    * @param[in] filepath Path to the file to use
    * @param[in] offset Bytes from the start of the file (the default is zero)
    * @param[in] size Bytes from the offset; use zero for entire file (the default is zero)
+   * @return Constructed datasource object
    */
   static std::unique_ptr<datasource> create(const std::string& filepath,
                                             size_t offset = 0,
@@ -83,13 +100,15 @@ class datasource {
    * @brief Creates a source from a memory buffer.
    *
    * @param[in] buffer Host buffer object
+   * @return Constructed datasource object
    */
   static std::unique_ptr<datasource> create(host_buffer const& buffer);
 
   /**
    * @brief Creates a source from a from an Arrow file.
    *
    * @param[in] arrow_file RandomAccessFile to which the API calls are forwarded
+   * @return Constructed datasource object
    */
   static std::unique_ptr<datasource> create(
     std::shared_ptr<arrow::io::RandomAccessFile> arrow_file);
@@ -98,13 +117,15 @@ class datasource {
    * @brief Creates a source from an user implemented datasource object.
    *
    * @param[in] source Non-owning pointer to the datasource object
+   * @return Constructed datasource object
    */
   static std::unique_ptr<datasource> create(datasource* source);
 
   /**
    * @brief Creates a vector of datasources, one per element in the input vector.
    *
    * @param[in] args vector of parameters
+   * @return Constructed vector of datasource objects
    */
   template <typename T>
   static std::vector<std::unique_ptr<datasource>> create(std::vector<T> const& args)
@@ -262,10 +283,26 @@ class datasource {
    public:
     non_owning_buffer() {}
 
+    /**
+     * @brief Construct a new non owning buffer object
+     *
+     * @param data The data buffer
+     * @param size The size of the data buffer
+     */
     non_owning_buffer(uint8_t* data, size_t size) : _data(data), _size(size) {}
 
+    /**
+     * @brief Returns the size of the buffer.
+     *
+     * @return The size of the buffer in bytes
+     */
     [[nodiscard]] size_t size() const override { return _size; }
 
+    /**
+     * @brief Returns the pointer to the buffer.
+     *
+     * @return Pointer to the buffer
+     */
     [[nodiscard]] uint8_t const* data() const override { return _data; }
 
    private:
@@ -285,6 +322,8 @@ class datasource {
    public:
     /**
      * @brief Moves the input container into the newly created object.
+     *
+     * @param data_owner The container to construct the buffer from (ownership is transferred)
      */
     owning_buffer(Container&& data_owner)
       : _data(std::move(data_owner)), _data_ptr(_data.data()), _size(_data.size())
@@ -294,14 +333,28 @@ class datasource {
     /**
      * @brief Moves the input container into the newly created object, and exposes a subspan of the
      * buffer.
+     *
+     * @param data_owner The container to construct the buffer from (ownership is transferred)
+     * @param data_ptr Pointer to the start of the subspan
+     * @param size The size of the subspan
      */
     owning_buffer(Container&& data_owner, uint8_t const* data_ptr, size_t size)
       : _data(std::move(data_owner)), _data_ptr(data_ptr), _size(size)
     {
     }
 
+    /**
+     * @brief Returns the size of the buffer.
+     *
+     * @return The size of the buffer in bytes
+     */
     [[nodiscard]] size_t size() const override { return _size; }
 
+    /**
+     * @brief Returns the pointer to the data in the buffer.
+     *
+     * @return Pointer to the data in the buffer
+     */
     [[nodiscard]] uint8_t const* data() const override
     {
       return static_cast<uint8_t const*>(_data_ptr);
@@ -314,12 +367,6 @@ class datasource {
   };
 };
 
-template <typename Container>
-std::unique_ptr<datasource::buffer> datasource::buffer::create(Container&& data_owner)
-{
-  return std::make_unique<owning_buffer<Container>>(std::move(data_owner));
-}
-
 /**
  * @brief Implementation class for reading from an Apache Arrow file. The file
  * could be a memory-mapped file or other implementation supported by Arrow.
@@ -378,6 +425,10 @@ class arrow_io_source : public datasource {
 
   /**
    * @brief Returns a buffer with a subset of data from the `arrow` source.
+   *
+   * @param offset The offset in bytes from which to read
+   * @param size The number of bytes to read
+   * @return A buffer with the read data
    */
   std::unique_ptr<buffer> host_read(size_t offset, size_t size) override
   {
@@ -388,6 +439,11 @@ class arrow_io_source : public datasource {
 
   /**
    * @brief Reads a selected range from the `arrow` source into a preallocated buffer.
+   *
+   * @param[in] offset The offset in bytes from which to read
+   * @param[in] size The number of bytes to read
+   * @param[out] dst The preallocated buffer to read into
+   * @return The number of bytes read
    */
   size_t host_read(size_t offset, size_t size, uint8_t* dst) override
   {
@@ -398,6 +454,8 @@ class arrow_io_source : public datasource {
 
   /**
    * @brief Returns the size of the data in the `arrow` source.
+   *
+   * @return The size of the data in the `arrow` source
    */
   [[nodiscard]] size_t size() const override
   {

cpp/include/cudf/io/text/byte_range_info.hpp

@@ -30,21 +30,48 @@ namespace text {
  */
 class byte_range_info {
  private:
-  int64_t _offset;
-  int64_t _size;
+  int64_t _offset;  ///< offset in bytes
+  int64_t _size;    ///< size in bytes
 
  public:
   constexpr byte_range_info() noexcept : _offset(0), _size(0) {}
+  /**
+   * @brief Constructs a byte_range_info object
+   *
+   * @param offset offset in bytes
+   * @param size size in bytes
+   */
   constexpr byte_range_info(int64_t offset, int64_t size) : _offset(offset), _size(size)
   {
     CUDF_EXPECTS(offset >= 0, "offset must be non-negative");
     CUDF_EXPECTS(size >= 0, "size must be non-negative");
   }
 
+  /**
+   * @brief Copy constructor
+   *
+   * @param other byte_range_info object to copy
+   */
   constexpr byte_range_info(byte_range_info const& other) noexcept = default;
+  /**
+   * @brief  Copy assignment operator
+   *
+   * @param other byte_range_info object to copy
+   * @return this object after copying
+   */
   constexpr byte_range_info& operator=(byte_range_info const& other) noexcept = default;
 
+  /**
+   * @brief Get the offset in bytes
+   *
+   * @return Offset in bytes
+   */
   [[nodiscard]] constexpr int64_t offset() { return _offset; }
+  /**
+   * @brief Get the size in bytes
+   *
+   * @return Size in bytes
+   */
   [[nodiscard]] constexpr int64_t size() { return _size; }
 };