Add missing docs for roaring bitmap (#752)

This PR adds missing docs for the experimental roaring bitmap.

---------

Co-authored-by: Daniel Jünger <[email protected]>

Author: PointKernel

include/cuco/detail/roaring_bitmap/roaring_bitmap_storage.cuh

@@ -37,10 +37,24 @@ struct roaring_bitmap_storage_ref {
   static_assert(cuco::dependent_false<T>, "T must be either uint32_t or uint64_t");
 };
 
+/**
+ * @brief Reference type for 32-bit roaring bitmap storage
+ *
+ * Provides a lightweight reference to a 32-bit roaring bitmap stored in device memory,
+ * allowing access to the bitmap data and metadata without ownership.
+ */
 template <>
 class roaring_bitmap_storage_ref<cuda::std::uint32_t> {
  public:
+  /// Metadata type for this storage reference
   using metadata_type = roaring_bitmap_metadata<cuda::std::uint32_t>;
+
+  /**
+   * @brief Constructs a storage reference from bitmap data and metadata
+   *
+   * @param bitmap Pointer to the serialized bitmap in a device-accessible memory location
+   * @param metadata Metadata describing the bitmap structure
+   */
   __host__ __device__ roaring_bitmap_storage_ref(cuda::std::byte const* bitmap,
                                                  metadata_type const& metadata)
     : metadata_{metadata},
@@ -52,24 +66,61 @@ class roaring_bitmap_storage_ref<cuda::std::uint32_t> {
     assert(metadata.valid);
   }
 
+  /**
+   * @brief Constructs a storage reference from bitmap data
+   *
+   * Automatically parses metadata from the bitmap data.
+   *
+   * @param bitmap Pointer to the serialized bitmap in a device-accessible memory location
+   */
   __device__ roaring_bitmap_storage_ref(cuda::std::byte const* bitmap)
     : roaring_bitmap_storage_ref{bitmap, metadata_type{bitmap}}
   {
   }
 
+  /**
+   * @brief Returns the metadata for this bitmap
+   *
+   * @return Reference to the bitmap metadata
+   */
   __host__ __device__ metadata_type const& metadata() const noexcept { return metadata_; }
 
+  /**
+   * @brief Returns pointer to the raw bitmap data
+   *
+   * @return Pointer to the beginning of the bitmap data
+   */
   __host__ __device__ cuda::std::byte const* data() const noexcept { return data_; }
 
+  /**
+   * @brief Returns the size of the bitmap in bytes
+   *
+   * @return Size of the bitmap data in bytes
+   */
   __host__ __device__ cuda::std::size_t size_bytes() const noexcept { return metadata_.size_bytes; }
 
+  /**
+   * @brief Returns pointer to the run container bitmap
+   *
+   * @return Pointer to the run container bitmap data
+   */
   __host__ __device__ cuda::std::byte const* run_container_bitmap() const noexcept
   {
     return run_container_bitmap_;
   }
 
+  /**
+   * @brief Returns pointer to the key cardinalities data
+   *
+   * @return Pointer to the key cardinalities data
+   */
   __host__ __device__ cuda::std::byte const* key_cards() const noexcept { return key_cards_; }
 
+  /**
+   * @brief Returns pointer to the container offsets data
+   *
+   * @return Pointer to the container offsets data
+   */
   __host__ __device__ cuda::std::byte const* container_offsets() const noexcept
   {
     return container_offsets_;
@@ -83,11 +134,25 @@ class roaring_bitmap_storage_ref<cuda::std::uint32_t> {
   cuda::std::byte const* container_offsets_;
 };
 
+/**
+ * @brief Reference type for 64-bit roaring bitmap storage
+ *
+ * Provides a lightweight reference to a 64-bit roaring bitmap stored in device memory,
+ * allowing access to the bitmap data, metadata, and bucket information without ownership.
+ */
 template <>
 class roaring_bitmap_storage_ref<cuda::std::uint64_t> {
  public:
+  /// Metadata type for this storage reference
   using metadata_type = roaring_bitmap_metadata<cuda::std::uint64_t>;
 
+  /**
+   * @brief Constructs a storage reference from bitmap data, metadata, and buckets
+   *
+   * @param bitmap Pointer to the serialized bitmap in a device-accessible memory location
+   * @param metadata Metadata describing the bitmap structure
+   * @param buckets Pointer to the array of bucket references in a device-accessible memory location
+   */
   __host__ __device__ roaring_bitmap_storage_ref(
     cuda::std::byte const* bitmap,
     metadata_type const& metadata,
@@ -96,12 +161,32 @@ class roaring_bitmap_storage_ref<cuda::std::uint64_t> {
   {
   }
 
+  /**
+   * @brief Returns the metadata for this bitmap
+   *
+   * @return Reference to the bitmap metadata
+   */
   __host__ __device__ metadata_type const& metadata() const noexcept { return metadata_; }
 
+  /**
+   * @brief Returns pointer to the raw bitmap data
+   *
+   * @return Pointer to the beginning of the bitmap data
+   */
   __host__ __device__ cuda::std::byte const* data() const noexcept { return data_; }
 
+  /**
+   * @brief Returns the size of the bitmap in bytes
+   *
+   * @return Size of the bitmap data in bytes
+   */
   __host__ __device__ cuda::std::size_t size_bytes() const noexcept { return metadata_.size_bytes; }
 
+  /**
+   * @brief Returns pointer to the bucket array
+   *
+   * @return Pointer to the array of bucket key-reference pairs
+   */
   __host__ __device__
     cuda::std::pair<cuda::std::uint32_t, roaring_bitmap_storage_ref<cuda::std::uint32_t>>*
     buckets() const noexcept
@@ -120,20 +205,62 @@ struct roaring_bitmap_storage {
   static_assert(cuco::dependent_false<T>, "T must be either uint32_t or uint64_t");
 };
 
+/**
+ * @brief Storage container for 32-bit roaring bitmap
+ *
+ * Manages device memory for a 32-bit roaring bitmap, providing ownership
+ * and automatic memory management.
+ *
+ * @tparam Allocator Allocator type for device memory management
+ */
 template <class Allocator>
 class roaring_bitmap_storage<cuda::std::uint32_t, Allocator> {
  public:
+  /// Allocator type for device memory allocation
   using allocator_type =
     typename std::allocator_traits<Allocator>::template rebind_alloc<cuda::std::byte>;
+  /// Reference type for this storage
   using ref_type = roaring_bitmap_storage_ref<cuda::std::uint32_t>;
 
-  roaring_bitmap_storage(roaring_bitmap_storage const& other)            = default;
-  roaring_bitmap_storage(roaring_bitmap_storage&& other)                 = default;
+  /**
+   * @brief Copy constructor
+   *
+   * @param other The roaring_bitmap_storage to copy from
+   */
+  roaring_bitmap_storage(roaring_bitmap_storage const& other) = default;
+
+  /**
+   * @brief Move constructor
+   *
+   * @param other The roaring_bitmap_storage to move from
+   */
+  roaring_bitmap_storage(roaring_bitmap_storage&& other) = default;
+
+  /**
+   * @brief Copy assignment operator
+   *
+   * @param other The roaring_bitmap_storage to copy from
+   * @return Reference to this roaring_bitmap_storage
+   */
   roaring_bitmap_storage& operator=(roaring_bitmap_storage const& other) = default;
-  roaring_bitmap_storage& operator=(roaring_bitmap_storage&& other)      = default;
+
+  /**
+   * @brief Move assignment operator
+   *
+   * @param other The roaring_bitmap_storage to move from
+   * @return Reference to this roaring_bitmap_storage
+   */
+  roaring_bitmap_storage& operator=(roaring_bitmap_storage&& other) = default;
 
   ~roaring_bitmap_storage() = default;
 
+  /**
+   * @brief Constructs storage by copying bitmap data to device memory
+   *
+   * @param bitmap Pointer to the serialized bitmap data in host memory
+   * @param alloc Allocator for device memory allocation
+   * @param stream CUDA stream for memory operations
+   */
   roaring_bitmap_storage(cuda::std::byte const* bitmap,
                          Allocator const& alloc,
                          cuda::stream_ref stream)
@@ -148,6 +275,11 @@ class roaring_bitmap_storage<cuda::std::uint32_t, Allocator> {
       data_.get(), bitmap, metadata_.size_bytes, cudaMemcpyHostToDevice, stream.get()));
   }
 
+  /**
+   * @brief Returns a reference to the stored bitmap
+   *
+   * @return Reference to the bitmap storage
+   */
   ref_type ref() const noexcept { return ref_; }
 
  private:
@@ -158,23 +290,67 @@ class roaring_bitmap_storage<cuda::std::uint32_t, Allocator> {
   ref_type ref_;
 };
 
+/**
+ * @brief Storage container for 64-bit roaring bitmap
+ *
+ * Manages device memory for a 64-bit roaring bitmap, providing ownership
+ * and automatic memory management including bucket storage.
+ *
+ * @tparam Allocator Allocator type for device memory management
+ */
 template <class Allocator>
 class roaring_bitmap_storage<cuda::std::uint64_t, Allocator> {
  public:
+  /// Allocator type for device memory allocation
   using allocator_type =
     typename std::allocator_traits<Allocator>::template rebind_alloc<cuda::std::byte>;
-  using ref_type              = roaring_bitmap_storage_ref<cuda::std::uint64_t>;
-  using bucket_ref_type       = roaring_bitmap_storage_ref<cuda::std::uint32_t>;
+  /// Reference type for this storage
+  using ref_type = roaring_bitmap_storage_ref<cuda::std::uint64_t>;
+  /// Reference type for individual buckets
+  using bucket_ref_type = roaring_bitmap_storage_ref<cuda::std::uint32_t>;
+  /// Allocator type for bucket array allocation
   using bucket_allocator_type = typename std::allocator_traits<Allocator>::template rebind_alloc<
     cuda::std::pair<cuda::std::uint32_t, bucket_ref_type>>;
 
-  roaring_bitmap_storage(roaring_bitmap_storage const& other)            = default;
-  roaring_bitmap_storage(roaring_bitmap_storage&& other)                 = default;
+  /**
+   * @brief Copy constructor
+   *
+   * @param other The roaring_bitmap_storage to copy from
+   */
+  roaring_bitmap_storage(roaring_bitmap_storage const& other) = default;
+
+  /**
+   * @brief Move constructor
+   *
+   * @param other The roaring_bitmap_storage to move from
+   */
+  roaring_bitmap_storage(roaring_bitmap_storage&& other) = default;
+
+  /**
+   * @brief Copy assignment operator
+   *
+   * @param other The roaring_bitmap_storage to copy from
+   * @return Reference to this roaring_bitmap_storage
+   */
   roaring_bitmap_storage& operator=(roaring_bitmap_storage const& other) = default;
-  roaring_bitmap_storage& operator=(roaring_bitmap_storage&& other)      = default;
+
+  /**
+   * @brief Move assignment operator
+   *
+   * @param other The roaring_bitmap_storage to move from
+   * @return Reference to this roaring_bitmap_storage
+   */
+  roaring_bitmap_storage& operator=(roaring_bitmap_storage&& other) = default;
 
   ~roaring_bitmap_storage() = default;
 
+  /**
+   * @brief Constructs storage by copying bitmap data to device memory
+   *
+   * @param bitmap Pointer to the serialized bitmap data in host memory
+   * @param alloc Allocator for device memory allocation
+   * @param stream CUDA stream for memory operations
+   */
   roaring_bitmap_storage(cuda::std::byte const* bitmap,
                          Allocator const& alloc,
                          cuda::stream_ref stream)
@@ -210,6 +386,11 @@ class roaring_bitmap_storage<cuda::std::uint64_t, Allocator> {
       stream.get()));
   }
 
+  /**
+   * @brief Returns a reference to the stored bitmap
+   *
+   * @return Reference to the bitmap storage
+   */
   ref_type ref() const noexcept { return ref_; }
 
  private: