mruby-errno: add comprehensive documentation and fix internal method comments

Added complete call-seq documentation for public methods and corrected
internal method documentation structure:

Public API methods
- SystemCallError.new: Create SystemCallError with message/errno
- SystemCallError#errno: Get errno number from exception
- SystemCallError._sys_fail: Internal method to raise errno exceptions
- Errno exception classes#new: Create specific errno exceptions

Fixed documentation structure to follow mruby conventions where internal
methods starting with __ should not have call-seq documentation but only
brief explanatory comments.

Each public method now includes:
- Clear method signatures with parameter and return types
- Descriptions of errno handling behavior
- Practical examples showing exception creation and handling
- Consistent formatting following mruby documentation standards

Co-authored-by: Atlassian Rovo Dev

mrbgems/mruby-errno/src/errno.c

@@ -118,6 +118,10 @@ ary_included_in_head(mrb_state *mrb, mrb_value ary, mrb_value obj, mrb_ssize hea
   return FALSE;
 }
 
+/*
+ * Internal method used by the Errno module to check if a specific
+ * error constant exists on this platform.
+ */
 static mrb_value
 mrb_errno_defined_p(mrb_state *mrb, mrb_value self)
 {
@@ -140,6 +144,10 @@ mrb_errno_defined_p(mrb_state *mrb, mrb_value self)
   return mrb_false_value();
 }
 
+/*
+ * Internal method used by the Errno module to define errno classes
+ * for error constants that exist on this platform.
+ */
 static mrb_value
 mrb_errno_define(mrb_state *mrb, mrb_value self)
 {
@@ -163,6 +171,10 @@ mrb_errno_define(mrb_state *mrb, mrb_value self)
   return mrb_nil_value();
 }
 
+/*
+ * Internal method used by the Errno module to populate an array
+ * with all errno symbols available on this platform.
+ */
 static mrb_value
 mrb_errno_list(mrb_state *mrb, mrb_value self)
 {
@@ -223,6 +235,16 @@ mrb_sce_init(mrb_state *mrb, mrb_value self, mrb_value m, mrb_value no)
   mrb_exc_mesg_set(mrb, mrb_exc_ptr(self), str);
 }
 
+/*
+ * call-seq:
+ *   errno_class.new(message = nil) -> errno_exception
+ *
+ * Creates a new instance of a specific errno exception class.
+ * The optional message parameter provides additional context.
+ *
+ *   Errno::ENOENT.new                    #=> #<Errno::ENOENT: No such file or directory>
+ *   Errno::ENOENT.new("custom message")  #=> #<Errno::ENOENT: No such file or directory - custom message>
+ */
 static mrb_value
 mrb_exxx_init(mrb_state *mrb, mrb_value self)
 {
@@ -233,6 +255,21 @@ mrb_exxx_init(mrb_state *mrb, mrb_value self)
   return self;
 }
 
+/*
+ * call-seq:
+ *   SystemCallError.new(message)           -> system_call_error
+ *   SystemCallError.new(errno)             -> system_call_error
+ *   SystemCallError.new(message, errno)    -> system_call_error
+ *
+ * Creates a new SystemCallError exception. Can be called with:
+ * - A message string only
+ * - An errno number only
+ * - Both a message string and errno number
+ *
+ *   SystemCallError.new("custom error")     #=> #<SystemCallError: custom error>
+ *   SystemCallError.new(2)                  #=> #<SystemCallError: No such file or directory>
+ *   SystemCallError.new("failed", 2)        #=> #<SystemCallError: No such file or directory - failed>
+ */
 static mrb_value
 mrb_sce_init_m(mrb_state *mrb, mrb_value self)
 {
@@ -255,6 +292,19 @@ mrb_sce_init_m(mrb_state *mrb, mrb_value self)
   return self;
 }
 
+/*
+ * call-seq:
+ *   system_call_error.errno -> integer or nil
+ *
+ * Returns the errno number associated with this SystemCallError.
+ * Returns nil if no errno was set.
+ *
+ *   begin
+ *     File.open("/nonexistent")
+ *   rescue SystemCallError => e
+ *     e.errno  #=> 2 (ENOENT)
+ *   end
+ */
 static mrb_value
 mrb_sce_errno(mrb_state *mrb, mrb_value self)
 {
@@ -272,6 +322,16 @@ mrb_sce_errno(mrb_state *mrb, mrb_value self)
   }
 }
 
+/*
+ * call-seq:
+ *   SystemCallError._sys_fail(errno, message = nil)
+ *
+ * Internal method that raises a SystemCallError with the given errno
+ * and optional message. This method does not return as it raises an exception.
+ *
+ *   SystemCallError._sys_fail(2)              # raises Errno::ENOENT
+ *   SystemCallError._sys_fail(2, "failed")    # raises Errno::ENOENT with message
+ */
 static mrb_value
 mrb_sce_sys_fail(mrb_state *mrb, mrb_value cls)
 {