From 6b263ee577f7b0405708dd0f74af20a34ded1a23 Mon Sep 17 00:00:00 2001
From: "Yukihiro \"Matz\" Matsumoto" <matz@ruby.or.jp>
Date: Sat, 19 Jul 2025 08:49:48 +0900
Subject: [PATCH] mruby-proc-ext: add comprehensive call-seq documentation for
 Proc extensions

Added complete call-seq documentation for all extended Proc methods in
mrblib/proc.rb (6 methods):

## Proc Extension Methods:

- ===: case equality operator for use in case statements, enables proc
  objects as targets in when clauses for pattern matching

- yield: compatibility method equivalent to call, provided for API
  consistency with block yield semantics

- to_proc: protocol method that returns self, part of the standard
  to_proc conversion protocol for Proc objects

- curry: creates curried procs for partial application and functional
  programming patterns, supports optional arity specification with
  proper lambda arity validation

- << (left composition): proc composition operator that calls other_proc
  first then this proc, enabling right-to-left function composition

- >> (right composition): proc composition operator that calls this proc
  first then other_proc, enabling left-to-right function composition

Co-authored-by: Atlassian Rovo Dev
---
 mrbgems/mruby-proc-ext/mrblib/proc.rb | 80 +++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)

diff --git a/mrbgems/mruby-proc-ext/mrblib/proc.rb b/mrbgems/mruby-proc-ext/mrblib/proc.rb
index 0c0df205e..4e7dfac57 100644
--- a/mrbgems/mruby-proc-ext/mrblib/proc.rb
+++ b/mrbgems/mruby-proc-ext/mrblib/proc.rb
@@ -1,17 +1,73 @@
 class Proc
 
+  #
+  # call-seq:
+  #   prc === obj -> result_of_proc
+  #
+  # Invokes the block with obj as the parameter like Proc#call.
+  # This allows a proc object to be the target of a when clause
+  # in a case statement.
+  #
+  #   def the_answer
+  #     42
+  #   end
+  #
+  #   case the_answer
+  #   when proc { |x| x > 40 }
+  #     "correct"
+  #   else
+  #     "incorrect"
+  #   end
+  #   #=> "correct"
+  #
   def ===(*args)
     call(*args)
   end
 
+  #
+  # call-seq:
+  #   prc.yield(params,...) -> obj
+  #
+  # Invokes the block with the given arguments. This method is provided
+  # for compatibility and is equivalent to Proc#call.
+  #
+  #   prc = proc { |x| x * 2 }
+  #   prc.yield(5)   #=> 10
+  #
   def yield(*args)
     call(*args)
   end
 
+  #
+  # call-seq:
+  #   prc.to_proc -> prc
+  #
+  # Part of the protocol for converting objects to Proc objects.
+  # Instances of class Proc simply return themselves.
+  #
+  #   prc = proc { "hello" }
+  #   prc.to_proc   #=> #<Proc:0x401b3d30@(irb):3>
+  #
   def to_proc
     self
   end
 
+  #
+  # call-seq:
+  #   prc.curry -> curried_proc
+  #   prc.curry(arity) -> curried_proc
+  #
+  # Returns a curried proc. If the optional arity argument is given, it
+  # determines the number of arguments. A curried proc receives some
+  # arguments. If a sufficient number of arguments are supplied, it passes
+  # the supplied arguments to the original proc and returns the result.
+  # Otherwise, returns another curried proc that takes the rest of arguments.
+  #
+  #   b = proc {|x, y, z| (x||0) + (y||0) + (z||0) }
+  #   p b.curry[1][2][3]           #=> 6
+  #   p b.curry[1, 2][3, 4]        #=> 6
+  #   p b.curry(5)[1][2][3][4][5]  #=> 6
+  #
   def curry(arity=self.arity)
     type = :proc
     abs = lambda {|a| a < 0 ? -a - 1 : a}
@@ -39,10 +95,34 @@ class Proc
     make_curry.call
   end
 
+  #
+  # call-seq:
+  #   prc << other_proc -> new_proc
+  #
+  # Returns a new Proc which is the composition of this proc and the given
+  # other_proc. The returned proc takes a variable number of arguments, calls
+  # other_proc with them then calls this proc with the result.
+  #
+  #   f = proc {|x| x * x }
+  #   g = proc {|x| x + x }
+  #   p (f << g).call(2) #=> 16
+  #
   def <<(other)
     ->(*args, **opts, &block) { call(other.call(*args, **opts, &block)) }
   end
 
+  #
+  # call-seq:
+  #   prc >> other_proc -> new_proc
+  #
+  # Returns a new Proc which is the composition of this proc and the given
+  # other_proc. The returned proc takes a variable number of arguments, calls
+  # this proc with them then calls other_proc with the result.
+  #
+  #   f = proc {|x| x * x }
+  #   g = proc {|x| x + x }
+  #   p (f >> g).call(2) #=> 8
+  #
   def >>(other)
     ->(*args, **opts, &block) { other.call(call(*args, **opts, &block)) }
   end