Fix more doxygen issues (#1367)

This PR:
- Adds the errors group to the doxygen so that errors are also contained in a group
- Removes invalid `@throws` sections that throw nothing
- Remove unnecessary backticks around exception types in contexts where they are already assumed to be types and therefore will link/use the appropriate font automatically

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

Approvers:
  - Mark Harris (https://github.com/harrism)

URL: #1367

benchmarks/utilities/simulated_memory_resource.hpp

@@ -72,7 +72,7 @@ class simulated_memory_resource final : public device_memory_resource {
    *
    * @note Stream argument is ignored
    *
-   * @throws `rmm::bad_alloc` if the requested allocation could not be fulfilled
+   * @throws rmm::bad_alloc if the requested allocation could not be fulfilled
    *
    * @param bytes The size, in bytes, of the allocation
    * @return void* Pointer to the newly allocated memory
@@ -91,8 +91,6 @@ class simulated_memory_resource final : public device_memory_resource {
    *
    * @note This call is ignored.
    *
-   * @throws Nothing.
-   *
    * @param ptr Pointer to be deallocated
    */
   void do_deallocate(void* ptr, std::size_t, cuda_stream_view) override {}

doxygen/Doxyfile

@@ -859,8 +859,11 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
+# Need to specify the error.hpp file explicitly because it is excluded by the
+# EXCLUDE_PATTERNS below.
 INPUT                  = main_page.md \
-                         ../include
+                         ../include \
+                         ../include/rmm/detail/error.hpp
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

include/doxygen_groups.h

@@ -38,6 +38,7 @@
  * @defgroup cuda_device_management CUDA Device Management
  * @defgroup cuda_streams CUDA Streams
  * @defgroup data_containers Data Containers
+ * @defgroup errors Errors
  * @defgroup logging Logging
  * @defgroup thrust_integrations Thrust Integrations
  */

include/rmm/detail/error.hpp

@@ -24,9 +24,12 @@
 #include <string>
 
 namespace rmm {
+
 /**
  * @brief Exception thrown when logical precondition is violated.
  *
+ * @ingroup errors
+ *
  * This exception should not be thrown directly and is instead thrown by the
  * RMM_EXPECTS macro.
  *
@@ -38,6 +41,8 @@ struct logic_error : public std::logic_error {
 /**
  * @brief Exception thrown when a CUDA error is encountered.
  *
+ * @ingroup errors
+ *
  */
 struct cuda_error : public std::runtime_error {
   using std::runtime_error::runtime_error;
@@ -46,12 +51,28 @@ struct cuda_error : public std::runtime_error {
 /**
  * @brief Exception thrown when an RMM allocation fails
  *
+ * @ingroup errors
+ *
  */
 class bad_alloc : public std::bad_alloc {
  public:
+  /**
+   * @brief Constructs a bad_alloc with the error message.
+   *
+   * @param msg Message to be associated with the exception
+   */
   bad_alloc(const char* msg) : _what{std::string{std::bad_alloc::what()} + ": " + msg} {}
+
+  /**
+   * @brief Constructs a bad_alloc with the error message.
+   *
+   * @param msg Message to be associated with the exception
+   */
   bad_alloc(std::string const& msg) : bad_alloc{msg.c_str()} {}
 
+  /**
+   * @briefreturn{The explanatory string}
+   */
   [[nodiscard]] const char* what() const noexcept override { return _what.c_str(); }
 
  private:
@@ -61,17 +82,32 @@ class bad_alloc : public std::bad_alloc {
 /**
  * @brief Exception thrown when RMM runs out of memory
  *
+ * @ingroup errors
+ *
  * This error should only be thrown when we know for sure a resource is out of memory.
  */
 class out_of_memory : public bad_alloc {
  public:
+  /**
+   * @brief Constructs an out_of_memory with the error message.
+   *
+   * @param msg Message to be associated with the exception
+   */
   out_of_memory(const char* msg) : bad_alloc{std::string{"out_of_memory: "} + msg} {}
+
+  /**
+   * @brief Constructs an out_of_memory with the error message.
+   *
+   * @param msg Message to be associated with the exception
+   */
   out_of_memory(std::string const& msg) : out_of_memory{msg.c_str()} {}
 };
 
 /**
  * @brief Exception thrown when attempting to access outside of a defined range
  *
+ * @ingroup errors
+ *
  */
 class out_of_range : public std::out_of_range {
   using std::out_of_range::out_of_range;
@@ -86,7 +122,7 @@ class out_of_range : public std::out_of_range {
  * @brief Macro for checking (pre-)conditions that throws an exception when
  * a condition is violated.
  *
- * Defaults to throwing `rmm::logic_error`, but a custom exception may also be
+ * Defaults to throwing rmm::logic_error, but a custom exception may also be
  * specified.
  *
  * Example usage:
@@ -97,12 +133,13 @@ class out_of_range : public std::out_of_range {
  * // throws std::runtime_error
  * RMM_EXPECTS(p != nullptr, "Unexpected nullptr", std::runtime_error);
  * ```
- * @param[in] _condition Expression that evaluates to true or false
- * @param[in] _what  String literal description of why the exception was
- *     thrown, i.e. why `_condition` was expected to be true.
- * @param[in] _expection_type The exception type to throw; must inherit
- *     `std::exception`. If not specified (i.e. if only two macro
- *     arguments are provided), defaults to `rmm::logic_error`
+ * @param ... This macro accepts either two or three arguments:
+ *   - The first argument must be an expression that evaluates to true or
+ *     false, and is the condition being checked.
+ *   - The second argument is a string literal used to construct the `what` of
+ *     the exception.
+ *   - When given, the third argument is the exception to be thrown. When not
+ *     specified, defaults to `rmm::logic_error`.
  * @throw `_exception_type` if the condition evaluates to 0 (false).
  */
 #define RMM_EXPECTS(...)                                           \
@@ -122,7 +159,7 @@ class out_of_range : public std::out_of_range {
  *
  * Example usage:
  * ```c++
- * // Throws `rmm::logic_error`
+ * // Throws rmm::logic_error
  * RMM_FAIL("Unsupported code path");
  *
  * // Throws `std::runtime_error`
@@ -145,16 +182,16 @@ class out_of_range : public std::out_of_range {
  * `cudaSuccess`, invokes cudaGetLastError() to clear the error and throws an
  * exception detailing the CUDA error that occurred
  *
- * Defaults to throwing `rmm::cuda_error`, but a custom exception may also be
+ * Defaults to throwing rmm::cuda_error, but a custom exception may also be
  * specified.
  *
  * Example:
  * ```c++
  *
- * // Throws `rmm::cuda_error` if `cudaMalloc` fails
+ * // Throws rmm::cuda_error if `cudaMalloc` fails
  * RMM_CUDA_TRY(cudaMalloc(&p, 100));
  *
- * // Throws `std::runtime_error` if `cudaMalloc` fails
+ * // Throws std::runtime_error if `cudaMalloc` fails
  * RMM_CUDA_TRY(cudaMalloc(&p, 100), std::runtime_error);
  * ```
  *
@@ -183,8 +220,8 @@ class out_of_range : public std::out_of_range {
  * `cudaSuccess`, invokes cudaGetLastError() to clear the error and throws an
  * exception detailing the CUDA error that occurred
  *
- * Defaults to throwing `rmm::bad_alloc`, but when `cudaErrorMemoryAllocation` is returned,
- * `rmm::out_of_memory` is thrown instead.
+ * Defaults to throwing rmm::bad_alloc, but when `cudaErrorMemoryAllocation` is returned,
+ * rmm::out_of_memory is thrown instead.
  */
 #define RMM_CUDA_TRY_ALLOC(_call)                                                                  \
   do {                                                                                             \

include/rmm/device_buffer.hpp

@@ -177,8 +177,6 @@ class device_buffer {
    * valid, empty `device_buffer`, i.e., `data()` returns `nullptr`, and
    * `size()` and `capacity()` are zero.
    *
-   * @throws Nothing
-   *
    * @param other The `device_buffer` whose contents will be moved into the
    * newly constructed one.
    */

include/rmm/device_scalar.hpp

@@ -87,7 +87,7 @@ class device_scalar {
    * stream, or on another stream only if a dependency is enforced (e.g. using
    * `cudaStreamWaitEvent()`).
    *
-   * @throws `rmm::bad_alloc` if allocating the device memory fails.
+   * @throws rmm::bad_alloc if allocating the device memory fails.
    *
    * @param stream Stream on which to perform asynchronous allocation.
    * @param mr Optional, resource with which to allocate.
@@ -108,8 +108,8 @@ class device_scalar {
    * stream, or on another stream only if a dependency is enforced (e.g. using
    * `cudaStreamWaitEvent()`).
    *
-   * @throws `rmm::bad_alloc` if allocating the device memory for `initial_value` fails.
-   * @throws `rmm::cuda_error` if copying `initial_value` to device memory fails.
+   * @throws rmm::bad_alloc if allocating the device memory for `initial_value` fails.
+   * @throws rmm::cuda_error if copying `initial_value` to device memory fails.
    *
    * @param initial_value The initial value of the object in device memory.
    * @param stream Optional, stream on which to perform allocation and copy.
@@ -153,8 +153,8 @@ class device_scalar {
    * (e.g. using `cudaStreamWaitEvent()` or `cudaStreamSynchronize()`) before calling this function,
    * otherwise there may be a race condition.
    *
-   * @throws `rmm::cuda_error` If the copy fails.
-   * @throws `rmm::cuda_error` If synchronizing `stream` fails.
+   * @throws rmm::cuda_error If the copy fails.
+   * @throws rmm::cuda_error If synchronizing `stream` fails.
    *
    * @return T The value of the scalar.
    * @param stream CUDA stream on which to perform the copy and synchronize.
@@ -196,7 +196,7 @@ class device_scalar {
    * v = 13;
    * \endcode
    *
-   * @throws `rmm::cuda_error` if copying `host_value` to device memory fails.
+   * @throws rmm::cuda_error if copying @p value to device memory fails.
    *
    * @param value The host value which will be copied to device
    * @param stream CUDA stream on which to perform the copy

include/rmm/logger.hpp

@@ -96,15 +96,9 @@ struct bytes {
 
 }  // namespace detail
 
-/**
- * @addtogroup logging
- * @{
- * @file
- */
-
 /**
  * @brief Returns the global RMM logger
- *
+ * @addtogroup logging
  * This is a spdlog logger. The easiest way to log messages is to use the `RMM_LOG_*` macros.
  *
  * @return spdlog::logger& The logger.
@@ -136,5 +130,4 @@ inline spdlog::logger& logger()
 template <>
 struct fmt::formatter<rmm::detail::bytes> : fmt::ostream_formatter {};
 
-/** @} */  // end of group
 //! @endcond

include/rmm/mr/device/aligned_resource_adaptor.hpp

@@ -56,8 +56,8 @@ class aligned_resource_adaptor final : public device_memory_resource {
   /**
    * @brief Construct an aligned resource adaptor using `upstream` to satisfy allocation requests.
    *
-   * @throws `rmm::logic_error` if `upstream == nullptr`
-   * @throws `rmm::logic_error` if `allocation_alignment` is not a power of 2
+   * @throws rmm::logic_error if `upstream == nullptr`
+   * @throws rmm::logic_error if `allocation_alignment` is not a power of 2
    *
    * @param upstream The resource used for allocating/deallocating device memory.
    * @param alignment The size used for allocation alignment.
@@ -114,7 +114,7 @@ class aligned_resource_adaptor final : public device_memory_resource {
    * @brief Allocates memory of size at least `bytes` using the upstream resource with the specified
    * alignment.
    *
-   * @throws `rmm::bad_alloc` if the requested allocation could not be fulfilled
+   * @throws rmm::bad_alloc if the requested allocation could not be fulfilled
    * by the upstream resource.
    *
    * @param bytes The size, in bytes, of the allocation
@@ -143,8 +143,6 @@ class aligned_resource_adaptor final : public device_memory_resource {
   /**
    * @brief Free allocation of size `bytes` pointed to to by `p` and log the deallocation.
    *
-   * @throws Nothing.
-   *
    * @param ptr Pointer to be deallocated
    * @param bytes Size of the allocation
    * @param stream Stream on which to perform the deallocation
@@ -169,8 +167,6 @@ class aligned_resource_adaptor final : public device_memory_resource {
   /**
    * @brief Compare this resource to another.
    *
-   * @throws Nothing.
-   *
    * @param other The other resource to compare to
    * @return true If the two resources are equivalent
    * @return false If the two resources are not equivalent
@@ -188,7 +184,7 @@ class aligned_resource_adaptor final : public device_memory_resource {
    *
    * The free size may not be fully allocatable because of alignment requirements.
    *
-   * @throws `rmm::cuda_error` if unable to retrieve memory info.
+   * @throws rmm::cuda_error if unable to retrieve memory info.
    *
    * @param stream Stream on which to get the mem info.
    * @return std::pair containing free_size and total_size of memory

include/rmm/mr/device/cuda_async_memory_resource.hpp

@@ -220,8 +220,6 @@ class cuda_async_memory_resource final : public device_memory_resource {
   /**
    * @brief Compare this resource to another.
    *
-   * @throws Nothing.
-   *
    * @param other The other resource to compare to
    * @return true If the two resources are equivalent
    * @return false If the two resources are not equal
@@ -239,7 +237,7 @@ class cuda_async_memory_resource final : public device_memory_resource {
   /**
    * @brief Get free and available memory for memory resource
    *
-   * @throws `rmm::cuda_error` if unable to retrieve memory info.
+   * @throws rmm::cuda_error if unable to retrieve memory info.
    *
    * @return std::pair contaiing free_size and total_size of memory
    */

include/rmm/mr/device/cuda_async_view_memory_resource.hpp

@@ -162,8 +162,6 @@ class cuda_async_view_memory_resource final : public device_memory_resource {
   /**
    * @brief Compare this resource to another.
    *
-   * @throws Nothing.
-   *
    * @param other The other resource to compare to
    * @return true If the two resources are equivalent
    * @return false If the two resources are not equal
@@ -176,7 +174,7 @@ class cuda_async_view_memory_resource final : public device_memory_resource {
   /**
    * @brief Get free and available memory for memory resource
    *
-   * @throws `rmm::cuda_error` if unable to retrieve memory info.
+   * @throws rmm::cuda_error if unable to retrieve memory info.
    *
    * @return std::pair contaiing free_size and total_size of memory
    */

include/rmm/mr/device/cuda_memory_resource.hpp

@@ -100,8 +100,6 @@ class cuda_memory_resource final : public device_memory_resource {
    * Two cuda_memory_resources always compare equal, because they can each
    * deallocate memory allocated by the other.
    *
-   * @throws Nothing.
-   *
    * @param other The other resource to compare to
    * @return true If the two resources are equivalent
    * @return false If the two resources are not equal
@@ -114,7 +112,7 @@ class cuda_memory_resource final : public device_memory_resource {
   /**
    * @brief Get free and available memory for memory resource
    *
-   * @throws `rmm::cuda_error` if unable to retrieve memory info.
+   * @throws rmm::cuda_error if unable to retrieve memory info.
    *
    * @return std::pair contaiing free_size and total_size of memory
    */

include/rmm/mr/device/device_memory_resource.hpp

@@ -104,8 +104,8 @@ class device_memory_resource {
    * If supported, this operation may optionally be executed on a stream.
    * Otherwise, the stream is ignored and the null stream is used.
    *
-   * @throws `rmm::bad_alloc` When the requested `bytes` cannot be allocated on
-   * the specified `stream`.
+   * @throws rmm::bad_alloc When the requested `bytes` cannot be allocated on
+   * the specified @p stream.
    *
    * @param bytes The size of the allocation
    * @param stream Stream on which to perform allocation
@@ -127,8 +127,6 @@ class device_memory_resource {
    * If supported, this operation may optionally be executed on a stream.
    * Otherwise, the stream is ignored and the null stream is used.
    *
-   * @throws Nothing.
-   *
    * @param ptr Pointer to be deallocated
    * @param bytes The size in bytes of the allocation. This must be equal to the
    * value of `bytes` that was passed to the `allocate` call that returned `p`.