From bde6b61fd2942f71cd7323413be2b374e86b57cb Mon Sep 17 00:00:00 2001
From: Burdette Lamar <BurdetteLamar@Yahoo.com>
Date: Sun, 28 Jun 2026 12:44:51 -0500
Subject: [PATCH 1/5] [DOC] Update Set#empty? documentation

---
 set.c | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/set.c b/set.c
index 97357ba62a23af..10cc5a135e12de 100644
--- a/set.c
+++ b/set.c
@@ -1315,7 +1315,12 @@ set_i_size(VALUE set)
  *  call-seq:
  *    empty? -> true or false
  *
- *  Returns true if the set contains no elements.
+ *  Returns whether +self+ contains no elements:
+ *
+ *    Set[].empty?  # => true
+ *    Set[0].empty? # => false
+ *
+ *  Related: see {Methods for Querying}[rdoc-ref:Set@Methods+for+Querying].
  */
 static VALUE
 set_i_empty(VALUE set)

From f3009a1e2a62efaad717500c83cb2381959defec Mon Sep 17 00:00:00 2001
From: Burdette Lamar <BurdetteLamar@Yahoo.com>
Date: Sun, 28 Jun 2026 12:46:17 -0500
Subject: [PATCH 2/5] [DOC] Update Set#flatten documentation

---
 set.c | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)

diff --git a/set.c b/set.c
index 10cc5a135e12de..031736994c4977 100644
--- a/set.c
+++ b/set.c
@@ -1663,10 +1663,23 @@ set_flatten_merge(VALUE set, VALUE from, VALUE hash)
 
 /*
  *  call-seq:
- *    flatten -> set
+ *    flatten -> new_set
  *
- *  Returns a new set that is a copy of the set, flattening each
- *  containing set recursively.
+ *  Returns a new set that is a copy of +self+,
+ *  but with +self+ and its nested sets flattened;
+ *  that is, their elements become elements of +self+:
+ *
+ *    Set[Set[0, 1], Set[2, 3]].flatten
+ *    # => Set[0, 1, 2, 3]
+ *    Set[Set[0, 1], Set[Set[2, 3], Set[3, 4]]].flatten
+ *    # => Set[0, 1, 2, 3, 4]
+ *
+ *  Does not flatten nested arrays or hashes:
+ *
+ *    Set[%w[foo bar]].flatten      # => Set[["foo", "bar"]]
+ *    Set[{foo: 0, bar: 1}].flatten # => Set[{foo: 0, bar: 1}]
+ *
+ *  Related: see {Methods for Converting}[rdoc-ref:Set@Methods+for+Converting].
  */
 static VALUE
 set_i_flatten(VALUE set)

From 73a6e69de16fa1a56b78a260f5b06aecaba1f184 Mon Sep 17 00:00:00 2001
From: Burdette Lamar <BurdetteLamar@Yahoo.com>
Date: Sun, 28 Jun 2026 12:48:05 -0500
Subject: [PATCH 3/5] [DOC] Update Set#flatten! documentation

---
 set.c | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/set.c b/set.c
index 031736994c4977..4bea6a2d8029d7 100644
--- a/set.c
+++ b/set.c
@@ -1701,10 +1701,21 @@ set_contains_set_i(st_data_t item, st_data_t arg)
 
 /*
  *  call-seq:
- *    flatten! -> self
+ *    flatten! -> self or nil
  *
- *  Equivalent to Set#flatten, but replaces the receiver with the
- *  result in place.  Returns nil if no modifications were made.
+ *  Like #flatten, but if any changes were made
+ *  replaces +self+ with the result and returns +self+:
+ *
+ *    Set[Set[0, 1], Set[2, 3]].flatten!
+ *    # => Set[0, 1, 2, 3]
+ *    Set[Set[0, 1], Set[Set[2, 3], Set[3, 4]]].flatten!
+ *    # => Set[0, 1, 2, 3, 4]
+ *
+ *  Returns +nil+ if no changes were made:
+ *
+ *    Set[0, 1, 2].flatten! # => nil
+ *
+ *  Related: see {Methods for Assigning}[rdoc-ref:Set@Methods+for+Assigning].
  */
 static VALUE
 set_i_flatten_bang(VALUE set)

From 40c2f61195ec661dedb214c337e11040c7a4dcd5 Mon Sep 17 00:00:00 2001
From: Burdette Lamar <BurdetteLamar@Yahoo.com>
Date: Sun, 28 Jun 2026 13:00:48 -0500
Subject: [PATCH 4/5] [DOC] Update Set#inspect documentation

---
 set.c | 12 ++++--------
 1 file changed, 4 insertions(+), 8 deletions(-)

diff --git a/set.c b/set.c
index 4bea6a2d8029d7..b06240f8d45b8e 100644
--- a/set.c
+++ b/set.c
@@ -621,16 +621,12 @@ set_inspect(VALUE set, VALUE dummy, int recur)
 
 /*
  *  call-seq:
- *    inspect -> new_string
+ *    inspect -> string
  *
- *  Returns a new string containing the set entries:
+ *  Returns a string representation of +self+:
  *
- *    s = Set.new
- *    s.inspect # => "Set[]"
- *    s.add(1)
- *    s.inspect # => "Set[1]"
- *    s.add(2)
- *    s.inspect # => "Set[1, 2]"
+ *    Set[*%w[foo bar], {foo: 0, bar: 1}].inspect
+ *    # => "Set[\"foo\", \"bar\", {foo: 0, bar: 1}]"
  *
  *  Related: see {Methods for Converting}[rdoc-ref:Set@Methods+for+Converting].
  */

From cf979af0af8a0de1ccb3454a2cc7b2263c3bf5cf Mon Sep 17 00:00:00 2001
From: Burdette Lamar <BurdetteLamar@Yahoo.com>
Date: Sun, 28 Jun 2026 13:02:23 -0500
Subject: [PATCH 5/5] [DOC] Update Set#intersect? documentation

---
 set.c | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/set.c b/set.c
index b06240f8d45b8e..134770e70ab0ae 100644
--- a/set.c
+++ b/set.c
@@ -1817,15 +1817,16 @@ set_intersect_i(st_data_t key, st_data_t arg)
 
 /*
  *  call-seq:
- *    intersect?(set) -> true or false
+ *    intersect?(enumerable) -> true or false
  *
- *  Returns true if the set and the given enumerable have at least one
- *  element in common.
+ *  Returns whether +self+ and +enumerable+ have any elements in common:
  *
- *    Set[1, 2, 3].intersect? Set[4, 5]   #=> false
- *    Set[1, 2, 3].intersect? Set[3, 4]   #=> true
- *    Set[1, 2, 3].intersect? 4..5        #=> false
- *    Set[1, 2, 3].intersect? [3, 4]      #=> true
+ *    set = Set[0, 'zero', :zero]
+ *    set.intersect?([0, 1, 2])        # => true
+ *    set.intersect?(%w[zero one two]) # => true
+ *    set.intersect?(Set[3])           # => false
+ *
+ *  Related: see {Methods for Querying}[rdoc-ref:Set@Methods+for+Querying].
  */
 static VALUE
 set_i_intersect(VALUE set, VALUE other)