From 242936a90b2b2226faa7b80e1cc259205f5a9fc0 Mon Sep 17 00:00:00 2001
From: "Yukihiro \"Matz\" Matsumoto" <matz@ruby.or.jp>
Date: Thu, 17 Jul 2025 12:51:35 +0900
Subject: [PATCH] mruby-binding: add comprehensive documentation with examples
 for binding methods

Enhanced documentation for Binding class methods with detailed examples:

- local_variable_defined?: Added examples showing usage within methods and at
  top-level, including interaction with local_variable_set
- local_variable_get: Added examples demonstrating retrieval of different data
  types, variable modification tracking, and NameError behavior
- local_variable_set: Added examples showing variable assignment and creation
- local_variables: Added examples showing array of local variable names
- receiver: Added examples showing bound receiver object access
- binding (Kernel method): Added examples showing binding creation and usage

Co-authored-by: Atlassian Rovo Dev
---
 mrbgems/mruby-binding/src/binding.c | 90 +++++++++++++++++++++++++++++
 1 file changed, 90 insertions(+)

diff --git a/mrbgems/mruby-binding/src/binding.c b/mrbgems/mruby-binding/src/binding.c
index 05a068a0e..34e089248 100644
--- a/mrbgems/mruby-binding/src/binding.c
+++ b/mrbgems/mruby-binding/src/binding.c
@@ -240,6 +240,23 @@ binding_local_variable_search(mrb_state *mrb, const struct RProc *proc, struct R
 /*
  * call-seq:
  *  local_variable_defined?(symbol) -> bool
+ *
+ * Returns true if a local variable with the given name is defined
+ * in the binding's context, false otherwise.
+ *
+ *   def foo
+ *     a = 1
+ *     b = binding
+ *     b.local_variable_defined?(:a)  #=> true
+ *     b.local_variable_defined?(:c)  #=> false
+ *   end
+ *
+ *   x = 10
+ *   bind = binding
+ *   bind.local_variable_defined?(:x)     #=> true
+ *   bind.local_variable_defined?(:y)     #=> false
+ *   bind.local_variable_set(:y, 20)
+ *   bind.local_variable_defined?(:y)     #=> true
  */
 static mrb_value
 binding_local_variable_defined_p(mrb_state *mrb, mrb_value self)
@@ -261,6 +278,25 @@ binding_local_variable_defined_p(mrb_state *mrb, mrb_value self)
 /*
  * call-seq:
  *  local_variable_get(symbol) -> object
+ *
+ * Returns the value of the local variable with the given name
+ * in the binding's context. Raises NameError if the variable
+ * is not defined.
+ *
+ *   def foo
+ *     a = 42
+ *     b = "hello"
+ *     bind = binding
+ *     bind.local_variable_get(:a)  #=> 42
+ *     bind.local_variable_get(:b)  #=> "hello"
+ *     bind.local_variable_get(:c)  #=> NameError
+ *   end
+ *
+ *   x = [1, 2, 3]
+ *   bind = binding
+ *   bind.local_variable_get(:x)      #=> [1, 2, 3]
+ *   x = "modified"
+ *   bind.local_variable_get(:x)      #=> "modified"
  */
 static mrb_value
 binding_local_variable_get(mrb_state *mrb, mrb_value self)
@@ -278,6 +314,20 @@ binding_local_variable_get(mrb_state *mrb, mrb_value self)
   return *e;
 }
 
+/*
+ * call-seq:
+ *   binding.local_variable_set(symbol, obj) -> obj
+ *
+ * Set local variable named symbol as obj in binding's context.
+ * If the variable is not defined in the binding, it will be created.
+ *
+ *   def foo
+ *     a = 1
+ *     binding.local_variable_set(:a, 2)
+ *     binding.local_variable_set(:b, 3)
+ *     [a, b]  #=> [2, 3]
+ *   end
+ */
 static mrb_value
 binding_local_variable_set(mrb_state *mrb, mrb_value self)
 {
@@ -301,6 +351,19 @@ binding_local_variable_set(mrb_state *mrb, mrb_value self)
   return obj;
 }
 
+/*
+ * call-seq:
+ *   binding.local_variables -> array
+ *
+ * Returns an array of symbols representing the names of the local variables
+ * in the binding.
+ *
+ *   def foo
+ *     a = 1
+ *     b = 2
+ *     binding.local_variables  #=> [:a, :b]
+ *   end
+ */
 static mrb_value
 binding_local_variables(mrb_state *mrb, mrb_value self)
 {
@@ -308,6 +371,19 @@ binding_local_variables(mrb_state *mrb, mrb_value self)
   return mrb_proc_local_variables(mrb, proc);
 }
 
+/*
+ * call-seq:
+ *   binding.receiver -> object
+ *
+ * Returns the bound receiver of the binding object.
+ *
+ *   class Demo
+ *     def get_binding
+ *       binding
+ *     end
+ *   end
+ *   Demo.new.get_binding.receiver  #=> #<Demo:0x...>
+ */
 static mrb_value
 binding_receiver(mrb_state *mrb, mrb_value self)
 {
@@ -374,6 +450,20 @@ mrb_binding_new(mrb_state *mrb, const struct RProc *proc, mrb_value recv, struct
   return mrb_obj_value(binding);
 }
 
+/*
+ * call-seq:
+ *   binding -> binding
+ *
+ * Returns a Binding object, describing the variable and method bindings
+ * at the point of call. This object can be used when calling eval to
+ * execute the evaluated command in this environment.
+ *
+ *   def get_binding(param)
+ *     binding
+ *   end
+ *   b = get_binding("hello")
+ *   b.eval("param")  #=> "hello"
+ */
 static mrb_value
 mrb_f_binding(mrb_state *mrb, mrb_value self)
 {