[DOC] Clarify Class#subclases behavior quirks

As per discussion in [Feature #18273], explain the
non-deterministic nature of the method.

1 files changed, 21 insertions, 0 deletions

diff --git a/class.c b/class.c
index 55bc761ebe..847c4d0a57 100644
--- a/class.c
+++ b/class.c
@@ -1572,6 +1572,27 @@ class_descendants(VALUE klass, bool immediate_only)
  *     A.subclasses        #=> [D, B]
  *     B.subclasses        #=> [C]
  *     C.subclasses        #=> []
+ *
+ *  Anonymous subclasses (not associated with a constant) are
+ *  returned, too:
+ *
+ *     c = Class.new(A)
+ *     A.subclasses        # => [#<Class:0x00007f003c77bd78>, D, B]
+ *
+ *  Note that the parent does not hold references to subclasses
+ *  and doesn't prevent them from being garbage collected. This
+ *  means that the subclass might disappear when all references
+ *  to it are dropped:
+ *
+ *     # drop the reference to subclass, it can be garbage-collected now
+ *     c = nil
+ *
+ *     A.subclasses
+ *     # It can be
+ *     #  => [#<Class:0x00007f003c77bd78>, D, B]
+ *     # ...or just
+ *     #  => [D, B]
+ *     # ...depending on whether garbage collector was run
  */
 
 VALUE