From 4ab07c74d6963d38a371f7fc32d0df7ea2be58bd Mon Sep 17 00:00:00 2001
From: "Yukihiro \"Matz\" Matsumoto" <matz@ruby.or.jp>
Date: Sat, 19 Jul 2025 12:39:28 +0900
Subject: [PATCH] mruby-method: add comprehensive call-seq documentation for
 Method extensions

Added complete call-seq documentation for all Method extension methods in
mrblib/method.rb (3 methods):

## Method Extension Methods:

- to_proc: converts Method object to Proc for functional programming
  patterns, enables use with &: syntax for concise method references
  and supports full argument passing including blocks and keyword arguments

- << (left composition): method composition operator that calls other_proc
  first then this method, enables right-to-left function composition with
  mathematical notation f(g(x)) for building complex transformations

- >> (right composition): method composition operator that calls this method
  first then other_proc, enables left-to-right function composition with
  pipeline notation for intuitive data flow transformations

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

diff --git a/mrbgems/mruby-method/mrblib/method.rb b/mrbgems/mruby-method/mrblib/method.rb
index 09b611eb7..efb1d5b35 100644
--- a/mrbgems/mruby-method/mrblib/method.rb
+++ b/mrbgems/mruby-method/mrblib/method.rb
@@ -1,4 +1,23 @@
 class Method
+  #
+  # call-seq:
+  #   meth.to_proc -> proc
+  #
+  # Returns a Proc object corresponding to this method.
+  #
+  #   class Foo
+  #     def bar
+  #       "baz"
+  #     end
+  #   end
+  #
+  #   m = Foo.new.method(:bar)
+  #   p = m.to_proc
+  #   p.call  #=> "baz"
+  #
+  #   # Can be used with &:
+  #   %w[hello world].map(&:upcase)  #=> ["HELLO", "WORLD"]
+  #
   def to_proc
     m = self
     lambda { |*args, **opts, &b|
@@ -6,10 +25,48 @@ class Method
     }
   end
 
+  #
+  # call-seq:
+  #   meth << other_proc -> proc
+  #
+  # Returns a proc that is the composition of this method and the given
+  # other_proc. The returned proc takes a variable number of arguments,
+  # calls other_proc with them then calls this method with the result.
+  #
+  #   def f(x)
+  #     x * x
+  #   end
+  #
+  #   def g(x)
+  #     x + x
+  #   end
+  #
+  #   # (f << g).call(2) == f(g(2)) == f(4) == 16
+  #   p (method(:f) << method(:g)).call(2)  #=> 16
+  #
   def <<(other)
     ->(*args, **opts, &block) { call(other.call(*args, **opts, &block)) }
   end
 
+  #
+  # call-seq:
+  #   meth >> other_proc -> proc
+  #
+  # Returns a proc that is the composition of this method and the given
+  # other_proc. The returned proc takes a variable number of arguments,
+  # calls this method with them then calls other_proc with the result.
+  #
+  #   def f(x)
+  #     x * x
+  #   end
+  #
+  #   def g(x)
+  #     x + x
+  #   end
+  #
+  #   # (f >> g).call(2) == g(f(2)) == g(4) == 8
+  #   p (method(:f) >> method(:g)).call(2)  #=> 8
+  #
   def >>(other)
     ->(*args, **opts, &block) { other.call(call(*args, **opts, &block)) }
   end