mruby-compar-ext/compar.rb (clamp): update document; ref #5748

mrbgems/mruby-compar-ext/mrblib/compar.rb

@@ -1,15 +1,44 @@
 module Comparable
   ##
-  # Returns <i>min</i> if <i>obj</i> <code><=></code> <i>min</i> is less
-  # than zero, <i>max</i> if <i>obj</i> <code><=></code> <i>max</i> is
-  # greater than zero and <i>obj</i> otherwise.
+  #  call-seq:
+  #    obj.clamp(min, max) ->  obj
+  #    obj.clamp(range)    ->  obj
   #
-  #     12.clamp(0, 100)         #=> 12
-  #     523.clamp(0, 100)        #=> 100
-  #     -3.123.clamp(0, 100)     #=> 0
+  # In <code>(min, max)</code> form, returns _min_ if _obj_
+  # <code><=></code> _min_ is less than zero, _max_ if _obj_
+  # <code><=></code> _max_ is greater than zero, and _obj_
+  # otherwise.
   #
-  #     'd'.clamp('a', 'f')      #=> 'd'
-  #     'z'.clamp('a', 'f')      #=> 'f'
+  #    12.clamp(0, 100)         #=> 12
+  #    523.clamp(0, 100)        #=> 100
+  #    -3.123.clamp(0, 100)     #=> 0
+  #
+  #    'd'.clamp('a', 'f')      #=> 'd'
+  #    'z'.clamp('a', 'f')      #=> 'f'
+  #
+  # In <code>(range)</code> form, returns _range.begin_ if _obj_
+  # <code><=></code> _range.begin_ is less than zero, _range.end_
+  # if _obj_ <code><=></code> _range.end_ is greater than zero, and
+  # _obj_ otherwise.
+  #
+  #    12.clamp(0..100)         #=> 12
+  #    523.clamp(0..100)        #=> 100
+  #    -3.123.clamp(0..100)     #=> 0
+  #
+  #    'd'.clamp('a'..'f')      #=> 'd'
+  #    'z'.clamp('a'..'f')      #=> 'f'
+  #
+  # If _range.begin_ is +nil+, it is considered smaller than _obj_,
+  # and if _range.end_ is +nil+, it is considered greater than
+  # _obj_.
+  #
+  #    -20.clamp(0..)           #=> 0
+  #    523.clamp(..100)         #=> 100
+  #
+  # When _range.end_ is excluded and not +nil+, an exception is
+  # raised.
+  #
+  #     100.clamp(0...100)       # ArgumentError
   #
   def clamp(min, max=nil)
     if max.nil?