From 8b39a57be76dae0b526581d30c44030650f214ac Mon Sep 17 00:00:00 2001
From: "Yukihiro \"Matz\" Matsumoto" <matz@ruby.or.jp>
Date: Mon, 21 Jul 2025 16:40:08 +0900
Subject: [PATCH] mruby-sleep: add comprehensive call-seq documentation for
 sleep functionality

Added complete call-seq documentation for thread suspension methods in
src/sleep.c:

## Core Methods:

### sleep:
- Suspends current thread for specified duration in seconds
- Supports floating point precision when MRB_NO_FLOAT is not defined
- Returns actual number of seconds slept (rounded)
- Cross-platform implementation (Windows Sleep vs Unix nanosleep)
- Comprehensive examples showing fractional second delays

### usleep:
- Suspends current thread for specified duration in microseconds
- Provides microsecond-level precision for short delays
- Integer-only parameter for precise timing control
- Returns 0 on successful completion
- Examples demonstrating millisecond and microsecond delays

Co-authored-by: Atlassian Rovo Dev
---
 mrbgems/mruby-sleep/src/sleep.c | 50 ++++++++++++++++++++++++++++++++-
 1 file changed, 49 insertions(+), 1 deletion(-)

diff --git a/mrbgems/mruby-sleep/src/sleep.c b/mrbgems/mruby-sleep/src/sleep.c
index 8f434957d..6e98d80a2 100644
--- a/mrbgems/mruby-sleep/src/sleep.c
+++ b/mrbgems/mruby-sleep/src/sleep.c
@@ -39,7 +39,24 @@
 #include <mruby.h>
 #include <mruby/presym.h>
 
-/* not implemented forever sleep (called without an argument)*/
+/*
+ * call-seq:
+ *   sleep(duration) -> integer
+ *
+ * Suspends the current thread for duration seconds (which may be any number,
+ * including a Float with fractional seconds if floating point is enabled).
+ * Returns the actual number of seconds slept (rounded), which may be less than
+ * that asked for if another thread calls Thread#run. Zero arguments causes
+ * sleep to sleep forever.
+ *
+ *   Time.new    #=> 2008-03-08 19:56:19 +0900
+ *   sleep 1.2   #=> 1
+ *   Time.new    #=> 2008-03-08 19:56:20 +0900
+ *   sleep 1.9   #=> 2
+ *   Time.new    #=> 2008-03-08 19:56:22 +0900
+ *
+ * Note: Forever sleep (called without an argument) is not implemented.
+ */
 static mrb_value
 f_sleep(mrb_state *mrb, mrb_value self)
 {
@@ -72,6 +89,21 @@ f_sleep(mrb_state *mrb, mrb_value self)
 }
 
 /* mruby special; needed for mruby without float numbers */
+/*
+ * call-seq:
+ *   usleep(microseconds) -> 0
+ *
+ * Suspends the current thread for microseconds microseconds (which should be
+ * an integer). This provides microsecond-level precision for short delays.
+ * Returns 0 on successful completion.
+ *
+ *   usleep(500000)  # Sleep for 0.5 seconds (500,000 microseconds)
+ *   usleep(1000)    # Sleep for 1 millisecond (1,000 microseconds)
+ *   usleep(100)     # Sleep for 100 microseconds
+ *
+ * Note: This function is useful for precise timing in embedded systems
+ * where sub-second delays are required.
+ */
 static mrb_value
 f_usleep(mrb_state *mrb, mrb_value self)
 {
@@ -126,6 +158,17 @@ f_usleep(mrb_state *mrb, mrb_value self)
     return mrb_fixnum_value((mrb_int)slp_tm);
 }
 
+/*
+ * Initializes the mruby-sleep gem by defining sleep and usleep methods
+ * as private methods in the Kernel module, making them available globally.
+ *
+ * - sleep: requires 1 argument (duration in seconds), supports floating point
+ *   when MRB_NO_FLOAT is not defined, otherwise uses integer seconds
+ * - usleep: requires 1 argument (duration in microseconds), integer only
+ *
+ * Both methods provide thread suspension capabilities for timing control
+ * in embedded Ruby environments with cross-platform support (Windows/Unix).
+ */
 void
 mrb_mruby_sleep_gem_init(mrb_state *mrb)
 {
@@ -133,6 +176,11 @@ mrb_mruby_sleep_gem_init(mrb_state *mrb)
   mrb_define_private_method_id(mrb, mrb->kernel_module, MRB_SYM(usleep),  f_usleep,  MRB_ARGS_REQ(1));
 }
 
+/*
+ * Finalizes the mruby-sleep gem. Currently no cleanup is required
+ * as the sleep/usleep implementation uses system calls without
+ * persistent state or allocated resources.
+ */
 void
 mrb_mruby_sleep_gem_final(mrb_state *mrb)
 {