Fix doxygen warnings (#1317)

This PR fixes all doxygen warnings from building the C++ documentation.

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

Approvers:
  - Mark Harris (https://github.com/harrism)
  - Rong Ou (https://github.com/rongou)
  - Lawrence Mitchell (https://github.com/wence-)

URL: #1317

doxygen/Doxyfile

@@ -259,7 +259,11 @@ TAB_SIZE               = 4
 # commands \{ and \} for these it is advised to use the version @{ and @} or use
 # a double escape (\\{ and \\})
 
-ALIASES                =
+ALIASES                +=   "briefreturn{1}=@brief \1 @return \1"
+ALIASES                +=   "default_copy_constructor=Default copy constructor"
+ALIASES                +=   "default_move_constructor=Default move constructor"
+ALIASES                +=   "default_copy_assignment{1}=@brief Default copy assignment operator @return \1& Reference to the assigned object"
+ALIASES                +=   "default_move_assignment{1}=@brief Default move assignment operator @return \1& Reference to the assigned object"
 
 # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
 # only. Doxygen will then generate output that is more tailored for C. For
@@ -898,7 +902,7 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       =
+EXCLUDE_PATTERNS       = */detail/*
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the

include/rmm/cuda_device.hpp

@@ -26,16 +26,16 @@ namespace rmm {
  *
  */
 struct cuda_device_id {
-  using value_type = int;
+  using value_type = int;  ///< Integer type used for device identifier
 
   /**
    * @brief Construct a `cuda_device_id` from the specified integer value
    *
-   * @param id The device's integer identifier
+   * @param dev_id The device's integer identifier
    */
   explicit constexpr cuda_device_id(value_type dev_id) noexcept : id_{dev_id} {}
 
-  /// Returns the wrapped integer value
+  /// @briefreturn{The wrapped integer value}
   [[nodiscard]] constexpr value_type value() const noexcept { return id_; }
 
  private:

include/rmm/cuda_stream.hpp

@@ -46,6 +46,8 @@ class cuda_stream {
    *
    * A moved-from cuda_stream is invalid and it is Undefined Behavior to call methods that access
    * the owned stream.
+   *
+   * @return A reference to this cuda_stream
    */
   cuda_stream& operator=(cuda_stream&&) = default;
   ~cuda_stream()                        = default;

include/rmm/cuda_stream_view.hpp

@@ -33,41 +33,47 @@ namespace rmm {
  */
 class cuda_stream_view {
  public:
-  constexpr cuda_stream_view()                                   = default;
-  constexpr cuda_stream_view(cuda_stream_view const&)            = default;
-  constexpr cuda_stream_view(cuda_stream_view&&)                 = default;
-  constexpr cuda_stream_view& operator=(cuda_stream_view const&) = default;
-  constexpr cuda_stream_view& operator=(cuda_stream_view&&)      = default;
-  ~cuda_stream_view()                                            = default;
+  constexpr cuda_stream_view()                        = default;
+  ~cuda_stream_view()                                 = default;
+  constexpr cuda_stream_view(cuda_stream_view const&) = default;  ///< @default_copy_constructor
+  constexpr cuda_stream_view(cuda_stream_view&&)      = default;  ///< @default_move_constructor
+  constexpr cuda_stream_view& operator=(cuda_stream_view const&) =
+    default;  ///< @default_copy_assignment{cuda_stream_view}
+  constexpr cuda_stream_view& operator=(cuda_stream_view&&) =
+    default;  ///< @default_move_assignment{cuda_stream_view}
 
   // Disable construction from literal 0
   constexpr cuda_stream_view(int)            = delete;  //< Prevent cast from 0
   constexpr cuda_stream_view(std::nullptr_t) = delete;  //< Prevent cast from nullptr
 
   /**
-   * @brief Implicit conversion from cudaStream_t.
+   * @brief Constructor from a cudaStream_t
+   *
+   * @param stream The underlying stream for this view
    */
   constexpr cuda_stream_view(cudaStream_t stream) noexcept : stream_{stream} {}
 
   /**
    * @brief Get the wrapped stream.
    *
-   * @return cudaStream_t The wrapped stream.
+   * @return cudaStream_t The underlying stream referenced by this cuda_stream_view
    */
   [[nodiscard]] constexpr cudaStream_t value() const noexcept { return stream_; }
 
   /**
    * @brief Implicit conversion to cudaStream_t.
+   *
+   * @return cudaStream_t The underlying stream referenced by this cuda_stream_view
    */
   constexpr operator cudaStream_t() const noexcept { return value(); }
 
   /**
-   * @brief Return true if the wrapped stream is the CUDA per-thread default stream.
+   * @briefreturn{true if the wrapped stream is the CUDA per-thread default stream}
    */
   [[nodiscard]] inline bool is_per_thread_default() const noexcept;
 
   /**
-   * @brief Return true if the wrapped stream is explicitly the CUDA legacy default stream.
+   * @briefreturn{true if the wrapped stream is explicitly the CUDA legacy default stream}
    */
   [[nodiscard]] inline bool is_default() const noexcept;
 

include/rmm/device_buffer.hpp

@@ -29,7 +29,6 @@
 
 namespace rmm {
 /**
- * @file device_buffer.hpp
  * @brief RAII construct for device memory allocation
  *
  * This class allocates untyped and *uninitialized* device memory using a
@@ -202,6 +201,8 @@ class device_buffer {
    * replaced by the `other.stream()`.
    *
    * @param other The `device_buffer` whose contents will be moved.
+   *
+   * @return A reference to this `device_buffer`
    */
   device_buffer& operator=(device_buffer&& other) noexcept
   {
@@ -331,22 +332,22 @@ class device_buffer {
   }
 
   /**
-   * @brief Returns raw pointer to underlying device memory allocation
+   * @briefreturn{Const pointer to the device memory allocation}
    */
   [[nodiscard]] void const* data() const noexcept { return _data; }
 
   /**
-   * @brief Returns raw pointer to underlying device memory allocation
+   * @briefreturn{Pointer to the device memory allocation}
    */
   void* data() noexcept { return _data; }
 
   /**
-   * @brief Returns the number of bytes.
+   * @briefreturn{The number of bytes}
    */
   [[nodiscard]] std::size_t size() const noexcept { return _size; }
 
   /**
-   * @brief Returns the signed number of bytes.
+   * @briefreturn{The signed number of bytes}
    */
   [[nodiscard]] std::int64_t ssize() const noexcept
   {
@@ -356,23 +357,24 @@ class device_buffer {
   }
 
   /**
-   * @brief returns the number of bytes that can be held in currently allocated storage.
+   * @briefreturn{Whether or not the buffer currently holds any data}
    *
    * If `is_empty() == true`, the `device_buffer` may still hold an allocation
    * if `capacity() > 0`.
-   *
    */
   [[nodiscard]] bool is_empty() const noexcept { return 0 == size(); }
 
   /**
    * @brief Returns actual size in bytes of device memory allocation.
    *
    * The invariant `size() <= capacity()` holds.
+   *
+   * @return The actual size in bytes of the device memory allocation
    */
   [[nodiscard]] std::size_t capacity() const noexcept { return _capacity; }
 
   /**
-   * @brief Returns stream most recently specified for allocation/deallocation
+   * @briefreturn{The stream most recently specified for allocation/deallocation}
    */
   [[nodiscard]] cuda_stream_view stream() const noexcept { return _stream; }
 
@@ -384,12 +386,13 @@ class device_buffer {
    * will be used for deallocation in the `rmm::device_uvector` destructor.
    * However, if either of `resize()` or `shrink_to_fit()` is called after this,
    * the later stream parameter will be stored and used in the destructor.
+   *
+   * @param stream The stream to use for deallocation
    */
   void set_stream(cuda_stream_view stream) noexcept { _stream = stream; }
 
   /**
-   * @brief Returns pointer to the memory resource used to allocate and
-   * deallocate the device memory
+   * @briefreturn{Pointer to the memory resource used to allocate and deallocate}
    */
   [[nodiscard]] mr::device_memory_resource* memory_resource() const noexcept { return _mr; }
 

include/rmm/device_scalar.hpp

@@ -37,18 +37,25 @@ class device_scalar {
  public:
   static_assert(std::is_trivially_copyable<T>::value, "Scalar type must be trivially copyable");
 
-  using value_type      = typename device_uvector<T>::value_type;
-  using reference       = typename device_uvector<T>::reference;
-  using const_reference = typename device_uvector<T>::const_reference;
-  using pointer         = typename device_uvector<T>::pointer;
-  using const_pointer   = typename device_uvector<T>::const_pointer;
+  using value_type = typename device_uvector<T>::value_type;  ///< T, the type of the scalar element
+  using reference  = typename device_uvector<T>::reference;   ///< value_type&
+  using const_reference = typename device_uvector<T>::const_reference;  ///< const value_type&
+  using pointer =
+    typename device_uvector<T>::pointer;  ///< The type of the pointer returned by data()
+  using const_pointer = typename device_uvector<T>::const_pointer;  ///< The type of the iterator
+                                                                    ///< returned by data() const
 
   RMM_EXEC_CHECK_DISABLE
   ~device_scalar() = default;
 
   RMM_EXEC_CHECK_DISABLE
-  device_scalar(device_scalar&&) noexcept = default;
+  device_scalar(device_scalar&&) noexcept = default;  ///< Default move constructor
 
+  /**
+   * @brief Default move assignment operator
+   *
+   * @return device_scalar& A reference to the assigned-to object
+   */
   device_scalar& operator=(device_scalar&&) noexcept = default;
 
   /**
@@ -224,6 +231,8 @@ class device_scalar {
    * specified to the constructor, then appropriate dependencies must be inserted between the
    * streams (e.g. using `cudaStreamWaitEvent()` or `cudaStreamSynchronize()`), otherwise there may
    * be a race condition.
+   *
+   * @return Pointer to underlying device memory
    */
   [[nodiscard]] pointer data() noexcept { return static_cast<pointer>(_storage.data()); }
 
@@ -234,19 +243,23 @@ class device_scalar {
    * specified to the constructor, then appropriate dependencies must be inserted between the
    * streams (e.g. using `cudaStreamWaitEvent()` or `cudaStreamSynchronize()`), otherwise there may
    * be a race condition.
+   *
+   * @return Const pointer to underlying device memory
    */
   [[nodiscard]] const_pointer data() const noexcept
   {
     return static_cast<const_pointer>(_storage.data());
   }
 
   /**
-   * @brief Returns stream most recently specified for allocation/deallocation
+   * @briefreturn{Stream associated with the device memory allocation}
    */
   [[nodiscard]] cuda_stream_view stream() const noexcept { return _storage.stream(); }
 
   /**
    * @brief Sets the stream to be used for deallocation
+   *
+   * @param stream Stream to be used for deallocation
    */
   void set_stream(cuda_stream_view stream) noexcept { _storage.set_stream(stream); }
 

include/rmm/device_uvector.hpp

@@ -71,22 +71,24 @@ class device_uvector {
                 "device_uvector only supports types that are trivially copyable.");
 
  public:
-  using value_type      = T;
-  using size_type       = std::size_t;
-  using reference       = value_type&;
-  using const_reference = value_type const&;
-  using pointer         = value_type*;
-  using const_pointer   = value_type const*;
-  using iterator        = pointer;
-  using const_iterator  = const_pointer;
+  using value_type = T;            ///< T; stored value type
+  using size_type  = std::size_t;  ///< The type used for the size of the vector
+  using reference = value_type&;  ///< value_type&; reference type returned by operator[](size_type)
+  using const_reference = value_type const&;  ///< value_type const&; constant reference type
+                                              ///< returned by operator[](size_type) const
+  using pointer        = value_type*;         ///< The type of the pointer returned by data()
+  using const_pointer  = value_type const*;   ///< The type of the pointer returned by data() const
+  using iterator       = pointer;             ///< The type of the iterator returned by begin()
+  using const_iterator = const_pointer;  ///< The type of the const iterator returned by cbegin()
 
   RMM_EXEC_CHECK_DISABLE
   ~device_uvector() = default;
 
   RMM_EXEC_CHECK_DISABLE
-  device_uvector(device_uvector&&) noexcept = default;
+  device_uvector(device_uvector&&) noexcept = default;  ///< @default_move_constructor
 
-  device_uvector& operator=(device_uvector&&) noexcept = default;
+  device_uvector& operator=(device_uvector&&) noexcept =
+    default;  ///< @default_move_assignment{device_uvector}
 
   /**
    * @brief Copy ctor is deleted as it doesn't allow a stream argument
@@ -497,12 +499,12 @@ class device_uvector {
   [[nodiscard]] const_iterator end() const noexcept { return cend(); }
 
   /**
-   * @brief Returns the number of elements.
+   * @briefreturn{The number of elements in the vector}
    */
   [[nodiscard]] std::size_t size() const noexcept { return bytes_to_elements(_storage.size()); }
 
   /**
-   * @brief Returns the signed number of elements.
+   * @briefreturn{The signed number of elements in the vector}
    */
   [[nodiscard]] std::int64_t ssize() const noexcept
   {
@@ -512,25 +514,20 @@ class device_uvector {
   }
 
   /**
-   * @brief Returns true if the vector contains no elements, i.e., `size() == 0`.
-   *
-   * @return true The vector is empty
-   * @return false The vector is not empty
+   * @briefreturn{true if the vector contains no elements, i.e. `size() == 0`}
    */
   [[nodiscard]] bool is_empty() const noexcept { return size() == 0; }
 
   /**
-   * @brief Returns pointer to the resource used to allocate and deallocate the device storage.
-   *
-   * @return Pointer to underlying resource
+   * @briefreturn{Pointer to underlying resource used to allocate and deallocate the device storage}
    */
   [[nodiscard]] mr::device_memory_resource* memory_resource() const noexcept
   {
     return _storage.memory_resource();
   }
 
   /**
-   * @brief Returns stream most recently specified for allocation/deallocation
+   * @briefreturn{Stream most recently specified for allocation/deallocation}
    */
   [[nodiscard]] cuda_stream_view stream() const noexcept { return _storage.stream(); }
 
@@ -542,6 +539,8 @@ class device_uvector {
    * will be used for deallocation in the `rmm::device_uvector destructor.
    * However, if either of `resize()` or `shrink_to_fit()` is called after this,
    * the later stream parameter will be stored and used in the destructor.
+   *
+   * @param stream The stream to use for deallocation
    */
   void set_stream(cuda_stream_view stream) noexcept { _storage.set_stream(stream); }
 

include/rmm/exec_policy.hpp

@@ -30,6 +30,9 @@
 
 namespace rmm {
 
+/**
+ * @brief Synchronous execution policy for allocations using thrust
+ */
 using thrust_exec_policy_t =
   thrust::detail::execute_with_allocator<rmm::mr::thrust_allocator<char>,
                                          thrust::cuda_cub::execute_on_stream_base>;
@@ -40,6 +43,12 @@ using thrust_exec_policy_t =
  */
 class exec_policy : public thrust_exec_policy_t {
  public:
+  /**
+   * @brief Construct a new execution policy object
+   *
+   * @param stream The stream on which to allocate temporary memory
+   * @param mr The resource to use for allocating temporary memory
+   */
   explicit exec_policy(cuda_stream_view stream             = cuda_stream_default,
                        rmm::mr::device_memory_resource* mr = mr::get_current_device_resource())
     : thrust_exec_policy_t(
@@ -50,6 +59,9 @@ class exec_policy : public thrust_exec_policy_t {
 
 #if THRUST_VERSION >= 101600
 
+/**
+ * @brief Asynchronous execution policy for allocations using thrust
+ */
 using thrust_exec_policy_nosync_t =
   thrust::detail::execute_with_allocator<rmm::mr::thrust_allocator<char>,
                                          thrust::cuda_cub::execute_on_stream_nosync_base>;
@@ -72,9 +84,11 @@ class exec_policy_nosync : public thrust_exec_policy_nosync_t {
 
 #else
 
-using thrust_exec_policy_nosync_t = thrust_exec_policy_t;
-using exec_policy_nosync          = exec_policy;
-
+using thrust_exec_policy_nosync_t =
+  thrust_exec_policy_t;  ///< When used with Thrust < 1.16.0, thrust_exec_policy_nosync_t is an
+                         ///< alias for thrust_exec_policy_t
+using exec_policy_nosync =
+  exec_policy;           ///< When used with Thrust < 1.16.0, exec_policy_nosync is an alias for exec_policy
 #endif
 
 }  // namespace rmm