Add a bunch of documentation

.yardopts

@@ -0,0 +1 @@
+--embed-mixins --no-private

Gemfile

@@ -11,3 +11,5 @@ gem "rake-compiler"
 gem "debug"
 
 gem "minitest", "~> 5.0"
+
+gem "yard"

Gemfile.lock

@@ -23,6 +23,7 @@ GEM
     reline (0.3.1)
       io-console (~> 0.5)
     singleton (0.1.1)
+    yard (0.9.36)
 
 PLATFORMS
   arm64-darwin-23
@@ -35,6 +36,7 @@ DEPENDENCIES
   rake (~> 13.0)
   rake-compiler
   roaring!
+  yard
 
 BUNDLED WITH
    2.3.4

Rakefile

@@ -3,6 +3,12 @@
 require "bundler/gem_tasks"
 require "rake/testtask"
 
+require "yard"
+
+YARD::Rake::YardocTask.new do |t|
+  t.files = ["lib/**/*.rb", "ext/**/*.c"]
+end
+
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"

ext/roaring/bitmap32.c

@@ -48,6 +48,7 @@ static roaring_bitmap_t *get_bitmap(VALUE obj) {
     return bitmap;
 }
 
+// Replaces the contents of `self` with another bitmap
 static VALUE rb_roaring32_replace(VALUE self, VALUE other) {
     roaring_bitmap_t *self_data = get_bitmap(self);
     roaring_bitmap_t *other_data = get_bitmap(other);
@@ -57,13 +58,16 @@ static VALUE rb_roaring32_replace(VALUE self, VALUE other) {
     return self;
 }
 
+// @return [Integer] the number of elements in the bitmap
 static VALUE rb_roaring32_cardinality(VALUE self)
 {
     roaring_bitmap_t *data = get_bitmap(self);
     uint64_t cardinality = roaring_bitmap_get_cardinality(data);
     return ULONG2NUM(cardinality);
 }
 
+// Adds an element from the bitmap
+// @param val [Integer] the value to add
 static VALUE rb_roaring32_add(VALUE self, VALUE val)
 {
     roaring_bitmap_t *data = get_bitmap(self);
@@ -73,6 +77,9 @@ static VALUE rb_roaring32_add(VALUE self, VALUE val)
     return self;
 }
 
+// Adds an element from the bitmap
+// @see {add}
+// @return `self` if value was add, `nil` if value was already in the bitmap
 static VALUE rb_roaring32_add_p(VALUE self, VALUE val)
 {
     roaring_bitmap_t *data = get_bitmap(self);
@@ -81,6 +88,7 @@ static VALUE rb_roaring32_add_p(VALUE self, VALUE val)
     return roaring_bitmap_add_checked(data, num) ? self : Qnil;
 }
 
+// Removes an element from the bitmap
 static VALUE rb_roaring32_remove(VALUE self, VALUE val)
 {
     roaring_bitmap_t *data = get_bitmap(self);
@@ -90,6 +98,10 @@ static VALUE rb_roaring32_remove(VALUE self, VALUE val)
     return self;
 }
 
+// Removes an element from the bitmap
+//
+// @see {remove}
+// @return [self,nil] `self` if value was removed, `nil` if the value wasn't in the bitmap
 static VALUE rb_roaring32_remove_p(VALUE self, VALUE val)
 {
     roaring_bitmap_t *data = get_bitmap(self);
@@ -98,6 +110,7 @@ static VALUE rb_roaring32_remove_p(VALUE self, VALUE val)
     return roaring_bitmap_remove_checked(data, num) ? self : Qnil;
 }
 
+// @return [Boolean] `true` if the bitmap is contains `val`, otherwise `false`
 static VALUE rb_roaring32_include_p(VALUE self, VALUE val)
 {
     roaring_bitmap_t *data = get_bitmap(self);
@@ -106,12 +119,14 @@ static VALUE rb_roaring32_include_p(VALUE self, VALUE val)
     return RBOOL(roaring_bitmap_contains(data, num));
 }
 
+// @return [Boolean] `true` if the bitmap is empty, otherwise `false`
 static VALUE rb_roaring32_empty_p(VALUE self)
 {
     roaring_bitmap_t *data = get_bitmap(self);
     return RBOOL(roaring_bitmap_is_empty(data));
 }
 
+// Removes all elements from the bitmap
 static VALUE rb_roaring32_clear(VALUE self)
 {
     roaring_bitmap_t *data = get_bitmap(self);
@@ -124,13 +139,17 @@ bool rb_roaring32_each_i(uint32_t value, void *param) {
     return true;  // iterate till the end
 }
 
+// Iterates over every element in the bitmap
+// @return [self]
 static VALUE rb_roaring32_each(VALUE self)
 {
     roaring_bitmap_t *data = get_bitmap(self);
     roaring_iterate(data, rb_roaring32_each_i, NULL);
     return self;
 }
 
+// Find the nth smallest integer in the bitmap
+// @return [Integer,nil] The nth integer in the bitmap, or `nil` if `rankv` is `>= cardinality`
 static VALUE rb_roaring32_aref(VALUE self, VALUE rankv)
 {
     roaring_bitmap_t *data = get_bitmap(self);
@@ -146,6 +165,8 @@ static VALUE rb_roaring32_aref(VALUE self, VALUE rankv)
     return self;
 }
 
+// Find the smallest integer in the bitmap
+// @return [Integer,nil] The smallest integer in the bitmap, or `nil` if it is empty
 static VALUE rb_roaring32_min(VALUE self)
 {
     roaring_bitmap_t *data = get_bitmap(self);
@@ -158,6 +179,8 @@ static VALUE rb_roaring32_min(VALUE self)
     }
 }
 
+// Find the largest integer in the bitmap
+// @return [Integer,nil] The largest integer in the bitmap, or `nil` if it is empty
 static VALUE rb_roaring32_max(VALUE self)
 {
     roaring_bitmap_t *data = get_bitmap(self);
@@ -170,12 +193,16 @@ static VALUE rb_roaring32_max(VALUE self)
     }
 }
 
+// Attemps to internally optimize the representation of bitmap by finding runs, consecutive sequences of integers.
+// @return [Boolean] whether the result has at least one run container
 static VALUE rb_roaring32_run_optimize(VALUE self)
 {
     roaring_bitmap_t *data = get_bitmap(self);
     return RBOOL(roaring_bitmap_run_optimize(data));
 }
 
+// Serializes a bitmap into a string
+// @return [string]
 static VALUE rb_roaring32_serialize(VALUE self)
 {
     roaring_bitmap_t *data = get_bitmap(self);
@@ -189,13 +216,17 @@ static VALUE rb_roaring32_serialize(VALUE self)
     return str;
 }
 
+// Loads a previously serialized bitmap
+// @return [Bitmap32]
 static VALUE rb_roaring32_deserialize(VALUE self, VALUE str)
 {
     roaring_bitmap_t *bitmap = roaring_bitmap_portable_deserialize_safe(RSTRING_PTR(str), RSTRING_LEN(str));
 
     return TypedData_Wrap_Struct(cRoaringBitmap32, &roaring_type, bitmap);
 }
 
+// Provides statistics about the internal layout of the bitmap
+// @return [Hash]
 static VALUE rb_roaring32_statistics(VALUE self)
 {
     roaring_bitmap_t *data = get_bitmap(self);
@@ -257,61 +288,85 @@ static VALUE rb_roaring32_binary_op_bool(VALUE self, VALUE other, binary_func_bo
     return RBOOL(result);
 }
 
+// Inplace version of {and}
+// @return [self] the modified Bitmap
 static VALUE rb_roaring32_and_inplace(VALUE self, VALUE other)
 {
     return rb_roaring32_binary_op_inplace(self, other, roaring_bitmap_and_inplace);
 }
 
+// Inplace version of {or}
+// @return [self] the modified Bitmap
 static VALUE rb_roaring32_or_inplace(VALUE self, VALUE other)
 {
     return rb_roaring32_binary_op_inplace(self, other, roaring_bitmap_or_inplace);
 }
 
+// Inplace version of {xor}
+// @return [self] the modified Bitmap
 static VALUE rb_roaring32_xor_inplace(VALUE self, VALUE other)
 {
     return rb_roaring32_binary_op_inplace(self, other, roaring_bitmap_xor_inplace);
 }
 
+// Inplace version of {andnot}
+// @return [self] the modified Bitmap
 static VALUE rb_roaring32_andnot_inplace(VALUE self, VALUE other)
 {
     return rb_roaring32_binary_op_inplace(self, other, roaring_bitmap_andnot_inplace);
 }
 
+// Computes the intersection between two bitmaps
+// @return [Bitmap32] a new bitmap containing all elements in both `self` and `other`
 static VALUE rb_roaring32_and(VALUE self, VALUE other)
 {
     return rb_roaring32_binary_op(self, other, roaring_bitmap_and);
 }
 
+// Computes the union between two bitmaps
+// @return [Bitmap32] a new bitmap containing all elements in either `self` or `other`
 static VALUE rb_roaring32_or(VALUE self, VALUE other)
 {
     return rb_roaring32_binary_op(self, other, roaring_bitmap_or);
 }
 
+// Computes the exclusive or between two bitmaps
+// @return [Bitmap32] a new bitmap containing all elements in one of `self` or `other`, but not both
 static VALUE rb_roaring32_xor(VALUE self, VALUE other)
 {
     return rb_roaring32_binary_op(self, other, roaring_bitmap_xor);
 }
 
+// Computes the difference between two bitmaps
+// @return [Bitmap32] a new bitmap containing all elements in `self`, but not in `other`
 static VALUE rb_roaring32_andnot(VALUE self, VALUE other)
 {
     return rb_roaring32_binary_op(self, other, roaring_bitmap_andnot);
 }
 
+// Compare equality between two bitmaps
+// @return [Boolean] `true` if both bitmaps contain all the same elements, otherwise `false`
 static VALUE rb_roaring32_eq(VALUE self, VALUE other)
 {
     return rb_roaring32_binary_op_bool(self, other, roaring_bitmap_equals);
 }
 
+// Check if `self` is a strict subset of `other`. A strict subset requires every element in `self` is also in `other`, but they aren't exactly equal.
+// @return [Boolean] `true` if `self` is a strict subset of `other`, otherwise `false`
 static VALUE rb_roaring32_lt(VALUE self, VALUE other)
 {
     return rb_roaring32_binary_op_bool(self, other, roaring_bitmap_is_strict_subset);
 }
 
+// Check if `self` is a (non-strict) subset of `other`. A subset requires that every element in `self` is also in `other`. They may be equal.
+// @return [Boolean] `true` if `self` is a subset of `other`, otherwise `false`
 static VALUE rb_roaring32_lte(VALUE self, VALUE other)
 {
     return rb_roaring32_binary_op_bool(self, other, roaring_bitmap_is_subset);
 }
 
+// Checks whether `self` intersects `other`
+// @return [Boolean] `true` if `self` intersects `other`, otherwise `false`
 static VALUE rb_roaring32_intersect_p(VALUE self, VALUE other)
 {
     return rb_roaring32_binary_op_bool(self, other, roaring_bitmap_intersect);
@@ -328,7 +383,6 @@ rb_roaring32_init(void)
   rb_define_method(cRoaringBitmap32, "cardinality", rb_roaring32_cardinality, 0);
   rb_define_method(cRoaringBitmap32, "add", rb_roaring32_add, 1);
   rb_define_method(cRoaringBitmap32, "add?", rb_roaring32_add_p, 1);
-  rb_define_method(cRoaringBitmap32, "<<", rb_roaring32_add, 1);
   rb_define_method(cRoaringBitmap32, "remove", rb_roaring32_remove, 1);
   rb_define_method(cRoaringBitmap32, "remove?", rb_roaring32_remove_p, 1);
   rb_define_method(cRoaringBitmap32, "include?", rb_roaring32_include_p, 1);