From 6f35e05350de789a42a5a4fbad3052d645b17f62 Mon Sep 17 00:00:00 2001
From: "Yukihiro \"Matz\" Matsumoto" <matz@ruby.or.jp>
Date: Sat, 19 Jul 2025 10:34:32 +0900
Subject: [PATCH] mruby-enum-chain: add comprehensive call-seq documentation
 for enumerator chaining

Added complete call-seq documentation for all enumerator chain methods in
mrblib/chain.rb (8 methods):

## Enumerable Extension Methods:

- chain: creates Enumerator::Chain from multiple enumerables for sequential
  iteration, enabling fluent chaining of enumerable objects

## Enumerator Extension Methods:

- +: operator overload for creating chains from two enumerators, provides
  convenient syntax for combining enumerators

## Enumerator::Chain Class Methods:

- new: constructor for creating chain from multiple enumerable arguments,
  stores enumerables and initializes position tracking

## Enumerator::Chain Instance Methods:

- each: core iteration method that sequentially processes all chained
  enumerables, supports both block and enumerator return modes

- size: calculates total size across all chained enumerables, returns nil
  if any enumerable doesn't support size method

- rewind: resets iteration state by rewinding all previously iterated
  enumerables in reverse order, maintains proper state management

- +: creates new chain by appending additional enumerable to existing chain,
  enables further composition of enumerator chains

- inspect: provides debugging representation showing internal enumerable
  structure for development and troubleshooting

Co-authored-by: Atlassian Rovo Dev
---
 mrbgems/mruby-enum-chain/mrblib/chain.rb | 87 ++++++++++++++++++++++++
 1 file changed, 87 insertions(+)

diff --git a/mrbgems/mruby-enum-chain/mrblib/chain.rb b/mrbgems/mruby-enum-chain/mrblib/chain.rb
index 43d0926c8..fb0dac66b 100644
--- a/mrbgems/mruby-enum-chain/mrblib/chain.rb
+++ b/mrbgems/mruby-enum-chain/mrblib/chain.rb
@@ -3,12 +3,33 @@
 # See Copyright Notice in mruby.h
 
 module Enumerable
+  #
+  # call-seq:
+  #   enum.chain(*enums) -> enumerator_chain
+  #
+  # Returns an Enumerator::Chain object which can enumerate over this
+  # enumerable and the given enumerables in sequence.
+  #
+  #   e = (1..3).chain([4, 5])
+  #   e.to_a  #=> [1, 2, 3, 4, 5]
+  #
   def chain(*args)
     Enumerator::Chain.new(self, *args)
   end
 end
 
 class Enumerator
+  #
+  # call-seq:
+  #   enum + other_enum -> enumerator_chain
+  #
+  # Returns an Enumerator::Chain object which can enumerate over this
+  # enumerator and the given enumerator in sequence.
+  #
+  #   e1 = (1..3).each
+  #   e2 = [4, 5].each
+  #   (e1 + e2).to_a  #=> [1, 2, 3, 4, 5]
+  #
   def +(other)
     Chain.new(self, other)
   end
@@ -16,11 +37,34 @@ class Enumerator
   class Chain
     include Enumerable
 
+    #
+    # call-seq:
+    #   Enumerator::Chain.new(*enums) -> enumerator_chain
+    #
+    # Generates a new enumerator which iterates over each one of the
+    # given enumerable objects in sequence.
+    #
+    #   e = Enumerator::Chain.new(1..3, [4, 5])
+    #   e.to_a  #=> [1, 2, 3, 4, 5]
+    #
     def initialize(*args)
       @enums = args.freeze
       @pos = -1
     end
 
+    #
+    # call-seq:
+    #   chain.each { |obj| block } -> chain
+    #   chain.each                 -> enumerator
+    #
+    # Iterates over the elements of the first enumerable by calling the
+    # each method on it with the given block, then proceeds to the next
+    # enumerable in the chain and continues until the end.
+    #
+    #   e = Enumerator::Chain.new(1..3, [4, 5])
+    #   e.each { |x| puts x }
+    #   # prints: 1, 2, 3, 4, 5
+    #
     def each(&block)
       return to_enum unless block
 
@@ -34,6 +78,16 @@ class Enumerator
       self
     end
 
+    #
+    # call-seq:
+    #   chain.size -> integer or nil
+    #
+    # Returns the total size of the enumerator chain if all of the
+    # chained enumerables define size. Otherwise it returns nil.
+    #
+    #   Enumerator::Chain.new(1..3, [4, 5]).size  #=> 5
+    #   Enumerator::Chain.new(1..3, loop).size    #=> nil
+    #
     def size
       @enums.reduce(0) do |a, e|
         return nil unless e.respond_to?(:size)
@@ -41,6 +95,19 @@ class Enumerator
       end
     end
 
+    #
+    # call-seq:
+    #   chain.rewind -> chain
+    #
+    # Rewinds the enumerator chain by calling the rewind method on each
+    # enumerable that has been iterated, in reverse order. Each enumerable
+    # that defines a rewind method will be rewound.
+    #
+    #   e = Enumerator::Chain.new((1..3), [4, 5])
+    #   e.next  #=> 1
+    #   e.rewind
+    #   e.next  #=> 1
+    #
     def rewind
       while 0 <= @pos && @pos < @enums.size
         e = @enums[@pos]
@@ -51,10 +118,30 @@ class Enumerator
       self
     end
 
+    #
+    # call-seq:
+    #   chain + other_enum -> enumerator_chain
+    #
+    # Returns a new Enumerator::Chain object which will enumerate over the
+    # elements of this chain, followed by the elements of other_enum.
+    #
+    #   e1 = Enumerator::Chain.new(1..3, [4, 5])
+    #   e2 = e1 + [6, 7]
+    #   e2.to_a  #=> [1, 2, 3, 4, 5, 6, 7]
+    #
     def +(other)
       self.class.new(self, other)
     end
 
+    #
+    # call-seq:
+    #   chain.inspect -> string
+    #
+    # Returns a printable version of the enumerator chain.
+    #
+    #   Enumerator::Chain.new(1..3, [4, 5]).inspect
+    #   #=> "#<Enumerator::Chain: [1..3, [4, 5]]>"
+    #
     def inspect
       "#<#{self.class}: #{@enums.inspect}>"
     end