rbs 3.3.2 → 3.4.0.pre.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 27004297e5bb976aba56b115d26288536b31acd15a38ea42841a0efd4dae6fe8
-  data.tar.gz: 4772b6936d87c79bc7b450f636389346be60c86eb8ec9827c2dcacacaf0056ae
+  metadata.gz: 48c814d4cbaac5fe01ca09ff353a0fdde62a95b37a677e398925e0f1905b5a4f
+  data.tar.gz: 3e8ff356790ab3879392996f26db15d0c0e01686a7e496ee4c6e26f9b326b9b2
 SHA512:
-  metadata.gz: '01394e99526697c6285db28bbacf32a787308e98b885c41b41ebeb49776cbe3e3a2dbd81d566634c46b4ba16ad3b4013fbe3e776cf1e608b253bba50932d844a'
-  data.tar.gz: cebafcc273581a42e7784468b8a00ca29ddd17be0d287b981ca6f1cb211c3f85cb22d73152955532f7e94e7dd2ab4e003ed05c3606aa6426ea9a622d98dc8f8b
+  metadata.gz: a14fdcafb7e142a4685fd31325900e24aceee40c17b453e87800bebcc1958e02d9ade0ff912ef711650a8e1ca8adae62c150ccd8377a6859d687be55ba999440
+  data.tar.gz: 8c69b1dafc7738fb35c6da0a12c33ac7fdc7bcd75f7fcefaf4dc68383b85fb3717fc21ca632d151ec9182633ebea115160edf44324681275de8dbfd945e7ba02

data/.github/workflows/comments.yml

@@ -12,6 +12,8 @@ jobs:
     runs-on: "ubuntu-latest"
     container:
       image: rubylang/ruby:3.2-dev-focal
+    env:
+      RUBY_COMMIT: v3_3_0_rc1
     steps:
       - uses: actions/checkout@v4
       - name: Install dependencies
@@ -22,11 +24,6 @@ jobs:
         run: |
           ruby -v
           gem update --system
-      - name: bundle config set with
-        run: |
-          echo "NO_MINITEST=true" >> $GITHUB_ENV
-          bundle config set --local without 'minitest'
-        if: "contains(matrix.container_tag, 'master-nightly')"
       - name: bin/setup
         run: |
           bin/setup

data/.github/workflows/ruby.yml

@@ -31,9 +31,8 @@ jobs:
             job: stdlib_test
           - container_tag: 3.1-dev-focal
             job: stdlib_test
-        include:
-          - container_tag: master-nightly-focal
-            allow_failures: "true"
+          - container_tag: 3.2-dev-focal
+            job: stdlib_test
     container:
       image: rubylang/ruby:${{ matrix.container_tag }}
     steps:
@@ -43,14 +42,14 @@ jobs:
       - name: Install dependencies
         run: |
           apt-get update
-          apt-get install -y libdb-dev curl autoconf automake m4 libtool
+          apt-get install -y libdb-dev curl autoconf automake m4 libtool python3
       - name: Install Re2c
         if: contains(matrix.job, 'lexer')
         run: |
           cd /tmp
-          curl -L https://github.com/skvadrik/re2c/archive/refs/tags/3.0.tar.gz > re2c-3.0.tar.gz
-          tar xf re2c-3.0.tar.gz
-          cd re2c-3.0
+          curl -L https://github.com/skvadrik/re2c/archive/refs/tags/3.1.tar.gz > re2c-3.1.tar.gz
+          tar xf re2c-3.1.tar.gz
+          cd re2c-3.1
           autoreconf -i -W all
           ./configure
           make
@@ -63,7 +62,7 @@ jobs:
         run: |
           echo "NO_MINITEST=true" >> $GITHUB_ENV
           bundle config set --local without 'minitest'
-        if: "contains(matrix.container_tag, 'master-nightly')"
+        if: ${{ contains(matrix.container_tag, 'master-nightly') }}
       - name: bin/setup
         run: |
           bin/setup

data/.github/workflows/typecheck.yml

@@ -0,0 +1,37 @@
+name: Type check
+
+on:
+  push:
+    branches:
+      - master
+  pull_request: {}
+  merge_group: {}
+
+jobs:
+  test:
+    runs-on: "ubuntu-latest"
+    strategy:
+      fail-fast: false
+      matrix:
+        container_tag:
+          - 3.2-dev-focal
+    container:
+      image: rubylang/ruby:${{ matrix.container_tag }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set working directory as safe
+        run: git config --global --add safe.directory $(pwd)
+      - name: Install dependencies
+        run: |
+          apt-get update
+          apt-get install -y libdb-dev curl autoconf automake m4 libtool
+      - name: Update rubygems & bundler
+        run: |
+          ruby -v
+          gem update --system
+      - name: bin/setup
+        run: |
+          bin/setup
+      - name: Run steep check
+        run: |
+          bin/steep check -j 2

data/CHANGELOG.md

@@ -2,6 +2,56 @@
 
 ## master
 
+## 3.4.0.pre.1 (2023-12-19)
+
+### Signature updates
+
+* Changes in ruby-3.3 ([#1684](https://github.com/ruby/rbs/pull/1684), [#1674](https://github.com/ruby/rbs/pull/1674))
+* Embedded docs update ([#1689](https://github.com/ruby/rbs/pull/1689), [#1676](https://github.com/ruby/rbs/pull/1676))
+* delegate ([#1677](https://github.com/ruby/rbs/pull/1677))
+* `MatchData` ([#1651](https://github.com/ruby/rbs/pull/1651))
+* `String` ([#1672](https://github.com/ruby/rbs/pull/1672), [#1641](https://github.com/ruby/rbs/pull/1641))
+* `Struct` ([#1621](https://github.com/ruby/rbs/pull/1621))
+* `Warning` categories ([#1576](https://github.com/ruby/rbs/pull/1576))
+* `ConditionVariable#wait` ([#1670](https://github.com/ruby/rbs/pull/1670))
+* `Date.parse` ([#1653](https://github.com/ruby/rbs/pull/1653))
+* `IO#gets` ([#1620](https://github.com/ruby/rbs/pull/1620))
+* `Kernel.Pathname` ([#1681](https://github.com/ruby/rbs/pull/1681))
+* `Resolv::DNS::Resource::Generic.create` ([#1655](https://github.com/ruby/rbs/pull/1655))
+* `Thread#raise` ([#1668](https://github.com/ruby/rbs/pull/1668))
+* Builtin types ([#1680](https://github.com/ruby/rbs/pull/1680), [#1644](https://github.com/ruby/rbs/pull/1644))
+
+### Library changes
+
+* Add more details error message for `UnresolvedOverloadingError` ([#1688](https://github.com/ruby/rbs/pull/1688))
+* Add `with_***` helpers ([#1687](https://github.com/ruby/rbs/pull/1687))
+* Fix lexer ([#1685](https://github.com/ruby/rbs/pull/1685))
+* Support `Delegator` object ([#1682](https://github.com/ruby/rbs/pull/1682))
+* Should raise `ParsingError` instead of NoMethodError ([#1675](https://github.com/ruby/rbs/pull/1675))
+* Implement multiple validate ([#1648](https://github.com/ruby/rbs/pull/1648))
+* Add `RBS::UnitTest` modules ([#1660](https://github.com/ruby/rbs/pull/1660))
+* Not cached as it may be replaced ([#1656](https://github.com/ruby/rbs/pull/1656))
+* Should raise `ParsingError` instead of ArgumentError ([#1652](https://github.com/ruby/rbs/pull/1652))
+* Added `WithEnum#but` and `with_range` ([#1649](https://github.com/ruby/rbs/pull/1649))
+* Bugfix; `.respond_to` is no longer used in `Rbs::Test::Errors#inspect_` ([#1650](https://github.com/ruby/rbs/pull/1650))
+* Add `--detail` option to rbs diff ([#1623](https://github.com/ruby/rbs/pull/1623))
+* Fix parse error when quoted required keywords ([#1627](https://github.com/ruby/rbs/pull/1627))
+
+#### rbs collection
+
+* Fix order for collection sources ([#1659](https://github.com/ruby/rbs/pull/1659))
+* [collection] Ignore directory starting with `_` as version from git source ([#1657](https://github.com/ruby/rbs/pull/1657))
+
+### Miscellaneous
+
+* Fix token names in comments ([#1658](https://github.com/ruby/rbs/pull/1658))
+* Small bugfix to have guaranteed print out instance variables ([#1642](https://github.com/ruby/rbs/pull/1642))
+* Fix flaky test ([#1616](https://github.com/ruby/rbs/pull/1616))
+* Update syntax.md ([#1634](https://github.com/ruby/rbs/pull/1634))
+* Add steep typecheck workflow ([#1632](https://github.com/ruby/rbs/pull/1632))
+* Add doc for Generating RBS ([#1617](https://github.com/ruby/rbs/pull/1617))
+* updated test harness utils ([#1600](https://github.com/ruby/rbs/pull/1600))
+
 ## 3.3.2 (2023-11-21)
 
 ### Miscellaneous

data/Gemfile

@@ -17,7 +17,7 @@ gem "goodcheck"
 gem "dbm"
 gem 'digest'
 gem 'tempfile'
-gem "rdoc", "~> 6.4.0"
+gem "rdoc"
 
 # Test gems
 gem "rbs-amber", path: "test/assets/test-gem"

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rbs (3.3.2)
+    rbs (3.4.0.pre.1)
       abbrev
 
 PATH
@@ -12,7 +12,7 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    abbrev (0.1.1)
+    abbrev (0.1.2)
     addressable (2.8.5)
       public_suffix (>= 2.0.2, < 6.0)
     ast (2.4.2)
@@ -24,7 +24,7 @@ GEM
       psych (>= 3.1, < 5.0)
       rainbow (>= 3.0, < 4.0)
       strong_json (>= 1.1, < 2.2)
-    json (2.6.3)
+    json (2.7.1)
     json-schema (4.1.1)
       addressable (>= 2.8)
     language_server-protocol (3.17.0.3)
@@ -42,14 +42,14 @@ GEM
     psych (4.0.6)
       stringio
     public_suffix (5.0.3)
-    racc (1.7.1)
+    racc (1.7.3)
     rainbow (3.1.1)
     rake (13.1.0)
     rake-compiler (1.2.5)
       rake
-    rdoc (6.4.0)
+    rdoc (6.6.2)
       psych (>= 4.0.0)
-    regexp_parser (2.8.2)
+    regexp_parser (2.8.3)
     rexml (3.2.6)
     rspec (3.12.0)
       rspec-core (~> 3.12.0)
@@ -64,7 +64,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.12.0)
     rspec-support (3.12.0)
-    rubocop (1.57.2)
+    rubocop (1.59.0)
       json (~> 2.3)
       language_server-protocol (>= 3.17.0)
       parallel (~> 1.10)
@@ -72,7 +72,7 @@ GEM
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.28.1, < 2.0)
+      rubocop-ast (>= 1.30.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 3.0)
     rubocop-ast (1.30.0)
@@ -81,9 +81,9 @@ GEM
       rubocop (~> 1.0)
     ruby-progressbar (1.13.0)
     stackprof (0.2.25)
-    stringio (3.0.7)
+    stringio (3.1.0)
     strong_json (2.1.2)
-    tempfile (0.2.0)
+    tempfile (0.2.1)
     test-unit (3.6.1)
       power_assert
     timeout (0.4.0)
@@ -105,7 +105,7 @@ DEPENDENCIES
   rake-compiler
   rbs!
   rbs-amber!
-  rdoc (~> 6.4.0)
+  rdoc
   rspec
   rubocop
   rubocop-rubycw

data/Steepfile

@@ -5,10 +5,10 @@ target :lib do
   check "lib"
   ignore(
     "lib/rbs/test",
-    "lib/rbs/test.rb"
+    # "lib/rbs/test.rb"
   )
 
-  library "pathname", "json", "logger", "monitor", "tsort", "uri", 'dbm', 'pstore', 'singleton', 'shellwords', 'fileutils', 'find', 'digest', 'abbrev', 'prettyprint', 'yaml'
+  library "pathname", "json", "logger", "monitor", "tsort", "uri", 'dbm', 'pstore', 'singleton', 'shellwords', 'fileutils', 'find', 'digest', 'abbrev', 'prettyprint', 'yaml', "psych", "securerandom"
   signature "stdlib/strscan/0/"
   signature "stdlib/optparse/0/"
   signature "stdlib/rdoc/0/"

data/core/array.rbs

@@ -607,7 +607,8 @@ class Array[unchecked out Elem] < Object
   #   - array & other_array -> new_array
   # -->
   # Returns a new Array containing each element found in both `array` and Array
-  # `other_array`; duplicates are omitted; items are compared using `eql?`:
+  # `other_array`; duplicates are omitted; items are compared using `eql?` (items
+  # must also implement `hash` correctly):
   #
   #     [0, 1, 2, 3] & [1, 2] # => [1, 2]
   #     [0, 1, 0, 1] & [0, 1] # => [0, 1]
@@ -837,8 +838,6 @@ class Array[unchecked out Elem] < Object
   #     # Raises TypeError (no implicit conversion of Symbol into Integer):
   #     a[:foo]
   #
-  # Array#slice is an alias for Array#[].
-  #
   def []: %a{implicitly-returns-nil} (int index) -> Elem
         | (int start, int length) -> ::Array[Elem]?
         | (::Range[::Integer?] range) -> ::Array[Elem]?
@@ -972,6 +971,8 @@ class Array[unchecked out Elem] < Object
   # -->
   # Returns `true` if all elements of `self` meet a given criterion.
   #
+  # If `self` has no element, returns `true` and argument or block are not used.
+  #
   # With no block given and no argument, returns `true` if `self` contains only
   # truthy elements, `false` otherwise:
   #
@@ -1009,6 +1010,8 @@ class Array[unchecked out Elem] < Object
   # -->
   # Returns `true` if any element of `self` meets a given criterion.
   #
+  # If `self` has no element, returns `false` and argument or block are not used.
+  #
   # With no block given and no argument, returns `true` if `self` has any truthy
   # element, `false` otherwise:
   #
@@ -1050,8 +1053,6 @@ class Array[unchecked out Elem] < Object
   #     a1 = a.push([:baz, :bat], [:bam, :bad])
   #     a1 # => [:foo, "bar", 2, [:baz, :bat], [:bam, :bad]]
   #
-  # Array#append is an alias for Array#push.
-  #
   # Related: #pop, #shift, #unshift.
   #
   alias append push
@@ -1135,8 +1136,6 @@ class Array[unchecked out Elem] < Object
   #     a1 = a.map
   #     a1 # => #<Enumerator: [:foo, "bar", 2]:map>
   #
-  # Array#collect is an alias for Array#map.
-  #
   def collect: [U] () { (Elem item) -> U } -> ::Array[U]
              | () -> ::Enumerator[Elem, ::Array[untyped]]
 
@@ -1157,8 +1156,6 @@ class Array[unchecked out Elem] < Object
   #     a1 = a.map!
   #     a1 # => #<Enumerator: [:foo, "bar", 2]:map!>
   #
-  # Array#collect! is an alias for Array#map!.
-  #
   def collect!: () { (Elem item) -> Elem } -> self
               | () -> ::Enumerator[Elem, self]
 
@@ -1388,18 +1385,16 @@ class Array[unchecked out Elem] < Object
   #   - array.delete_if {|element| ... } -> self
   #   - array.delete_if -> Enumerator
   # -->
-  # Removes each element in +self+ for which the block returns a truthy value;
-  #     returns +self+:
-  #
-  #       a = [:foo, 'bar', 2, 'bat']
-  #       a.delete_if {|element| element.to_s.start_with?('b') } # => [:foo, 2]
+  # Removes each element in `self` for which the block returns a truthy value;
+  # returns `self`:
   #
-  #     Returns a new \Enumerator if no block given:
+  #     a = [:foo, 'bar', 2, 'bat']
+  #     a.delete_if {|element| element.to_s.start_with?('b') } # => [:foo, 2]
   #
-  #       a = [:foo, 'bar', 2]
-  #       a.delete_if # => #<Enumerator: [:foo, "bar", 2]:delete_if>
+  # Returns a new Enumerator if no block given:
   #
-  # 3
+  #     a = [:foo, 'bar', 2]
+  #     a.delete_if # => #<Enumerator: [:foo, "bar", 2]:delete_if>
   #
   def delete_if: () { (Elem item) -> boolish } -> self
                | () -> ::Enumerator[Elem, self]
@@ -1854,8 +1849,6 @@ class Array[unchecked out Elem] < Object
   #     a = [:foo, 'bar', 2, :bam]
   #     a.select # => #<Enumerator: [:foo, "bar", 2, :bam]:select>
   #
-  # Array#filter is an alias for Array#select.
-  #
   def filter: () { (Elem item) -> boolish } -> ::Array[Elem]
             | () -> ::Enumerator[Elem, ::Array[Elem]]
 
@@ -1875,8 +1868,6 @@ class Array[unchecked out Elem] < Object
   #     a = [:foo, 'bar', 2, :bam]
   #     a.select! # => #<Enumerator: [:foo, "bar", 2, :bam]:select!>
   #
-  # Array#filter! is an alias for Array#select!.
-  #
   def filter!: () { (Elem item) -> boolish } -> self?
              | () -> ::Enumerator[Elem, self?]
 
@@ -1912,8 +1903,6 @@ class Array[unchecked out Elem] < Object
   #     e # => #<Enumerator: [:foo, "bar", 2]:index>
   #     e.each {|element| element == 'bar' } # => 1
   #
-  # Array#find_index is an alias for Array#index.
-  #
   # Related: #rindex.
   #
   def find_index: (untyped obj) -> ::Integer?
@@ -1921,7 +1910,7 @@ class Array[unchecked out Elem] < Object
                 | () -> ::Enumerator[Elem, ::Integer?]
 
   # <!--
-  #   rdoc-file=array.c
+  #   rdoc-file=array.rb
   #   - array.first -> object or nil
   #   - array.first(n) -> new_array
   # -->
@@ -2078,8 +2067,6 @@ class Array[unchecked out Elem] < Object
   #     e # => #<Enumerator: [:foo, "bar", 2]:index>
   #     e.each {|element| element == 'bar' } # => 1
   #
-  # Array#find_index is an alias for Array#index.
-  #
   # Related: #rindex.
   #
   alias index find_index
@@ -2130,8 +2117,6 @@ class Array[unchecked out Elem] < Object
   #     a = [:foo, 'bar', 2]
   #     a.inspect # => "[:foo, \"bar\", 2]"
   #
-  # Array#to_s is an alias for Array#inspect.
-  #
   def inspect: () -> String
 
   # <!--
@@ -2147,6 +2132,9 @@ class Array[unchecked out Elem] < Object
   #     a.intersect?(b)   #=> true
   #     a.intersect?(c)   #=> false
   #
+  # Array elements are compared using `eql?` (items must also implement `hash`
+  # correctly).
+  #
   def intersect?: (_ToAry[untyped]) -> bool
 
   # <!--
@@ -2155,7 +2143,7 @@ class Array[unchecked out Elem] < Object
   # -->
   # Returns a new Array containing each element found both in `self` and in all of
   # the given Arrays `other_arrays`; duplicates are omitted; items are compared
-  # using `eql?`:
+  # using `eql?` (items must also implement `hash` correctly):
   #
   #     [0, 1, 2, 3].intersection([0, 1, 2], [0, 1, 3]) # => [0, 1]
   #     [0, 0, 1, 1, 2, 3].intersection([0, 1, 2], [0, 1, 3]) # => [0, 1]
@@ -2221,7 +2209,7 @@ class Array[unchecked out Elem] < Object
              | () -> ::Enumerator[Elem, self]
 
   # <!--
-  #   rdoc-file=array.c
+  #   rdoc-file=array.rb
   #   - array.last  -> object or nil
   #   - array.last(n) -> new_array
   # -->
@@ -2277,8 +2265,6 @@ class Array[unchecked out Elem] < Object
   #     a1 = a.map
   #     a1 # => #<Enumerator: [:foo, "bar", 2]:map>
   #
-  # Array#collect is an alias for Array#map.
-  #
   alias map collect
 
   # <!-- rdoc-file=array.c -->
@@ -2294,8 +2280,6 @@ class Array[unchecked out Elem] < Object
   #     a1 = a.map!
   #     a1 # => #<Enumerator: [:foo, "bar", 2]:map!>
   #
-  # Array#collect! is an alias for Array#map!.
-  #
   alias map! collect!
 
   # <!--
@@ -2608,8 +2592,6 @@ class Array[unchecked out Elem] < Object
   #     a = [:foo, 'bar', 2]
   #     a.unshift(:bam, :bat) # => [:bam, :bat, :foo, "bar", 2]
   #
-  # Array#prepend is an alias for Array#unshift.
-  #
   # Related: #push, #pop, #shift.
   #
   alias prepend unshift
@@ -2695,8 +2677,6 @@ class Array[unchecked out Elem] < Object
   #     a1 = a.push([:baz, :bat], [:bam, :bad])
   #     a1 # => [:foo, "bar", 2, [:baz, :bat], [:bam, :bad]]
   #
-  # Array#append is an alias for Array#push.
-  #
   # Related: #pop, #shift, #unshift.
   #
   def push: (*Elem obj) -> self
@@ -3159,8 +3139,6 @@ class Array[unchecked out Elem] < Object
   #     a = [:foo, 'bar', 2, :bam]
   #     a.select # => #<Enumerator: [:foo, "bar", 2, :bam]:select>
   #
-  # Array#filter is an alias for Array#select.
-  #
   def select: () { (Elem item) -> boolish } -> ::Array[Elem]
             | () -> ::Enumerator[Elem, ::Array[Elem]]
 
@@ -3184,8 +3162,6 @@ class Array[unchecked out Elem] < Object
   #     a = [:foo, 'bar', 2, :bam]
   #     a.select! # => #<Enumerator: [:foo, "bar", 2, :bam]:select!>
   #
-  # Array#filter! is an alias for Array#select!.
-  #
   def select!: () { (Elem item) -> boolish } -> self?
              | () -> ::Enumerator[Elem, self?]
 
@@ -3347,8 +3323,6 @@ class Array[unchecked out Elem] < Object
   #     # Raises TypeError (no implicit conversion of Symbol into Integer):
   #     a[:foo]
   #
-  # Array#slice is an alias for Array#[].
-  #
   def slice: (int index) -> Elem?
            | (int start, int length) -> ::Array[Elem]?
            | (::Range[::Integer] range) -> ::Array[Elem]?
@@ -3682,8 +3656,6 @@ class Array[unchecked out Elem] < Object
   #     a = [:foo, 'bar', 2]
   #     a.inspect # => "[:foo, \"bar\", 2]"
   #
-  # Array#to_s is an alias for Array#inspect.
-  #
   alias to_s inspect
 
   # <!--
@@ -3780,8 +3752,6 @@ class Array[unchecked out Elem] < Object
   #     a = [:foo, 'bar', 2]
   #     a.unshift(:bam, :bat) # => [:bam, :bat, :foo, "bar", 2]
   #
-  # Array#prepend is an alias for Array#unshift.
-  #
   # Related: #push, #pop, #shift.
   #
   def unshift: (*Elem obj) -> self

data/core/basic_object.rbs

@@ -128,7 +128,7 @@ class BasicObject
   # Note: that some objects of builtin classes are reused for optimization. This
   # is the case for immediate values and frozen string literals.
   #
-  # BasicObject implements +__id__+, Kernel implements `object_id`.
+  # BasicObject implements `__id__`, Kernel implements `object_id`.
   #
   # Immediate values are not passed by reference but are passed by value: `nil`,
   # `true`, `false`, Fixnums, Symbols, and some Floats.
@@ -151,7 +151,7 @@ class BasicObject
   # When the method is identified by a string, the string is converted to a
   # symbol.
   #
-  # BasicObject implements +__send__+, Kernel implements `send`. `__send__` is
+  # BasicObject implements `__send__`, Kernel implements `send`. `__send__` is
   # safer than `send` when *obj* has the same method name like `Socket`. See also
   # `public_send`.
   #

data/core/comparable.rbs

@@ -8,25 +8,28 @@
 # implement the conventional comparison operators (`<`, `<=`, `==`, `>=`, and
 # `>`) and the method `between?`.
 #
-#     class SizeMatters
+#     class StringSorter
 #       include Comparable
+#
 #       attr :str
 #       def <=>(other)
 #         str.size <=> other.str.size
 #       end
+#
 #       def initialize(str)
 #         @str = str
 #       end
+#
 #       def inspect
 #         @str
 #       end
 #     end
 #
-#     s1 = SizeMatters.new("Z")
-#     s2 = SizeMatters.new("YY")
-#     s3 = SizeMatters.new("XXX")
-#     s4 = SizeMatters.new("WWWW")
-#     s5 = SizeMatters.new("VVVVV")
+#     s1 = StringSorter.new("Z")
+#     s2 = StringSorter.new("YY")
+#     s3 = StringSorter.new("XXX")
+#     s4 = StringSorter.new("WWWW")
+#     s5 = StringSorter.new("VVVVV")
 #
 #     s1 < s2                       #=> true
 #     s4.between?(s1, s3)           #=> false
@@ -40,8 +43,8 @@
 # *   #<: Returns whether `self` is less than the given object.
 # *   #<=: Returns whether `self` is less than or equal to the given object.
 # *   #==: Returns whether `self` is equal to the given object.
-# *   #>: Returns whether `self` is greater than or equal to the given object.
-# *   #>=: Returns whether `self` is greater than the given object.
+# *   #>: Returns whether `self` is greater than the given object.
+# *   #>=: Returns whether `self` is greater than or equal to the given object.
 # *   #between?: Returns `true` if `self` is between two given objects.
 # *   #clamp: For given objects `min` and `max`, or range `(min..max)`, returns:
 #
@@ -124,6 +127,12 @@ module Comparable : _WithSpaceshipOperator
   #     'd'.clamp('a', 'f')      #=> 'd'
   #     'z'.clamp('a', 'f')      #=> 'f'
   #
+  # If *min* is `nil`, it is considered smaller than *obj*, and if *max* is `nil`,
+  # it is considered greater than *obj*.
+  #
+  #     -20.clamp(0, nil)           #=> 0
+  #     523.clamp(nil, 100)         #=> 100
+  #
   # In `(range)` form, returns *range.begin* if *obj* `<=>` *range.begin* is less
   # than zero, *range.end* if *obj* `<=>` *range.end* is greater than zero, and
   # *obj* otherwise.