fix doxygen warnings in cudf/io/types.hpp, other header files

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
@@ -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.
@@ -50,12 +50,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,6 +68,13 @@ class datasource {
      */
     virtual ~buffer() {}
 
+    /**
+     * @brief Factory to construct a datasource object from a container.
+     *
+     * @tparam Container Type of the container to construct the datasource from
+     * @param data_owner The container to construct the datasource from (ownership is transferred)
+     * @return Constructed datasource object
+     */
     template <typename Container>
     static std::unique_ptr<buffer> create(Container&& data_owner);
   };
@@ -74,6 +85,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 +95,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 +112,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 +278,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 +317,8 @@ class datasource {
    public:
     /**
      * @brief Moves the input container into the newly created object.
+     *
+     * @param data_owner The container to move
      */
     owning_buffer(Container&& data_owner)
       : _data(std::move(data_owner)), _data_ptr(_data.data()), _size(_data.size())
@@ -294,14 +328,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 move
+     * @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 buffer.
+     *
+     * @return Pointer to the buffer
+     */
     [[nodiscard]] uint8_t const* data() const override
     {
       return static_cast<uint8_t const*>(_data_ptr);
@@ -314,6 +362,13 @@ class datasource {
   };
 };
 
+/**
+ * @brief Factory to construct a datasource object from a container.
+ *
+ * @tparam Container Type of the container to construct the datasource from
+ * @param data_owner The container to construct the datasource from (ownership is transferred)
+ * @return Constructed datasource object
+ */
 template <typename Container>
 std::unique_ptr<datasource::buffer> datasource::buffer::create(Container&& data_owner)
 {
@@ -378,6 +433,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 +447,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 +462,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; }
 };
 

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

@@ -36,9 +36,24 @@ namespace text {
  */
 class device_data_chunk {
  public:
-  virtual ~device_data_chunk()                     = default;
-  [[nodiscard]] virtual char const* data() const   = 0;
-  [[nodiscard]] virtual std::size_t size() const   = 0;
+  virtual ~device_data_chunk() = default;
+  /**
+   * @pure @brief Returns a pointer to the underlying device data.
+   *
+   * @return A pointer to the underlying device data.
+   */
+  [[nodiscard]] virtual char const* data() const = 0;
+  /**
+   * @pure @brief Returns the size of the underlying device data.
+   *
+   * @return The size of the underlying device data.
+   */
+  [[nodiscard]] virtual std::size_t size() const = 0;
+  /**
+   * @pure @brief Returns a span over the underlying device data.
+   *
+   * @return A span over the underlying device data.
+   */
   virtual operator device_span<char const>() const = 0;
 };
 
@@ -53,11 +68,16 @@ class device_data_chunk {
  */
 class data_chunk_reader {
  public:
-  virtual ~data_chunk_reader()              = default;
+  virtual ~data_chunk_reader() = default;
+  /**
+   * @pure @brief Skips the specified number of bytes in the data source.
+   *
+   * @param size The number of bytes to skip
+   */
   virtual void skip_bytes(std::size_t size) = 0;
 
   /**
-   * @brief Get the next chunk of bytes from the data source
+   * @pure @brief Get the next chunk of bytes from the data source
    *
    * Performs any necessary work to read and prepare the underlying data source for consumption as a
    * view over device memory. Common implementations may read from a file, copy data from host
@@ -80,7 +100,13 @@ class data_chunk_reader {
  */
 class data_chunk_source {
  public:
-  virtual ~data_chunk_source()                                                   = default;
+  virtual ~data_chunk_source() = default;
+
+  /**
+   * @pure @brief Get a reader for the data source.
+   *
+   * @return `data_chunk_reader` object for the data source.
+   */
   [[nodiscard]] virtual std::unique_ptr<data_chunk_reader> create_reader() const = 0;
 };