Add groups to the doxygen docs (#1358)

This PR adds doxygen groups for the various parts of the C++ API to help provide more context. This will also help with improving the docs experience in #1324.

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

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

URL: #1358

doxygen/Doxyfile

@@ -859,7 +859,8 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../include
+INPUT                  = main_page.md \
+                         ../include
 
 # 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
@@ -1017,7 +1018,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE =
+USE_MDFILE_AS_MAINPAGE = main_page.md
 
 #---------------------------------------------------------------------------
 # Configuration options related to source browsing

doxygen/main_page.md

@@ -0,0 +1,13 @@
+# librmm
+
+Achieving optimal performance in GPU-centric workflows frequently requires customizing how host and
+device memory are allocated. For example, using "pinned" host memory for asynchronous
+host <-> device memory transfers, or using a device memory pool sub-allocator to reduce the cost of
+dynamic device memory allocation.
+
+The goal of the RAPIDS Memory Manager (RMM) is to provide:
+- A common interface that allows customizing device and host memory allocation
+- A collection of implementations of the interface
+- A collection of data structures that use the interface for memory allocation
+
+\htmlonly For more information on APIs provided by rmm, see <a href="modules.html">the modules page</a>\endhtmlonly.

include/doxygen_groups.h

@@ -0,0 +1,43 @@
+/*
+ * Copyright (c) 2023, NVIDIA CORPORATION.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @file
+ * @brief Doxygen group definitions
+ */
+
+// This header is only processed by doxygen and does
+// not need to be included in any source file.
+// Below are the main groups that doxygen uses to build
+// the Modules page in the specified order.
+//
+// To add a new API to an existing group, just use the
+// @ingroup tag to the API's doxygen comment.
+// Add a new group by first specifying in the hierarchy below.
+
+/**
+ * @defgroup memory_resources Memory Resources
+ * @{
+ *   @defgroup device_memory_resources Device Memory Resources
+ *   @defgroup host_memory_resources Host Memory Resources
+ *   @defgroup device_resource_adaptors Device Resource Adaptors
+ * @}
+ * @defgroup cuda_device_management CUDA Device Management
+ * @defgroup cuda_streams CUDA Streams
+ * @defgroup data_containers Data Containers
+ * @defgroup logging Logging
+ * @defgroup thrust_integrations Thrust Integrations
+ */

include/rmm/cuda_device.hpp

@@ -21,6 +21,11 @@
 
 namespace rmm {
 
+/**
+ * @addtogroup cuda_device_management
+ * @{
+ * @file
+ */
 /**
  * @brief Strong type for a CUDA device identifier.
  *
@@ -101,4 +106,5 @@ struct cuda_set_device_raii {
   bool needs_reset_;
 };
 
+/** @} */  // end of group
 }  // namespace rmm

include/rmm/cuda_stream.hpp

@@ -26,6 +26,11 @@
 #include <memory>
 
 namespace rmm {
+/**
+ * @addtogroup cuda_streams
+ * @{
+ * @file
+ */
 
 /**
  * @brief Owning wrapper for a CUDA stream.
@@ -133,4 +138,5 @@ class cuda_stream {
   std::unique_ptr<cudaStream_t, std::function<void(cudaStream_t*)>> stream_;
 };
 
+/** @} */  // end of group
 }  // namespace rmm

include/rmm/cuda_stream_pool.hpp

@@ -25,6 +25,11 @@
 #include <vector>
 
 namespace rmm {
+/**
+ * @addtogroup cuda_streams
+ * @{
+ * @file
+ */
 
 /**
  * @brief A pool of CUDA streams.
@@ -96,4 +101,5 @@ class cuda_stream_pool {
   mutable std::atomic_size_t next_stream{};
 };
 
+/** @} */  // end of group
 }  // namespace rmm

include/rmm/cuda_stream_view.hpp

@@ -25,6 +25,11 @@
 #include <cstdint>
 
 namespace rmm {
+/**
+ * @addtogroup cuda_streams
+ * @{
+ * @file
+ */
 
 /**
  * @brief Strongly-typed non-owning wrapper for CUDA streams with default constructor.
@@ -175,4 +180,5 @@ inline std::ostream& operator<<(std::ostream& os, cuda_stream_view stream)
   return os;
 }
 
+/** @} */  // end of group
 }  // namespace rmm

include/rmm/device_buffer.hpp

@@ -28,6 +28,11 @@
 #include <utility>
 
 namespace rmm {
+/**
+ * @addtogroup data_containers
+ * @{
+ * @file
+ */
 /**
  * @brief RAII construct for device memory allocation
  *
@@ -459,4 +464,6 @@ class device_buffer {
     }
   }
 };
+
+/** @} */  // end of group
 }  // namespace rmm

include/rmm/device_scalar.hpp

@@ -24,6 +24,11 @@
 #include <type_traits>
 
 namespace rmm {
+/**
+ * @addtogroup data_containers
+ * @{
+ * @file
+ */
 
 /**
  * @brief Container for a single object of type `T` in device memory.
@@ -266,4 +271,6 @@ class device_scalar {
  private:
   rmm::device_uvector<T> _storage;
 };
+
+/** @} */  // end of group
 }  // namespace rmm

include/rmm/device_uvector.hpp

@@ -27,6 +27,11 @@
 #include <vector>
 
 namespace rmm {
+/**
+ * @addtogroup data_containers
+ * @{
+ * @file
+ */
 
 /**
  * @brief An *uninitialized* vector of elements in device memory.
@@ -557,4 +562,6 @@ class device_uvector {
     return num_bytes / sizeof(value_type);
   }
 };
+
+/** @} */  // end of group
 }  // namespace rmm

include/rmm/device_vector.hpp

@@ -22,11 +22,17 @@
 #include <thrust/device_vector.h>
 
 namespace rmm {
+/**
+ * @addtogroup thrust_integrations
+ * @{
+ * @file
+ */
 /**
  * @brief Alias for a thrust::device_vector that uses RMM for memory allocation.
  *
  */
 template <typename T>
 using device_vector = thrust::device_vector<T, rmm::mr::thrust_allocator<T>>;
 
+/** @} */  // end of group
 }  // namespace rmm

include/rmm/exec_policy.hpp

@@ -29,6 +29,11 @@
 #include <thrust/version.h>
 
 namespace rmm {
+/**
+ * @addtogroup thrust_integrations
+ * @{
+ * @file
+ */
 
 /**
  * @brief Synchronous execution policy for allocations using thrust
@@ -91,4 +96,5 @@ using exec_policy_nosync =
   exec_policy;  ///< When used with Thrust < 1.16.0, exec_policy_nosync is an alias for exec_policy
 #endif
 
+/** @} */  // end of group
 }  // namespace rmm

include/rmm/logger.hpp

@@ -96,6 +96,12 @@ struct bytes {
 
 }  // namespace detail
 
+/**
+ * @addtogroup logging
+ * @{
+ * @file
+ */
+
 /**
  * @brief Returns the global RMM logger
  *
@@ -109,6 +115,8 @@ inline spdlog::logger& logger()
   return wrapped.logger_;
 }
 
+//! @cond Doxygen_Suppress
+//
 // The default is INFO, but it should be used sparingly, so that by default a log file is only
 // output if there is important information, warnings, errors, and critical failures
 // Log messages that require computation should only be used at level TRACE and DEBUG
@@ -119,10 +127,14 @@ inline spdlog::logger& logger()
 #define RMM_LOG_ERROR(...)    SPDLOG_LOGGER_ERROR(&rmm::logger(), __VA_ARGS__)
 #define RMM_LOG_CRITICAL(...) SPDLOG_LOGGER_CRITICAL(&rmm::logger(), __VA_ARGS__)
 
+//! @endcond
+
 }  // namespace rmm
 
 // Doxygen doesn't like this because we're overloading something from fmt
 //! @cond Doxygen_Suppress
 template <>
 struct fmt::formatter<rmm::detail::bytes> : fmt::ostream_formatter {};
+
+/** @} */  // end of group
 //! @endcond

include/rmm/mr/device/aligned_resource_adaptor.hpp

@@ -26,6 +26,11 @@
 #include <unordered_map>
 
 namespace rmm::mr {
+/**
+ * @addtogroup device_resource_adaptors
+ * @{
+ * @file
+ */
 /**
  * @brief Resource that adapts `Upstream` memory resource to allocate memory in a specified
  * alignment size.
@@ -214,4 +219,5 @@ class aligned_resource_adaptor final : public device_memory_resource {
   mutable std::mutex mtx_;           ///< Mutex for exclusive lock.
 };
 
+/** @} */  // end of group
 }  // namespace rmm::mr

include/rmm/mr/device/arena_memory_resource.hpp

@@ -31,6 +31,11 @@
 #include <thread>
 
 namespace rmm::mr {
+/**
+ * @addtogroup device_memory_resources
+ * @{
+ * @file
+ */
 
 /**
  * @brief A suballocator that emphasizes fragmentation avoidance and scalable concurrency support.
@@ -343,4 +348,5 @@ class arena_memory_resource final : public device_memory_resource {
   mutable std::shared_mutex mtx_;
 };
 
+/** @} */  // end of group
 }  // namespace rmm::mr

include/rmm/mr/device/binning_memory_resource.hpp

@@ -28,6 +28,11 @@
 #include <vector>
 
 namespace rmm::mr {
+/**
+ * @addtogroup device_memory_resources
+ * @{
+ * @file
+ */
 
 /**
  * @brief Allocates memory from upstream resources associated with bin sizes.
@@ -214,4 +219,5 @@ class binning_memory_resource final : public device_memory_resource {
   std::map<std::size_t, device_memory_resource*> resource_bins_;
 };
 
+/** @} */  // end of group
 }  // namespace rmm::mr

include/rmm/mr/device/callback_memory_resource.hpp

@@ -22,6 +22,11 @@
 #include <utility>
 
 namespace rmm::mr {
+/**
+ * @addtogroup device_memory_resources
+ * @{
+ * @file
+ */
 
 /**
  * @brief Callback function type used by callback memory resource for allocation.
@@ -147,4 +152,5 @@ class callback_memory_resource final : public device_memory_resource {
   void* deallocate_callback_arg_;
 };
 
+/** @} */  // end of group
 }  // namespace rmm::mr

include/rmm/mr/device/cuda_async_memory_resource.hpp

@@ -38,6 +38,11 @@
 #endif
 
 namespace rmm::mr {
+/**
+ * @addtogroup device_memory_resources
+ * @{
+ * @file
+ */
 
 /**
  * @brief `device_memory_resource` derived class that uses `cudaMallocAsync`/`cudaFreeAsync` for
@@ -245,4 +250,5 @@ class cuda_async_memory_resource final : public device_memory_resource {
   }
 };
 
+/** @} */  // end of group
 }  // namespace rmm::mr

include/rmm/mr/device/cuda_async_view_memory_resource.hpp

@@ -35,6 +35,11 @@
 #endif
 
 namespace rmm::mr {
+/**
+ * @addtogroup device_memory_resources
+ * @{
+ * @file
+ */
 
 /**
  * @brief `device_memory_resource` derived class that uses `cudaMallocAsync`/`cudaFreeAsync` for
@@ -182,4 +187,5 @@ class cuda_async_view_memory_resource final : public device_memory_resource {
   }
 };
 
+/** @} */  // end of group
 }  // namespace rmm::mr