rbs 3.6.1 → 3.9.5

data/stdlib/rdoc/0/rdoc.rbs

@@ -1,9 +1,3 @@
-# <!-- rdoc-file=lib/rdoc/rubygems_hook.rb -->
-# Gem::RDoc provides methods to generate RDoc and ri data for installed gems
-# upon gem installation.
-#
-# This file is automatically required by RubyGems 1.9 and newer.
-#
 # <!-- rdoc-file=lib/rdoc.rb -->
 # RDoc produces documentation for Ruby source files by parsing the source and
 # extracting the definition for classes, modules, methods, includes and
@@ -21,8 +15,7 @@
 # If you want to use RDoc to create documentation for your Ruby source files,
 # see RDoc::Markup and refer to `rdoc --help` for command line usage.
 #
-# If you want to set the default markup format see
-# RDoc::Markup@Supported+Formats
+# If you want to set the default markup format see RDoc::Markup@Markup+Formats
 #
 # If you want to store rdoc configuration in your gem (such as the default
 # markup format) see RDoc::Options@Saved+Options
@@ -56,6 +49,18 @@
 #     of Keiju ISHITSUKA of Nippon Rational Inc, who produced the Ruby parser
 #     for irb and the rtags package.
 #
+# <!-- rdoc-file=lib/rdoc/rubygems_hook.rb -->
+# This class is referenced by RubyGems to create documents. All implementations
+# are moved to the above RubyGemsHook.
+#
+# This class does nothing when this RDoc is installed as a normal gem or a
+# bundled gem.
+#
+# This class does generate/remove documents for compatibility when this RDoc is
+# installed as a default gem.
+#
+# We can remove this when all maintained RubyGems remove `rubygems/rdoc.rb`.
+#
 module RDoc
   # <!-- rdoc-file=lib/rdoc/token_stream.rb -->
   # A TokenStream is a list of tokens, gathered during the parse of some entity

data/stdlib/resolv/0/resolv.rbs

@@ -126,10 +126,14 @@ class Resolv
 
   # <!--
   #   rdoc-file=lib/resolv.rb
-  #   - new(resolvers=nil, use_ipv6: nil)
+  #   - new(resolvers=(arg_not_set = true; nil), use_ipv6: (keyword_not_set = true; nil))
   # -->
   # Creates a new Resolv using `resolvers`.
   #
+  # If `resolvers` is not given, a hash, or `nil`, uses a Hosts resolver and and a
+  # DNS resolver.  If `resolvers` is a hash, uses the hash as configuration for
+  # the DNS resolver.
+  #
   def initialize: (?Resolv::Hosts | Resolv::DNS resolvers) -> untyped
 end
 
@@ -292,7 +296,6 @@ class Resolv::DNS
   # *   Resolv::DNS::Resource::IN::TXT
   # *   Resolv::DNS::Resource::IN::WKS
   #
-  #
   # Returned resource is represented as a Resolv::DNS::Resource instance, i.e.
   # Resolv::DNS::Resource::IN::A.
   #
@@ -341,8 +344,10 @@ class Resolv::DNS
   #
   # nil
   # :   Uses /etc/resolv.conf.
+  #
   # String
   # :   Path to a file using /etc/resolv.conf's format.
+  #
   # Hash
   # :   Must contain :nameserver, :search and :ndots keys.
   #
@@ -355,12 +360,10 @@ class Resolv::DNS
   # *   :nameserver => '8.8.8.8'
   # *   :nameserver => ['8.8.8.8', '8.8.4.4']
   #
-  #
   # The value of :nameserver_port should be an array of pair of nameserver address
   # and port number.
   # *   :nameserver_port => [['8.8.8.8', 53], ['8.8.4.4', 53]]
   #
-  #
   # Example:
   #
   #     Resolv::DNS.new(:nameserver => ['210.251.121.21'],
@@ -463,7 +466,7 @@ end
 class Resolv::DNS::Message
   def self.decode: (String m) -> instance
 
-  def ==: (instance other) -> bool
+  def ==: (self other) -> bool
 
   def aa: () -> Integer
 
@@ -555,7 +558,7 @@ class Resolv::DNS::Message::MessageDecoder
 
   private
 
-  def initialize: (String data) { (instance) -> void } -> untyped
+  def initialize: (String data) { (self) -> void } -> untyped
 end
 
 class Resolv::DNS::Message::MessageEncoder
@@ -594,12 +597,13 @@ class Resolv::DNS::Name
   #
   # Name
   # :   returns `arg`.
+  #
   # String
   # :   Creates a new Name.
   #
   def self.create: (Resolv::DNS::dns_name arg) -> untyped
 
-  def ==: (instance other) -> bool
+  def ==: (self other) -> bool
 
   def []: (Integer i) -> Resolv::DNS::Label::Str?
 
@@ -635,7 +639,7 @@ class Resolv::DNS::Name
   #     p Resolv::DNS::Name.create("x.y.z.").subdomain_of?(domain) #=> false
   #     p Resolv::DNS::Name.create("w.z").subdomain_of?(domain) #=> false
   #
-  def subdomain_of?: (instance other) -> bool
+  def subdomain_of?: (self other) -> bool
 
   def to_a: () -> Array[Resolv::DNS::Label::Str]
 
@@ -1487,14 +1491,14 @@ class Resolv::IPv4
   #
   def self.create: (String | instance arg) -> instance
 
-  def ==: (instance other) -> bool
+  def ==: (self other) -> bool
 
   # <!-- rdoc-file=lib/resolv.rb -->
   # The raw IPv4 address as a String.
   #
   def address: () -> String
 
-  def eql?: (instance other) -> bool
+  def eql?: (self other) -> bool
 
   def hash: () -> Integer
 
@@ -1534,19 +1538,20 @@ class Resolv::IPv6
   #
   # IPv6
   # :   returns `arg`.
+  #
   # String
   # :   `arg` must match one of the IPv6::Regex* constants
   #
   def self.create: (String | instance arg) -> instance
 
-  def ==: (instance other) -> bool
+  def ==: (self other) -> bool
 
   # <!-- rdoc-file=lib/resolv.rb -->
   # The raw IPv6 address as a String.
   #
   def address: () -> String
 
-  def eql?: (instance other) -> bool
+  def eql?: (self other) -> bool
 
   def hash: () -> Integer
 
@@ -1617,6 +1622,7 @@ class Resolv::LOC::Alt
   #
   # LOC::Alt
   # :   returns `arg`.
+  #
   # String
   # :   `arg` must match the LOC::Alt::Regex constant
   #
@@ -1663,6 +1669,7 @@ class Resolv::LOC::Coord
   #
   # LOC::Coord
   # :   returns `arg`.
+  #
   # String
   # :   `arg` must match the LOC::Coord::Regex constant
   #
@@ -1712,6 +1719,7 @@ class Resolv::LOC::Size
   #
   # LOC::Size
   # :   returns `arg`.
+  #
   # String
   # :   `arg` must match the LOC::Size::Regex constant
   #
@@ -1782,6 +1790,7 @@ class Resolv::MDNS < Resolv::DNS
   # nil
   # :   Uses the default mDNS addresses
   #
+  #
   # Hash
   # :   Must contain :nameserver or :nameserver_port like Resolv::DNS#initialize.
   #

data/stdlib/ripper/0/ripper.rbs

@@ -55,13 +55,11 @@
 #     Inside](http://www.rubyinside.com/using-ripper-to-see-how-ruby-is-parsing-
 #     your-code-5270.html)
 #
-#
 # ## Requirements
 #
 # *   ruby 1.9 (support CVS HEAD only)
 # *   bison 1.28 or later (Other yaccs do not work)
 #
-#
 # ## License
 #
 # Ruby License.

data/stdlib/securerandom/0/securerandom.rbs

@@ -14,7 +14,6 @@
 # *   /dev/urandom
 # *   Win32
 #
-#
 # SecureRandom is extended by the Random::Formatter module which defines the
 # following methods:
 #
@@ -29,7 +28,6 @@
 # *   urlsafe_base64
 # *   uuid
 #
-#
 # These methods are usable as class methods of SecureRandom such as
 # `SecureRandom.hex`.
 #
@@ -39,6 +37,13 @@
 module SecureRandom
   extend Random::Formatter
 
+  # <!--
+  #   rdoc-file=lib/securerandom.rb
+  #   - alphanumeric(n = nil, chars: ALPHANUMERIC)
+  # -->
+  # Compatibility methods for Ruby 3.2, we can remove this after dropping to
+  # support Ruby 3.2
+  #
   def self.alphanumeric: (?Integer?) -> String
 
   def self.base64: (?Integer?) -> String

data/stdlib/shellwords/0/shellwords.rbs

@@ -4,9 +4,11 @@
 # This module manipulates strings according to the word parsing rules of the
 # UNIX Bourne shell.
 #
-# The shellwords() function was originally a port of shellwords.pl, but modified
-# to conform to the Shell & Utilities volume of the IEEE Std 1003.1-2008, 2016
-# Edition [1].
+# The `shellwords()` function was originally a port of shellwords.pl, but
+# modified to conform to [the Shell & Utilities volume of the IEEE Std
+# 1003.1-2008, 2016
+# Edition](http://pubs.opengroup.org/onlinepubs/9699919799/utilities/contents.ht
+# ml)
 #
 # ### Usage
 #
@@ -58,17 +60,9 @@
 # *   Wakou Aoyama
 # *   Akinori MUSHA <knu@iDaemons.org>
 #
-#
 # ### Contact
 # *   Akinori MUSHA <knu@iDaemons.org> (current maintainer)
 #
-#
-# ### Resources
-#
-# 1: [IEEE Std 1003.1-2008, 2016 Edition, the Shell & Utilities
-# volume](http://pubs.opengroup.org/onlinepubs/9699919799/utilities/contents.htm
-# l)
-#
 module Shellwords
   # <!--
   #   rdoc-file=lib/shellwords.rb
@@ -77,6 +71,8 @@ module Shellwords
   # Escapes a string so that it can be safely used in a Bourne shell command line.
   #  `str` can be a non-string object that responds to `to_s`.
   #
+  # `str` must not contain NUL characters because of nature of `exec` system call.
+  #
   # Note that a resulted string should be used unquoted and is not intended for
   # use in double quotes nor in single quotes.
   #
@@ -114,7 +110,7 @@ module Shellwords
   #
   # All elements are joined into a single string with fields separated by a space,
   # where each element is escaped for the Bourne shell and stringified using
-  # `to_s`.
+  # `to_s`. See also Shellwords.shellescape.
   #
   #     ary = ["There's", "a", "time", "and", "place", "for", "everything"]
   #     argv = Shellwords.join(ary)
@@ -142,6 +138,9 @@ module Shellwords
   #     argv = Shellwords.split('here are "two words"')
   #     argv #=> ["here", "are", "two words"]
   #
+  # `line` must not contain NUL characters because of nature of `exec` system
+  # call.
+  #
   # Note, however, that this is not a command line parser.  Shell metacharacters
   # except for the single and double quotes and backslash are not treated as such.
   #

data/stdlib/singleton/0/singleton.rbs

@@ -53,7 +53,6 @@
 # *   Overriding Klass#clone and Klass#dup to raise TypeErrors to prevent
 #     cloning or duping.
 #
-#
 # ## Singleton and Marshal
 #
 # By default Singleton's #_dump(depth) returns the empty string. Marshalling by

data/stdlib/socket/0/addrinfo.rbs

@@ -541,7 +541,7 @@ class Addrinfo
 
   def marshal_dump: () -> String
 
-  def marshal_load: (String) -> instance
+  def marshal_load: (String) -> self
 
   # <!--
   #   rdoc-file=ext/socket/raddrinfo.c
@@ -642,7 +642,6 @@ class Addrinfo
   # *   `Socket.sockaddr_in(80, "www.ruby-lang.org")`
   # *   `Socket.sockaddr_un("/tmp/sock")`
   #
-  #
   # In an AF_INET/AF_INET6 sockaddr array, the 4th element, numeric IP address, is
   # used to construct socket address in the Addrinfo instance. If the 3rd element,
   # textual host name, is non-nil, it is also recorded but used only for

data/stdlib/socket/0/basic_socket.rbs

@@ -82,7 +82,6 @@ class BasicSocket < IO
   #     (127.0.0.1).
   # *   IPv6 unspecified address (::) is replaced by IPv6 loopback address (::1).
   #
-  #
   # If the local address is not suitable for connect, SocketError is raised. IPv4
   # and IPv6 address which port is 0 is not suitable for connect. Unix domain
   # socket which has no path is not suitable for connect.
@@ -202,7 +201,6 @@ class BasicSocket < IO
   #     Socket::SO_REUSEADDR. A string or symbol of the name, possibly without
   #     prefix, is also accepted.
   #
-  #
   # ### Examples
   #
   # Some socket options are integers with boolean values, in this case #getsockopt
@@ -302,7 +300,6 @@ class BasicSocket < IO
   # *   `buf` - destination String buffer
   # *   `options` - keyword hash, supporting `exception: false`
   #
-  #
   # ### Example
   #     serv = TCPServer.new("127.0.0.1", 0)
   #     af, port, host, addr = serv.addr
@@ -518,10 +515,8 @@ class BasicSocket < IO
   #         int is passed as for an Integer. Note that `false` must be passed, not
   #         `nil`.
   #     *   String: the string's data and length is passed to the socket.
-  #
   # *   `socketoption` is an instance of Socket::Option
   #
-  #
   # ### Examples
   #
   # Some socket options are integers with boolean values, in this case #setsockopt

data/stdlib/socket/0/socket.rbs

@@ -22,12 +22,10 @@
 # *   Socket::PF_UNIX
 # *   etc.
 #
-#
 # **type:** The type of communications between the two endpoints, typically
 # *   Socket::SOCK_STREAM
 # *   Socket::SOCK_DGRAM.
 #
-#
 # **protocol:** Typically *zero*. This may be used to identify a variant of a
 # protocol.
 #
@@ -37,7 +35,6 @@
 # *   a zero-length string which specifies INADDR_ANY
 # *   an integer (interpreted as binary address in host byte order).
 #
-#
 # ### Quick start
 #
 # Many of the classes, such as TCPSocket, UDPSocket or UNIXSocket, ease the use
@@ -94,10 +91,13 @@
 #
 # TCP client socket
 # :   Socket.tcp, TCPSocket.open
+#
 # TCP server socket
 # :   Socket.tcp_server_loop, TCPServer.open
+#
 # UNIX client socket
 # :   Socket.unix, UNIXSocket.open
+#
 # UNIX server socket
 # :   Socket.unix_server_loop, UNIXServer.open
 #
@@ -108,7 +108,6 @@
 # *   Sam Roberts
 # *   *Programming Ruby* from The Pragmatic Bookshelf.
 #
-#
 # Much material in this documentation is taken with permission from *Programming
 # Ruby* from The Pragmatic Bookshelf.
 #
@@ -180,7 +179,6 @@ class Socket < BasicSocket
   #     cannot be released since gethostbyname() is not thread safe.)
   # *   This method uses gethostbyname() function already removed from POSIX.
   #
-  #
   # This method obtains the host information for *address*.
   #
   #     p Socket.gethostbyaddr([221,186,184,68].pack("CCCC"))
@@ -209,7 +207,6 @@ class Socket < BasicSocket
   #     cannot be released since gethostbyname() is not thread safe.)
   # *   This method uses gethostbyname() function already removed from POSIX.
   #
-  #
   # This method obtains the host information for *hostname*.
   #
   #     p Socket.gethostbyname("hal") #=> ["localhost", ["hal"], 2, "\x7F\x00\x00\x01"]
@@ -281,7 +278,6 @@ class Socket < BasicSocket
   # *   3-elements array such as ["AF_INET", 80, "127.0.0.1"]
   # *   4-elements array such as ["AF_INET", 80, ignored, "127.0.0.1"]
   #
-  #
   # *flags* should be bitwise OR of Socket::NI_* constants.
   #
   # Note: The last form is compatible with IPSocket#addr and IPSocket#peeraddr.
@@ -462,13 +458,38 @@ class Socket < BasicSocket
   # -->
   # creates a new socket object connected to host:port using TCP/IP.
   #
+  # Starting from Ruby 3.4, this method operates according to the Happy Eyeballs
+  # Version 2 ([RFC 8305](https://datatracker.ietf.org/doc/html/rfc8305))
+  # algorithm by default.
+  #
+  # For details on Happy Eyeballs Version 2, see
+  # [Socket.tcp_fast_fallback=](rdoc-ref:Socket.tcp_fast_fallback=).
+  #
+  # To make it behave the same as in Ruby 3.3 and earlier, explicitly specify the
+  # option fast_fallback:false. Or, setting Socket.tcp_fast_fallback=false will
+  # disable Happy Eyeballs Version 2 not only for this method but for all Socket
+  # globally.
+  #
   # If local_host:local_port is given, the socket is bound to it.
   #
   # The optional last argument *opts* is options represented by a hash. *opts* may
   # have following options:
   #
+  # :resolv_timeout
+  # :   Specifies the timeout in seconds from when the hostname resolution starts.
+  #
   # :connect_timeout
-  # :   specify the timeout in seconds.
+  # :   This method sequentially attempts connecting to all candidate destination
+  #     addresses.
+  #     The `connect_timeout` specifies the timeout in seconds from the start of
+  #     the connection attempt to the last candidate.
+  #     By default, all connection attempts continue until the timeout occurs.
+  #     When `fast_fallback:false` is explicitly specified,
+  #     a timeout is set for each connection attempt and any connection attempt
+  #     that exceeds its timeout will be canceled.
+  #
+  # :fast_fallback
+  # :   Enables the Happy Eyeballs Version 2 algorithm (enabled by default).
   #
   #
   # If a block is given, the block is called with the socket. The value of the
@@ -832,7 +853,6 @@ class Socket < BasicSocket
   # *   `local_sockaddr` - the `struct` sockaddr contained in a string or an
   #     Addrinfo object
   #
-  #
   # ### Example
   #     require 'socket'
   #
@@ -873,7 +893,6 @@ class Socket < BasicSocket
   # *   Errno::EOPNOTSUPP - the socket type of the `socket` does not support
   #     binding to an address
   #
-  #
   # On unix-based based systems if the address family of the calling `socket` is
   # Socket::AF_UNIX the follow exceptions may be raised if the call to *bind*
   # fails:
@@ -892,7 +911,6 @@ class Socket < BasicSocket
   #     *sockaddr* is not a directory
   # *   Errno::EROFS - the name would reside on a read only filesystem
   #
-  #
   # ### Windows Exceptions
   # On Windows systems the following system exceptions may be raised if the call
   # to *bind* fails:
@@ -908,7 +926,6 @@ class Socket < BasicSocket
   # *   Errno::ENOBUFS - no buffer space is available
   # *   Errno::ENOTSOCK - the `socket` argument does not refer to a socket
   #
-  #
   # ### See
   # *   bind manual pages on unix-based systems
   # *   bind function in Microsoft's Winsock functions reference
@@ -926,7 +943,6 @@ class Socket < BasicSocket
   # *   `remote_sockaddr` - the `struct` sockaddr contained in a string or
   #     Addrinfo object
   #
-  #
   # ### Example:
   #     # Pull down Google's web page
   #     require 'socket'
@@ -981,7 +997,6 @@ class Socket < BasicSocket
   # *   Errno::ETIMEDOUT - the attempt to connect timed out before a connection
   #     was made.
   #
-  #
   # On unix-based systems if the address family of the calling `socket` is AF_UNIX
   # the follow exceptions may be raised if the call to *connect* fails:
   # *   Errno::EIO - an i/o error occurred while reading from or writing to the
@@ -995,7 +1010,6 @@ class Socket < BasicSocket
   # *   Errno::ENOTDIR - a component of the path prefix of the pathname in
   #     *sockaddr* is not a directory
   #
-  #
   # ### Windows Exceptions
   # On Windows systems the following system exceptions may be raised if the call
   # to *connect* fails:
@@ -1028,7 +1042,6 @@ class Socket < BasicSocket
   # *   Errno::EACCES - the attempt to connect the datagram socket to the
   #     broadcast address failed
   #
-  #
   # ### See
   # *   connect manual pages on unix-based systems
   # *   connect function in Microsoft's Winsock functions reference
@@ -1044,7 +1057,8 @@ class Socket < BasicSocket
   # otherwise an exception is raised.
   #
   # ### Parameter
-  #     # +remote_sockaddr+ - the +struct+ sockaddr contained in a string or Addrinfo object
+  # *   `remote_sockaddr` - the `struct` sockaddr contained in a string or
+  #     Addrinfo object
   #
   # ### Example:
   #     # Pull down Google's web page
@@ -1079,7 +1093,7 @@ class Socket < BasicSocket
   # the symbol `:wait_writable` instead.
   #
   # ### See
-  #     # Socket#connect
+  # *   Socket#connect
   #
   def connect_nonblock: (untyped addr, ?exception: untyped) -> (Integer | :wait_writable)
 
@@ -1102,7 +1116,6 @@ class Socket < BasicSocket
   # ### Parameter
   # *   `backlog` - the maximum length of the queue for pending connections.
   #
-  #
   # ### Example 1
   #     require 'socket'
   #     include Socket::Constants
@@ -1139,7 +1152,6 @@ class Socket < BasicSocket
   # *   Errno::ENOBUFS - insufficient resources are available in the system to
   #     complete the call
   #
-  #
   # ### Windows Exceptions
   # On Windows systems the following system exceptions may be raised if the call
   # to *listen* fails:
@@ -1159,7 +1171,6 @@ class Socket < BasicSocket
   # *   Errno::EOPNOTSUPP - the referenced `socket` is not a type that supports
   #     the *listen* method
   #
-  #
   # ### See
   # *   listen manual pages on unix-based systems
   # *   listen function in Microsoft's Winsock functions reference
@@ -1180,7 +1191,6 @@ class Socket < BasicSocket
   # *   `maxlen` - the maximum number of bytes to receive from the socket
   # *   `flags` - zero or more of the `MSG_` options
   #
-  #
   # ### Example
   #     # In one file, start this first
   #     require 'socket'
@@ -1236,7 +1246,6 @@ class Socket < BasicSocket
   # *   Errno::ETIMEDOUT - the connection timed out during connection
   #     establishment or due to a transmission timeout on an active connection
   #
-  #
   # ### Windows Exceptions
   # On Windows systems the following system exceptions may be raised if the call
   # to *recvfrom* fails:
@@ -1298,7 +1307,6 @@ class Socket < BasicSocket
   # *   `outbuf` - destination String buffer
   # *   `opts` - keyword hash, supporting `exception: false`
   #
-  #
   # ### Example
   #     # In one file, start this first
   #     require 'socket'
@@ -4122,7 +4130,6 @@ class Socket::AncillaryData
   # *   Socket::AF_UNIX, "AF_UNIX", "UNIX", :AF_UNIX, :UNIX
   # *   etc.
   #
-  #
   # *cmsg_level* should be an integer, a string or a symbol.
   # *   Socket::SOL_SOCKET, "SOL_SOCKET", "SOCKET", :SOL_SOCKET and :SOCKET
   # *   Socket::IPPROTO_IP, "IP" and :IP
@@ -4130,7 +4137,6 @@ class Socket::AncillaryData
   # *   Socket::IPPROTO_TCP, "TCP" and :TCP
   # *   etc.
   #
-  #
   # *cmsg_type* should be an integer, a string or a symbol. If a string/symbol is
   # specified, it is interpreted depend on *cmsg_level*.
   # *   Socket::SCM_RIGHTS, "SCM_RIGHTS", "RIGHTS", :SCM_RIGHTS, :RIGHTS for
@@ -4139,7 +4145,6 @@ class Socket::AncillaryData
   # *   Socket::IPV6_PKTINFO, "PKTINFO" and :PKTINFO for IPPROTO_IPV6
   # *   etc.
   #
-  #
   # *cmsg_data* should be a string.
   #
   #     p Socket::AncillaryData.new(:INET, :TCP, :NODELAY, "")

data/stdlib/socket/0/tcp_server.rbs

@@ -91,7 +91,6 @@ class TCPServer < TCPSocket
   # ### Parameter
   # *   `backlog` - the maximum length of the queue for pending connections.
   #
-  #
   # ### Example 1
   #     require 'socket'
   #     include Socket::Constants
@@ -128,7 +127,6 @@ class TCPServer < TCPSocket
   # *   Errno::ENOBUFS - insufficient resources are available in the system to
   #     complete the call
   #
-  #
   # ### Windows Exceptions
   # On Windows systems the following system exceptions may be raised if the call
   # to *listen* fails:
@@ -148,7 +146,6 @@ class TCPServer < TCPSocket
   # *   Errno::EOPNOTSUPP - the referenced `socket` is not a type that supports
   #     the *listen* method
   #
-  #
   # ### See
   # *   listen manual pages on unix-based systems
   # *   listen function in Microsoft's Winsock functions reference

data/stdlib/socket/0/tcp_socket.rbs

@@ -27,7 +27,6 @@ class TCPSocket < IPSocket
   #     cannot be released since gethostbyname() is not thread safe.)
   # *   This method uses gethostbyname() function already removed from POSIX.
   #
-  #
   # This method lookups host information by *hostname*.
   #
   #     TCPSocket.gethostbyname("localhost")
@@ -38,9 +37,43 @@ class TCPSocket < IPSocket
   private
 
   # <!--
-  #   rdoc-file=lib/resolv-replace.rb
-  #   - new(host, serv, *rest)
+  #   rdoc-file=ext/socket/tcpsocket.c
+  #   - TCPSocket.new(remote_host, remote_port, local_host=nil, local_port=nil, resolv_timeout: nil, connect_timeout: nil, fast_fallback: true)
   # -->
+  # Opens a TCP connection to `remote_host` on `remote_port`.  If `local_host` and
+  # `local_port` are specified, then those parameters are used on the local end to
+  # establish the connection.
+  #
+  # Starting from Ruby 3.4, this method operates according to the Happy Eyeballs
+  # Version 2 ([RFC 8305](https://datatracker.ietf.org/doc/html/rfc8305))
+  # algorithm by default, except on Windows.
+  #
+  # For details on Happy Eyeballs Version 2, see
+  # [Socket.tcp_fast_fallback=](rdoc-ref:Socket.tcp_fast_fallback=).
+  #
+  # To make it behave the same as in Ruby 3.3 and earlier, explicitly specify the
+  # option fast_fallback:false. Or, setting Socket.tcp_fast_fallback=false will
+  # disable Happy Eyeballs Version 2 not only for this method but for all Socket
+  # globally.
+  #
+  # When using TCPSocket.new on Windows, Happy Eyeballs Version 2 is not provided,
+  # and it behaves the same as in Ruby 3.3 and earlier.
+  #
+  # :resolv_timeout
+  # :   Specifies the timeout in seconds from when the hostname resolution starts.
+  #
+  # :connect_timeout
+  # :   This method sequentially attempts connecting to all candidate destination
+  #     addresses.
+  #     The `connect_timeout` specifies the timeout in seconds from the start of
+  #     the connection attempt to the last candidate.
+  #     By default, all connection attempts continue until the timeout occurs.
+  #     When `fast_fallback:false` is explicitly specified,
+  #     a timeout is set for each connection attempt and any connection attempt
+  #     that exceeds its timeout will be canceled.
+  #
+  # :fast_fallback
+  # :   Enables the Happy Eyeballs Version 2 algorithm (enabled by default).
   #
   def initialize: (String remote_host, Integer remote_port, ?String local_host, ?Integer local_port) -> untyped
 end