rbs 2.0.0 → 2.1.0

data/core/env.rbs

@@ -1,3 +1,4 @@
+# <!-- rdoc-file=hash.c -->
 # ENV is a hash-like accessor for environment variables.
 #
 # ### Interaction with the Operating System
@@ -85,9 +86,182 @@
 # *   ENV.replace replaces ENV with a new collection of entries.
 # *   ENV.clear empties ENV.
 #
+#
+# ## What's Here
+#
+# First, what's elsewhere. Class ENV:
+#
+# *   Inherits from [class
+#     Object](Object.html#class-Object-label-What-27s+Here).
+# *   Extends [module
+#     Enumerable](Enumerable.html#module-Enumerable-label-What-27s+Here),
+#
+#
+# Here, class ENV provides methods that are useful for:
+#
+# *   [Querying](#class-ENV-label-Methods+for+Querying)
+# *   [Assigning](#class-ENV-label-Methods+for+Assigning)
+# *   [Deleting](#class-ENV-label-Methods+for+Deleting)
+# *   [Iterating](#class-ENV-label-Methods+for+Iterating)
+# *   [Converting](#class-ENV-label-Methods+for+Converting)
+# *   [And more ....](#class-ENV-label-More+Methods)
+#
+#
+# ### Methods for Querying
+#
+#     ::[]
+# :       Returns the value for the given environment variable name if it
+#         exists:
+#
+#     ::empty?
+# :       Returns whether ENV is empty.
+#
+#     ::has_value?, ::value?
+# :       Returns whether the given value is in ENV.
+#
+#     ::include?, ::has_key?, ::key?, ::member?
+# :       Returns whether the given name is in ENV.
+#
+#     ::key
+# :       Returns the name of the first entry with the given value.
+#
+#     ::size, ::length
+# :       Returns the number of entries.
+#
+#     ::value?
+# :       Returns whether any entry has the given value.
+#
+#
+#
+# ### Methods for Assigning
+#
+#     ::[]=, ::store
+# :       Creates, updates, or deletes the named environment variable.
+#
+#     ::clear
+# :       Removes every environment variable; returns ENV:
+#
+#     ::update, ::merge!
+# :       Adds to ENV each key/value pair in the given hash.
+#
+#     ::replace
+# :       Replaces the entire content of the ENV with the name/value pairs in
+#         the given hash.
+#
+#
+#
+# ### Methods for Deleting
+#
+#     ::delete
+# :       Deletes the named environment variable name if it exists.
+#
+#     ::delete_if
+# :       Deletes entries selected by the block.
+#
+#     ::keep_if
+# :       Deletes entries not selected by the block.
+#
+#     ::reject!
+# :       Similar to #delete_if, but returns `nil` if no change was made.
+#
+#     ::select!, ::filter!
+# :       Deletes entries selected by the block.
+#
+#     ::shift
+# :       Removes and returns the first entry.
+#
+#
+#
+# ### Methods for Iterating
+#
+#     ::each, ::each_pair
+# :       Calls the block with each name/value pair.
+#
+#     ::each_key
+# :       Calls the block with each name.
+#
+#     ::each_value
+# :       Calls the block with each value.
+#
+#
+#
+# ### Methods for Converting
+#
+#     ::assoc
+# :       Returns a 2-element array containing the name and value of the named
+#         environment variable if it exists:
+#
+#     ::clone
+# :       Returns ENV (and issues a warning).
+#
+#     ::except
+# :       Returns a hash of all name/value pairs except those given.
+#
+#     ::fetch
+# :       Returns the value for the given name.
+#
+#     ::inspect
+# :       Returns the contents of ENV as a string.
+#
+#     ::invert
+# :       Returns a hash whose keys are the ENV values, and whose values are the
+#         corresponding ENV names.
+#
+#     ::keys
+# :       Returns an array of all names.
+#
+#     ::rassoc
+# :       Returns the name and value of the first found entry that has the given
+#         value.
+#
+#     ::reject
+# :       Returns a hash of those entries not rejected by the block.
+#
+#     ::select, ::filter
+# :       Returns a hash of name/value pairs selected by the block.
+#
+#     ::slice
+# :       Returns a hash of the given names and their corresponding values.
+#
+#     ::to_a
+# :       Returns the entries as an array of 2-element Arrays.
+#
+#     ::to_h
+# :       Returns a hash of entries selected by the block.
+#
+#     ::to_hash
+# :       Returns a hash of all entries.
+#
+#     ::to_s
+# :       Returns the string `'ENV'`.
+#
+#     ::values
+# :       Returns all values as an array.
+#
+#     ::values_at
+# :       Returns an array of the values for the given name.
+#
+#
+#
+# ### More Methods
+#
+#     ::dup
+# :       Raises an exception.
+#
+#     ::freeze
+# :       Raises an exception.
+#
+#     ::rehash
+# :       Returns `nil`, without modifying ENV.
+#
+%a{annotate:rdoc:copy:ENV}
 class ENVClass
   include Enumerable[[ String, String ]]
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV[name] -> value
+  # -->
   # Returns the value for the environment variable `name` if it exists:
   #     ENV['foo'] = '0'
   #     ENV['foo'] # => "0"
@@ -97,8 +271,15 @@ class ENVClass
   # Raises an exception if `name` is invalid. See [Invalid Names and
   # Values](#class-ENV-label-Invalid+Names+and+Values).
   #
+  %a{annotate:rdoc:copy:ENV.[]}
   def []: (String name) -> String?
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.fetch(name)                  -> value
+  #   - ENV.fetch(name, default)         -> value
+  #   - ENV.fetch(name) { |name| block } -> value
+  # -->
   # If `name` is the name of an environment variable, returns its value:
   #     ENV['foo'] = '0'
   #     ENV.fetch('foo') # => '0'
@@ -124,10 +305,16 @@ class ENVClass
   # Raises an exception if `name` is invalid. See [Invalid Names and
   # Values](#class-ENV-label-Invalid+Names+and+Values).
   #
+  %a{annotate:rdoc:copy:ENV.fetch}
   def fetch: (String name) -> String
            | [X] (String name, X default) -> (String | X)
            | [X] (String name) { (String) -> X } -> (String | X)
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV[name] = value      -> value
+  #   - ENV.store(name, value) -> value
+  # -->
   # ENV.store is an alias for ENV.[]=.
   #
   # Creates, updates, or deletes the named environment variable, returning the
@@ -175,8 +362,14 @@ class ENVClass
   # Raises an exception if `name` or `value` is invalid. See [Invalid Names and
   # Values](#class-ENV-label-Invalid+Names+and+Values).
   #
+  %a{annotate:rdoc:copy:ENV.[]=}
   def []=: (String name, String? value) -> String?
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV[name] = value      -> value
+  #   - ENV.store(name, value) -> value
+  # -->
   # ENV.store is an alias for ENV.[]=.
   #
   # Creates, updates, or deletes the named environment variable, returning the
@@ -224,8 +417,16 @@ class ENVClass
   # Raises an exception if `name` or `value` is invalid. See [Invalid Names and
   # Values](#class-ENV-label-Invalid+Names+and+Values).
   #
+  %a{annotate:rdoc:copy:ENV.store}
   alias store []=
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.each      { |name, value| block } -> ENV
+  #   - ENV.each                              -> an_enumerator
+  #   - ENV.each_pair { |name, value| block } -> ENV
+  #   - ENV.each_pair                         -> an_enumerator
+  # -->
   # Yields each environment variable name and its value as a 2-element Array:
   #     h = {}
   #     ENV.each_pair { |name, value| h[name] = value } # => ENV
@@ -237,9 +438,17 @@ class ENVClass
   #     e.each { |name, value| h[name] = value } # => ENV
   #     h # => {"bar"=>"1", "foo"=>"0"}
   #
+  %a{annotate:rdoc:copy:ENV.each}
   def each: () -> ::Enumerator[[ String, String ], self]
           | () { ([ String, String ]) -> void } -> self
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.each      { |name, value| block } -> ENV
+  #   - ENV.each                              -> an_enumerator
+  #   - ENV.each_pair { |name, value| block } -> ENV
+  #   - ENV.each_pair                         -> an_enumerator
+  # -->
   # Yields each environment variable name and its value as a 2-element Array:
   #     h = {}
   #     ENV.each_pair { |name, value| h[name] = value } # => ENV
@@ -251,9 +460,15 @@ class ENVClass
   #     e.each { |name, value| h[name] = value } # => ENV
   #     h # => {"bar"=>"1", "foo"=>"0"}
   #
+  %a{annotate:rdoc:copy:ENV.each_pair}
   def each_pair: () -> ::Enumerator[[ String, String ], self]
                | () { ([ String, String ]) -> void } -> self
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.each_key { |name| block } -> ENV
+  #   - ENV.each_key                  -> an_enumerator
+  # -->
   # Yields each environment variable name:
   #     ENV.replace('foo' => '0', 'bar' => '1') # => ENV
   #     names = []
@@ -266,9 +481,15 @@ class ENVClass
   #     e.each { |name| names.push(name) } # => ENV
   #     names # => ["bar", "foo"]
   #
+  %a{annotate:rdoc:copy:ENV.each_key}
   def each_key: () -> ::Enumerator[[ String ], self]
               | () { (String name) -> void } -> self
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.each_value { |value| block } -> ENV
+  #   - ENV.each_value                   -> an_enumerator
+  # -->
   # Yields each environment variable value:
   #     ENV.replace('foo' => '0', 'bar' => '1') # => ENV
   #     values = []
@@ -281,9 +502,17 @@ class ENVClass
   #     e.each { |value| values.push(value) } # => ENV
   #     values # => ["1", "0"]
   #
+  %a{annotate:rdoc:copy:ENV.each_value}
   def each_value: () -> ::Enumerator[[ String ], self]
                 | () { (String value) -> void } -> self
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.delete(name)                           -> value
+  #   - ENV.delete(name) { |name| block }          -> value
+  #   - ENV.delete(missing_name)                   -> nil
+  #   - ENV.delete(missing_name) { |name| block }  -> block_value
+  # -->
   # Deletes the environment variable with `name` if it exists and returns its
   # value:
   #     ENV['foo'] = '0'
@@ -304,9 +533,15 @@ class ENVClass
   # Raises an exception if `name` is invalid. See [Invalid Names and
   # Values](#class-ENV-label-Invalid+Names+and+Values).
   #
+  %a{annotate:rdoc:copy:ENV.delete}
   def delete: (String name) -> String?
             | (String name) { (String) -> String } -> String
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.delete_if { |name, value| block } -> ENV
+  #   - ENV.delete_if                         -> an_enumerator
+  # -->
   # Yields each environment variable name and its value as a 2-element Array,
   # deleting each environment variable for which the block returns a truthy value,
   # and returning ENV (regardless of whether any deletions):
@@ -322,9 +557,15 @@ class ENVClass
   #     ENV # => {"foo"=>"0"}
   #     e.each { |name, value| name.start_with?('b') } # => ENV
   #
+  %a{annotate:rdoc:copy:ENV.delete_if}
   def delete_if: () -> ::Enumerator[[ String, String ], self]
                | () { (String name, String value) -> boolish } -> self
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.keep_if { |name, value| block } -> ENV
+  #   - ENV.keep_if                         -> an_enumerator
+  # -->
   # Yields each environment variable name and its value as a 2-element Array,
   # deleting each environment variable for which the block returns `false` or
   # `nil`, and returning ENV:
@@ -338,9 +579,14 @@ class ENVClass
   #     e.each { |name, value| name.start_with?('b') } # => ENV
   #     ENV # => {"bar"=>"1", "baz"=>"2"}
   #
+  %a{annotate:rdoc:copy:ENV.keep_if}
   def keep_if: () -> ::Enumerator[[ String, String ], self]
              | () { (String name, String value) -> boolish } -> self
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.slice(*names) -> hash of name/value pairs
+  # -->
   # Returns a Hash of the given ENV names and their corresponding values:
   #     ENV.replace('foo' => '0', 'bar' => '1', 'baz' => '2', 'bat' => '3')
   #     ENV.slice('foo', 'baz') # => {"foo"=>"0", "baz"=>"2"}
@@ -350,23 +596,39 @@ class ENVClass
   # Values](#class-ENV-label-Invalid+Names+and+Values)):
   #     ENV.slice('foo', 'bar', :bat) # Raises TypeError (no implicit conversion of Symbol into String)
   #
+  %a{annotate:rdoc:copy:ENV.slice}
   def slice: (*String names) -> ::Hash[String, String]
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.except(*keys) -> a_hash
+  # -->
   # Returns a hash except the given keys from ENV and their values.
   #
   #     ENV                       #=> {"LANG"=>"en_US.UTF-8", "TERM"=>"xterm-256color", "HOME"=>"/Users/rhc"}
   #     ENV.except("TERM","HOME") #=> {"LANG"=>"en_US.UTF-8"}
   #
+  %a{annotate:rdoc:copy:ENV.except}
   def except: (*String names) -> ::Hash[String, String]
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.clear -> ENV
+  # -->
   # Removes every environment variable; returns ENV:
   #     ENV.replace('foo' => '0', 'bar' => '1')
   #     ENV.size # => 2
   #     ENV.clear # => ENV
   #     ENV.size # => 0
   #
+  %a{annotate:rdoc:copy:ENV.clear}
   def clear: () -> self
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.reject { |name, value| block } -> hash of name/value pairs
+  #   - ENV.reject                         -> an_enumerator
+  # -->
   # Yields each environment variable name and its value as a 2-element Array.
   # Returns a Hash whose items are determined by the block. When the block returns
   # a truthy value, the name/value pair is added to the return Hash; otherwise the
@@ -378,9 +640,15 @@ class ENVClass
   #     e = ENV.reject
   #     e.each { |name, value| name.start_with?('b') } # => {"foo"=>"0"}
   #
+  %a{annotate:rdoc:copy:ENV.reject}
   def reject: () -> ::Enumerator[[ String, String ], self]
             | () { (String name, String value) -> boolish } -> self
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.reject! { |name, value| block } -> ENV or nil
+  #   - ENV.reject!                         -> an_enumerator
+  # -->
   # Similar to ENV.delete_if, but returns `nil` if no changes were made.
   #
   # Yields each environment variable name and its value as a 2-element Array,
@@ -398,9 +666,17 @@ class ENVClass
   #     ENV # => {"foo"=>"0"}
   #     e.each { |name, value| name.start_with?('b') } # => nil
   #
+  %a{annotate:rdoc:copy:ENV.reject!}
   def reject!: () -> ::Enumerator[[ String, String ], self?]
              | () { (String name, String value) -> boolish } -> self?
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.select { |name, value| block } -> hash of name/value pairs
+  #   - ENV.select                         -> an_enumerator
+  #   - ENV.filter { |name, value| block } -> hash of name/value pairs
+  #   - ENV.filter                         -> an_enumerator
+  # -->
   # ENV.filter is an alias for ENV.select.
   #
   # Yields each environment variable name and its value as a 2-element Array,
@@ -416,9 +692,17 @@ class ENVClass
   #     e = ENV.filter # => #<Enumerator: {"bar"=>"1", "baz"=>"2", "foo"=>"0"}:filter>
   #     e.each { |name, value | name.start_with?('b') } # => {"bar"=>"1", "baz"=>"2"}
   #
+  %a{annotate:rdoc:copy:ENV.select}
   def select: () -> ::Enumerator[[ String, String ], ::Hash[String, String]]
             | () { (String name, String value) -> boolish } -> ::Hash[String, String]
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.select { |name, value| block } -> hash of name/value pairs
+  #   - ENV.select                         -> an_enumerator
+  #   - ENV.filter { |name, value| block } -> hash of name/value pairs
+  #   - ENV.filter                         -> an_enumerator
+  # -->
   # ENV.filter is an alias for ENV.select.
   #
   # Yields each environment variable name and its value as a 2-element Array,
@@ -434,8 +718,16 @@ class ENVClass
   #     e = ENV.filter # => #<Enumerator: {"bar"=>"1", "baz"=>"2", "foo"=>"0"}:filter>
   #     e.each { |name, value | name.start_with?('b') } # => {"bar"=>"1", "baz"=>"2"}
   #
+  %a{annotate:rdoc:copy:ENV.filter}
   alias filter select
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.select! { |name, value| block } -> ENV or nil
+  #   - ENV.select!                         -> an_enumerator
+  #   - ENV.filter! { |name, value| block } -> ENV or nil
+  #   - ENV.filter!                         -> an_enumerator
+  # -->
   # ENV.filter! is an alias for ENV.select!.
   #
   # Yields each environment variable name and its value as a 2-element Array,
@@ -466,9 +758,17 @@ class ENVClass
   #     ENV # => {"bar"=>"1", "baz"=>"2"}
   #     e.each { |name, value| true } # => nil
   #
+  %a{annotate:rdoc:copy:ENV.select!}
   def select!: () -> ::Enumerator[[ String, String ], self?]
              | () { (String name, String value) -> boolish } -> self?
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.select! { |name, value| block } -> ENV or nil
+  #   - ENV.select!                         -> an_enumerator
+  #   - ENV.filter! { |name, value| block } -> ENV or nil
+  #   - ENV.filter!                         -> an_enumerator
+  # -->
   # ENV.filter! is an alias for ENV.select!.
   #
   # Yields each environment variable name and its value as a 2-element Array,
@@ -499,8 +799,13 @@ class ENVClass
   #     ENV # => {"bar"=>"1", "baz"=>"2"}
   #     e.each { |name, value| true } # => nil
   #
+  %a{annotate:rdoc:copy:ENV.filter!}
   alias filter! select!
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.shift -> [name, value] or nil
+  # -->
   # Removes the first environment variable from ENV and returns a 2-element Array
   # containing its name and value:
   #     ENV.replace('foo' => '0', 'bar' => '1')
@@ -513,8 +818,13 @@ class ENVClass
   #
   # Returns `nil` if the environment is empty.
   #
+  %a{annotate:rdoc:copy:ENV.shift}
   def shift: () -> [ String, String ]?
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.invert -> hash of value/name pairs
+  # -->
   # Returns a Hash whose keys are the ENV values, and whose values are the
   # corresponding ENV names:
   #     ENV.replace('foo' => '0', 'bar' => '1')
@@ -528,8 +838,13 @@ class ENVClass
   # the order of overwriting is also OS-dependent. See [About
   # Ordering](#class-ENV-label-About+Ordering).
   #
+  %a{annotate:rdoc:copy:ENV.invert}
   def invert: () -> ::Hash[String, String]
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.replace(hash) -> ENV
+  # -->
   # Replaces the entire content of the environment variables with the name/value
   # pairs in the given `hash`; returns ENV.
   #
@@ -543,8 +858,16 @@ class ENVClass
   #     ENV.replace('foo' => '0', 'bar' => 1) # Raises TypeError (no implicit conversion of Integer into String)
   #     ENV.to_hash # => {"bar"=>"1", "foo"=>"0"}
   #
+  %a{annotate:rdoc:copy:ENV.replace}
   def replace: (Hash[String, String]) -> self
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.update(hash)                                     -> ENV
+  #   - ENV.update(hash) { |name, env_val, hash_val| block } -> ENV
+  #   - ENV.merge!(hash)                                     -> ENV
+  #   - ENV.merge!(hash) { |name, env_val, hash_val| block } -> ENV
+  # -->
   # ENV.update is an alias for ENV.merge!.
   #
   # Adds to ENV each key/value pair in the given `hash`; returns ENV:
@@ -577,9 +900,17 @@ class ENVClass
   # Note that for the exceptions above, hash pairs preceding an invalid name or
   # value are processed normally; those following are ignored.
   #
+  %a{annotate:rdoc:copy:ENV.update}
   def update: (Hash[String, String?]) -> self
             | (Hash[String, String?]) { (String name, String env_val, String? hash_val) -> String } -> self
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.update(hash)                                     -> ENV
+  #   - ENV.update(hash) { |name, env_val, hash_val| block } -> ENV
+  #   - ENV.merge!(hash)                                     -> ENV
+  #   - ENV.merge!(hash) { |name, env_val, hash_val| block } -> ENV
+  # -->
   # ENV.update is an alias for ENV.merge!.
   #
   # Adds to ENV each key/value pair in the given `hash`; returns ENV:
@@ -612,26 +943,46 @@ class ENVClass
   # Note that for the exceptions above, hash pairs preceding an invalid name or
   # value are processed normally; those following are ignored.
   #
+  %a{annotate:rdoc:copy:ENV.merge!}
   alias merge! update
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.rehash -> nil
+  # -->
   # (Provided for compatibility with Hash.)
   #
   # Does not modify ENV; returns `nil`.
   #
+  %a{annotate:rdoc:copy:ENV.rehash}
   def rehash: () -> nil
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.to_a -> array of 2-element arrays
+  # -->
   # Returns the contents of ENV as an Array of 2-element Arrays, each of which is
   # a name/value pair:
   #     ENV.replace('foo' => '0', 'bar' => '1')
   #     ENV.to_a # => [["bar", "1"], ["foo", "0"]]
   #
+  %a{annotate:rdoc:copy:ENV.to_a}
   def to_a: () -> ::Array[[ String, String ]]
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.to_s -> "ENV"
+  # -->
   # Returns String 'ENV':
   #     ENV.to_s # => "ENV"
   #
+  %a{annotate:rdoc:copy:ENV.to_s}
   def to_s: () -> "ENV"
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.key(value) -> name or nil
+  # -->
   # Returns the name of the first environment variable with `value`, if it exists:
   #     ENV.replace('foo' => '0', 'bar' => '0')
   #     ENV.key('0') # => "foo"
@@ -646,30 +997,52 @@ class ENVClass
   #
   # See [Invalid Names and Values](#class-ENV-label-Invalid+Names+and+Values).
   #
+  %a{annotate:rdoc:copy:ENV.key}
   def key: (String value) -> String?
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.length -> an_integer
+  #   - ENV.size   -> an_integer
+  # -->
   # Returns the count of environment variables:
   #     ENV.replace('foo' => '0', 'bar' => '1')
   #     ENV.length # => 2
   #     ENV.size # => 2
   #
+  %a{annotate:rdoc:copy:ENV.size}
   def size: () -> Integer
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.length -> an_integer
+  #   - ENV.size   -> an_integer
+  # -->
   # Returns the count of environment variables:
   #     ENV.replace('foo' => '0', 'bar' => '1')
   #     ENV.length # => 2
   #     ENV.size # => 2
   #
+  %a{annotate:rdoc:copy:ENV.length}
   alias length size
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.empty? -> true or false
+  # -->
   # Returns `true` when there are no environment variables, `false` otherwise:
   #     ENV.clear
   #     ENV.empty? # => true
   #     ENV['foo'] = '0'
   #     ENV.empty? # => false
   #
+  %a{annotate:rdoc:copy:ENV.empty?}
   def empty?: () -> bool
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.keys -> array of names
+  # -->
   # Returns all variable names in an Array:
   #     ENV.replace('foo' => '0', 'bar' => '1')
   #     ENV.keys # => ['bar', 'foo']
@@ -679,8 +1052,13 @@ class ENVClass
   #
   # Returns the empty Array if ENV is empty.
   #
+  %a{annotate:rdoc:copy:ENV.keys}
   def keys: () -> ::Array[String]
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.values -> array of values
+  # -->
   # Returns all environment variable values in an Array:
   #     ENV.replace('foo' => '0', 'bar' => '1')
   #     ENV.values # => ['1', '0']
@@ -690,8 +1068,13 @@ class ENVClass
   #
   # Returns the empty Array if ENV is empty.
   #
+  %a{annotate:rdoc:copy:ENV.values}
   def values: () -> ::Array[String]
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.values_at(*names) -> array of values
+  # -->
   # Returns an Array containing the environment variable values associated with
   # the given names:
   #     ENV.replace('foo' => '0', 'bar' => '1', 'baz' => '2')
@@ -705,8 +1088,16 @@ class ENVClass
   # Raises an exception if any name is invalid. See [Invalid Names and
   # Values](#class-ENV-label-Invalid+Names+and+Values).
   #
+  %a{annotate:rdoc:copy:ENV.values_at}
   def values_at: (*String names) -> ::Array[String?]
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.include?(name) -> true or false
+  #   - ENV.has_key?(name) -> true or false
+  #   - ENV.member?(name)  -> true or false
+  #   - ENV.key?(name)     -> true or false
+  # -->
   # ENV.has_key?, ENV.member?, and ENV.key? are aliases for ENV.include?.
   #
   # Returns `true` if there is an environment variable with the given `name`:
@@ -732,8 +1123,16 @@ class ENVClass
   # Raises an exception if `name` is not a String:
   #     ENV.include?(Object.new) # TypeError (no implicit conversion of Object into String)
   #
+  %a{annotate:rdoc:copy:ENV.include?}
   def include?: (String name) -> bool
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.include?(name) -> true or false
+  #   - ENV.has_key?(name) -> true or false
+  #   - ENV.member?(name)  -> true or false
+  #   - ENV.key?(name)     -> true or false
+  # -->
   # ENV.has_key?, ENV.member?, and ENV.key? are aliases for ENV.include?.
   #
   # Returns `true` if there is an environment variable with the given `name`:
@@ -759,8 +1158,16 @@ class ENVClass
   # Raises an exception if `name` is not a String:
   #     ENV.include?(Object.new) # TypeError (no implicit conversion of Object into String)
   #
+  %a{annotate:rdoc:copy:ENV.member?}
   alias member? include?
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.include?(name) -> true or false
+  #   - ENV.has_key?(name) -> true or false
+  #   - ENV.member?(name)  -> true or false
+  #   - ENV.key?(name)     -> true or false
+  # -->
   # ENV.has_key?, ENV.member?, and ENV.key? are aliases for ENV.include?.
   #
   # Returns `true` if there is an environment variable with the given `name`:
@@ -786,8 +1193,14 @@ class ENVClass
   # Raises an exception if `name` is not a String:
   #     ENV.include?(Object.new) # TypeError (no implicit conversion of Object into String)
   #
+  %a{annotate:rdoc:copy:ENV.has_key?}
   alias has_key? include?
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.value?(value)     -> true or false
+  #   - ENV.has_value?(value) -> true or false
+  # -->
   # Returns `true` if `value` is the value for some environment variable name,
   # `false` otherwise:
   #     ENV.replace('foo' => '0', 'bar' => '1')
@@ -796,8 +1209,14 @@ class ENVClass
   #     ENV.value?('2') # => false
   #     ENV.has_value?('2') # => false
   #
+  %a{annotate:rdoc:copy:ENV.has_value?}
   def has_value?: (String value) -> bool
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.value?(value)     -> true or false
+  #   - ENV.has_value?(value) -> true or false
+  # -->
   # Returns `true` if `value` is the value for some environment variable name,
   # `false` otherwise:
   #     ENV.replace('foo' => '0', 'bar' => '1')
@@ -806,8 +1225,16 @@ class ENVClass
   #     ENV.value?('2') # => false
   #     ENV.has_value?('2') # => false
   #
+  %a{annotate:rdoc:copy:ENV.value?}
   alias value? has_value?
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.include?(name) -> true or false
+  #   - ENV.has_key?(name) -> true or false
+  #   - ENV.member?(name)  -> true or false
+  #   - ENV.key?(name)     -> true or false
+  # -->
   # ENV.has_key?, ENV.member?, and ENV.key? are aliases for ENV.include?.
   #
   # Returns `true` if there is an environment variable with the given `name`:
@@ -833,14 +1260,24 @@ class ENVClass
   # Raises an exception if `name` is not a String:
   #     ENV.include?(Object.new) # TypeError (no implicit conversion of Object into String)
   #
+  %a{annotate:rdoc:copy:ENV.key?}
   alias key? include?
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.to_hash -> hash of name/value pairs
+  # -->
   # Returns a Hash containing all name/value pairs from ENV:
   #     ENV.replace('foo' => '0', 'bar' => '1')
   #     ENV.to_hash # => {"bar"=>"1", "foo"=>"0"}
   #
+  %a{annotate:rdoc:copy:ENV.to_hash}
   def to_hash: () -> ::Hash[String, String]
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.assoc(name) -> [name, value] or nil
+  # -->
   # Returns a 2-element Array containing the name and value of the environment
   # variable for `name` if it exists:
   #     ENV.replace('foo' => '0', 'bar' => '1')
@@ -862,8 +1299,13 @@ class ENVClass
   # Raises an exception if `name` is not a String:
   #     ENV.assoc(Object.new) # TypeError (no implicit conversion of Object into String)
   #
+  %a{annotate:rdoc:copy:ENV.assoc}
   def assoc: (String name) -> [ String, String ]?
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - ENV.rassoc(value) -> [name, value] or nil
+  # -->
   # Returns a 2-element Array containing the name and value of the **first**
   # **found** environment variable that has value `value`, if one exists:
   #     ENV.replace('foo' => '0', 'bar' => '0')
@@ -874,8 +1316,13 @@ class ENVClass
   #
   # Returns `nil` if there is no such environment variable.
   #
+  %a{annotate:rdoc:copy:ENV.rassoc}
   def rassoc: (String value) -> [ String, String ]?
 end
 
-# EnvClass is a temporary class prepared for ENV typing.
+# <!-- rdoc-file=hash.c -->
+# ENV is a Hash-like accessor for environment variables.
+#
+# See ENV (the class) for more details.
+#
 ENV: ENVClass