rbs 4.1.0.pre.2-java

data/stdlib/psych/0/store.rbs

@@ -0,0 +1,57 @@
+# <!-- rdoc-file=lib/yaml/store.rb -->
+# YAML::Store provides the same functionality as PStore, except it uses YAML to
+# dump objects instead of Marshal.
+#
+# ## Example
+#
+#     require 'yaml/store'
+#
+#     Person = Struct.new :first_name, :last_name
+#
+#     people = [Person.new("Bob", "Smith"), Person.new("Mary", "Johnson")]
+#
+#     store = YAML::Store.new "test.store"
+#
+#     store.transaction do
+#       store["people"] = people
+#       store["greeting"] = { "hello" => "world" }
+#     end
+#
+# After running the above code, the contents of "test.store" will be:
+#
+#     ---
+#     people:
+#     - !ruby/struct:Person
+#       first_name: Bob
+#       last_name: Smith
+#     - !ruby/struct:Person
+#       first_name: Mary
+#       last_name: Johnson
+#     greeting:
+#       hello: world
+#
+class Psych::Store < ::PStore[string, untyped]
+  # <!--
+  #   rdoc-file=lib/yaml/store.rb
+  #   - initialize( file_name, yaml_opts = {} )
+  #   - initialize( file_name, thread_safe = false, yaml_opts = {} )
+  # -->
+  # Creates a new YAML::Store object, which will store data in `file_name`. If the
+  # file does not already exist, it will be created.
+  #
+  # YAML::Store objects are always reentrant. But if *thread_safe* is set to true,
+  # then it will become thread-safe at the cost of a minor performance hit.
+  #
+  # Options passed in through `yaml_opts` will be used when converting the store
+  # to YAML via Hash#to_yaml().
+  #
+  def dump: (untyped table) -> String
+
+  def empty_marshal_checksum: () -> String
+
+  def empty_marshal_data: () -> String
+
+  def load: (String) -> untyped
+
+  def marshal_dump_supports_canonical_option?: () -> bool
+end

data/stdlib/pty/0/pty.rbs

@@ -0,0 +1,240 @@
+# <!-- rdoc-file=ext/pty/pty.c -->
+# Creates and manages pseudo terminals (PTYs).  See also
+# https://en.wikipedia.org/wiki/Pseudo_terminal
+#
+# PTY allows you to allocate new terminals using ::open or ::spawn a new
+# terminal with a specific command.
+#
+# ## Example
+#
+# In this example we will change the buffering type in the `factor` command,
+# assuming that factor uses stdio for stdout buffering.
+#
+# If IO.pipe is used instead of PTY.open, this code deadlocks because factor's
+# stdout is fully buffered.
+#
+#     # start by requiring the standard library PTY
+#     require 'pty'
+#
+#     master, slave = PTY.open
+#     read, write = IO.pipe
+#     pid = spawn("factor", :in=>read, :out=>slave)
+#     read.close     # we dont need the read
+#     slave.close    # or the slave
+#
+#     # pipe "42" to the factor command
+#     write.puts "42"
+#     # output the response from factor
+#     p master.gets #=> "42: 2 3 7\n"
+#
+#     # pipe "144" to factor and print out the response
+#     write.puts "144"
+#     p master.gets #=> "144: 2 2 2 2 3 3\n"
+#     write.close # close the pipe
+#
+#     # The result of read operation when pty slave is closed is platform
+#     # dependent.
+#     ret = begin
+#             master.gets     # FreeBSD returns nil.
+#           rescue Errno::EIO # GNU/Linux raises EIO.
+#             nil
+#           end
+#     p ret #=> nil
+#
+# ## License
+#
+# (c) Copyright 1998 by Akinori Ito.
+#
+# This software may be redistributed freely for this purpose, in full or in
+# part, provided that this entire copyright notice is included on any copies of
+# this software and applications and derivations thereof.
+#
+# This software is provided on an "as is" basis, without warranty of any kind,
+# either expressed or implied, as to any matter including, but not limited to
+# warranty of fitness of purpose, or merchantability, or results obtained from
+# use of this software.
+#
+module PTY
+  # <!--
+  #   rdoc-file=ext/pty/pty.c
+  #   - PTY.check(pid, raise = false) => Process::Status or nil
+  #   - PTY.check(pid, true)          => nil or raises PTY::ChildExited
+  # -->
+  # Checks the status of the child process specified by `pid`. Returns `nil` if
+  # the process is still alive.
+  #
+  # If the process is not alive, and `raise` was true, a PTY::ChildExited
+  # exception will be raised. Otherwise it will return a Process::Status instance.
+  #
+  # `pid`
+  # :   The process id of the process to check
+  #
+  # `raise`
+  # :   If `true` and the process identified by `pid` is no longer alive a
+  #     PTY::ChildExited is raised.
+  #
+  def self.check: (Integer pid, ?boolish raise) -> Process::Status?
+
+  # <!-- rdoc-file=ext/pty/pty.c -->
+  # Spawns the specified command on a newly allocated pty. You can also use the
+  # alias ::getpty.
+  #
+  # The command's controlling tty is set to the slave device of the pty and its
+  # standard input/output/error is redirected to the slave device.
+  #
+  # `env` is an optional hash that provides additional environment variables to
+  # the spawned pty.
+  #
+  #     # sets FOO to "bar"
+  #     PTY.spawn({"FOO"=>"bar"}, "printenv", "FOO") do |r, w, pid|
+  #       p r.read #=> "bar\r\n"
+  #     ensure
+  #       r.close; w.close; Process.wait(pid)
+  #     end
+  #     # unsets FOO
+  #     PTY.spawn({"FOO"=>nil}, "printenv", "FOO") do |r, w, pid|
+  #       p r.read #=> ""
+  #     ensure
+  #       r.close; w.close; Process.wait(pid)
+  #     end
+  #
+  # `command` and `command_line` are the full commands to run, given a String. Any
+  # additional `arguments` will be passed to the command.
+  #
+  # ### Return values
+  #
+  # In the non-block form this returns an array of size three, <code>[r, w,
+  # pid]</code>.
+  #
+  # In the block form these same values will be yielded to the block:
+  #
+  # `r`
+  # :   A readable IO that contains the command's standard output and standard
+  #     error
+  #
+  # `w`
+  # :   A writable IO that is the command's standard input
+  #
+  # `pid`
+  # :   The process identifier for the command.
+  #
+  #
+  # ### Clean up
+  #
+  # This method does not clean up like closing IOs or waiting for child process,
+  # except that the process is detached in the block form to prevent it from
+  # becoming a zombie (see Process.detach).  Any other cleanup is the
+  # responsibility of the caller.  If waiting for `pid`, be sure to close both `r`
+  # and `w` before doing so; doing it in the reverse order may cause deadlock on
+  # some OSes.
+  #
+  alias self.getpty self.spawn
+
+  # <!--
+  #   rdoc-file=ext/pty/pty.c
+  #   - PTY.open => [master_io, slave_file]
+  #   - PTY.open {|(master_io, slave_file)| ... } => block value
+  # -->
+  # Allocates a pty (pseudo-terminal).
+  #
+  # In the block form, yields an array of two elements (<code>master_io,
+  # slave_file</code>) and the value of the block is returned from `open`.
+  #
+  # The IO and File are both closed after the block completes if they haven't been
+  # already closed.
+  #
+  #     PTY.open {|master, slave|
+  #       p master      #=> #<IO:masterpty:/dev/pts/1>
+  #       p slave      #=> #<File:/dev/pts/1>
+  #       p slave.path #=> "/dev/pts/1"
+  #     }
+  #
+  # In the non-block form, returns a two element array, <code>[master_io,
+  # slave_file]</code>.
+  #
+  #     master, slave = PTY.open
+  #     # do something with master for IO, or the slave file
+  #
+  # The arguments in both forms are:
+  #
+  # `master_io`
+  # :   the master of the pty, as an IO.
+  #
+  # `slave_file`
+  # :   the slave of the pty, as a File.  The path to the terminal device is
+  #     available via <code>slave_file.path</code>
+  #
+  #
+  # IO#raw! is usable to disable newline conversions:
+  #
+  #     require 'io/console'
+  #     PTY.open {|m, s|
+  #       s.raw!
+  #       # ...
+  #     }
+  #
+  def self.open: () -> [ IO, File ]
+               | [A] () { ([ IO, File ]) -> A } -> A
+
+  # <!--
+  #   rdoc-file=ext/pty/pty.c
+  #   - PTY.spawn([env,] command_line)  { |r, w, pid| ... }
+  #   - PTY.spawn([env,] command_line)  => [r, w, pid]
+  #   - PTY.spawn([env,] command, arguments, ...)  { |r, w, pid| ... }
+  #   - PTY.spawn([env,] command, arguments, ...)  => [r, w, pid]
+  # -->
+  # Spawns the specified command on a newly allocated pty. You can also use the
+  # alias ::getpty.
+  #
+  # The command's controlling tty is set to the slave device of the pty and its
+  # standard input/output/error is redirected to the slave device.
+  #
+  # `env` is an optional hash that provides additional environment variables to
+  # the spawned pty.
+  #
+  #     # sets FOO to "bar"
+  #     PTY.spawn({"FOO"=>"bar"}, "printenv", "FOO") do |r, w, pid|
+  #       p r.read #=> "bar\r\n"
+  #     ensure
+  #       r.close; w.close; Process.wait(pid)
+  #     end
+  #     # unsets FOO
+  #     PTY.spawn({"FOO"=>nil}, "printenv", "FOO") do |r, w, pid|
+  #       p r.read #=> ""
+  #     ensure
+  #       r.close; w.close; Process.wait(pid)
+  #     end
+  #
+  # `command` and `command_line` are the full commands to run, given a String. Any
+  # additional `arguments` will be passed to the command.
+  #
+  # ### Return values
+  #
+  # In the non-block form this returns an array of size three, <code>[r, w,
+  # pid]</code>.
+  #
+  # In the block form these same values will be yielded to the block:
+  #
+  # `r`
+  # :   A readable IO that contains the command's standard output and standard
+  #     error
+  #
+  # `w`
+  # :   A writable IO that is the command's standard input
+  #
+  # `pid`
+  # :   The process identifier for the command.
+  #
+  #
+  # ### Clean up
+  #
+  # This method does not clean up like closing IOs or waiting for child process,
+  # except that the process is detached in the block form to prevent it from
+  # becoming a zombie (see Process.detach).  Any other cleanup is the
+  # responsibility of the caller.  If waiting for `pid`, be sure to close both `r`
+  # and `w` before doing so; doing it in the reverse order may cause deadlock on
+  # some OSes.
+  #
+  def self.spawn: (*String command) -> [ IO, IO, Integer ]
+                | (*String command) { ([ IO, IO, Integer ]) -> void } -> void
+end

data/stdlib/random-formatter/0/random-formatter.rbs

@@ -0,0 +1,277 @@
+module RBS
+  module Unnamed
+    module Random_Formatter
+      # <!--
+      #   rdoc-file=lib/random/formatter.rb
+      #   - base64(n=nil)
+      # -->
+      # Generate a random base64 string.
+      #
+      # The argument *n* specifies the length, in bytes, of the random number to be
+      # generated. The length of the result string is about 4/3 of *n*.
+      #
+      # If *n* is not specified or is nil, 16 is assumed. It may be larger in the
+      # future.
+      #
+      # The result may contain A-Z, a-z, 0-9, "+", "/" and "=".
+      #
+      #     require 'random/formatter'
+      #
+      #     Random.base64 #=> "/2BuBuLf3+WfSKyQbRcc/A=="
+      #     # or
+      #     prng = Random.new
+      #     prng.base64 #=> "6BbW0pxO0YENxn38HMUbcQ=="
+      #
+      # See RFC 3548 for the definition of base64.
+      #
+      %a{annotate:rdoc:copy:Random::Formatter#base64}
+      def base64: (?Integer? n) -> String
+
+      # <!--
+      #   rdoc-file=lib/random/formatter.rb
+      #   - hex(n=nil)
+      # -->
+      # Generate a random hexadecimal string.
+      #
+      # The argument *n* specifies the length, in bytes, of the random number to be
+      # generated. The length of the resulting hexadecimal string is twice of *n*.
+      #
+      # If *n* is not specified or is nil, 16 is assumed. It may be larger in the
+      # future.
+      #
+      # The result may contain 0-9 and a-f.
+      #
+      #     require 'random/formatter'
+      #
+      #     Random.hex #=> "eb693ec8252cd630102fd0d0fb7c3485"
+      #     # or
+      #     prng = Random.new
+      #     prng.hex #=> "91dc3bfb4de5b11d029d376634589b61"
+      #
+      %a{annotate:rdoc:copy:Random::Formatter#hex}
+      def hex: (?Integer? n) -> String
+
+      # <!--
+      #   rdoc-file=lib/random/formatter.rb
+      #   - random_bytes(n=nil)
+      # -->
+      # Generate a random binary string.
+      #
+      # The argument *n* specifies the length of the result string.
+      #
+      # If *n* is not specified or is nil, 16 is assumed. It may be larger in future.
+      #
+      # The result may contain any byte: "x00" - "xff".
+      #
+      #     require 'random/formatter'
+      #
+      #     Random.random_bytes #=> "\xD8\\\xE0\xF4\r\xB2\xFC*WM\xFF\x83\x18\xF45\xB6"
+      #     # or
+      #     prng = Random.new
+      #     prng.random_bytes #=> "m\xDC\xFC/\a\x00Uf\xB2\xB2P\xBD\xFF6S\x97"
+      #
+      %a{annotate:rdoc:copy:Random::Formatter#random_bytes}
+      def random_bytes: (?Integer? n) -> String
+
+      # <!--
+      #   rdoc-file=lib/random/formatter.rb
+      #   - urlsafe_base64(n=nil, padding=false)
+      # -->
+      # Generate a random URL-safe base64 string.
+      #
+      # The argument *n* specifies the length, in bytes, of the random number to be
+      # generated. The length of the result string is about 4/3 of *n*.
+      #
+      # If *n* is not specified or is nil, 16 is assumed. It may be larger in the
+      # future.
+      #
+      # The boolean argument *padding* specifies the padding. If it is false or nil,
+      # padding is not generated. Otherwise padding is generated. By default, padding
+      # is not generated because "=" may be used as a URL delimiter.
+      #
+      # The result may contain A-Z, a-z, 0-9, "-" and "_". "=" is also used if
+      # *padding* is true.
+      #
+      #     require 'random/formatter'
+      #
+      #     Random.urlsafe_base64 #=> "b4GOKm4pOYU_-BOXcrUGDg"
+      #     # or
+      #     prng = Random.new
+      #     prng.urlsafe_base64 #=> "UZLdOkzop70Ddx-IJR0ABg"
+      #
+      #     prng.urlsafe_base64(nil, true) #=> "i0XQ-7gglIsHGV2_BNPrdQ=="
+      #     prng.urlsafe_base64(nil, true) #=> "-M8rLhr7JEpJlqFGUMmOxg=="
+      #
+      # See RFC 3548 for the definition of URL-safe base64.
+      #
+      %a{annotate:rdoc:copy:Random::Formatter#urlsafe_base64}
+      def urlsafe_base64: (?Integer? n, ?boolish padding) -> String
+
+      # <!--
+      #   rdoc-file=lib/random/formatter.rb
+      #   - uuid()
+      # -->
+      # Generate a random v4 UUID (Universally Unique IDentifier).
+      #
+      #     require 'random/formatter'
+      #
+      #     Random.uuid #=> "2d931510-d99f-494a-8c67-87feb05e1594"
+      #     Random.uuid #=> "bad85eb9-0713-4da7-8d36-07a8e4b00eab"
+      #     # or
+      #     prng = Random.new
+      #     prng.uuid #=> "62936e70-1815-439b-bf89-8492855a7e6b"
+      #
+      # The version 4 UUID is purely random (except the version). It doesn't contain
+      # meaningful information such as MAC addresses, timestamps, etc.
+      #
+      # The result contains 122 random bits (15.25 random bytes).
+      #
+      # See [RFC9562](https://www.rfc-editor.org/rfc/rfc9562) for details of UUIDv4.
+      #
+      %a{annotate:rdoc:copy:Random::Formatter#uuid}
+      def uuid: () -> String
+
+      # <!--
+      #   rdoc-file=lib/random/formatter.rb
+      #   - uuid_v4()
+      # -->
+      #
+      %a{annotate:rdoc:copy:Random::Formatter#uuid_v4}
+      alias uuid_v4 uuid
+
+      # <!--
+      #   rdoc-file=lib/random/formatter.rb
+      #   - uuid_v7(extra_timestamp_bits: 0)
+      # -->
+      # Generate a random v7 UUID (Universally Unique IDentifier).
+      #
+      #     require 'random/formatter'
+      #
+      #     Random.uuid_v7 # => "0188d4c3-1311-7f96-85c7-242a7aa58f1e"
+      #     Random.uuid_v7 # => "0188d4c3-16fe-744f-86af-38fa04c62bb5"
+      #     Random.uuid_v7 # => "0188d4c3-1af8-764f-b049-c204ce0afa23"
+      #     Random.uuid_v7 # => "0188d4c3-1e74-7085-b14f-ef6415dc6f31"
+      #     #                    |<--sorted-->| |<----- random ---->|
+      #
+      #     # or
+      #     prng = Random.new
+      #     prng.uuid_v7 # => "0188ca51-5e72-7950-a11d-def7ff977c98"
+      #
+      # The version 7 UUID starts with the least significant 48 bits of a 64 bit Unix
+      # timestamp (milliseconds since the epoch) and fills the remaining bits with
+      # random data, excluding the version and variant bits.
+      #
+      # This allows version 7 UUIDs to be sorted by creation time.  Time ordered UUIDs
+      # can be used for better database index locality of newly inserted records,
+      # which may have a significant performance benefit compared to random data
+      # inserts.
+      #
+      # The result contains 74 random bits (9.25 random bytes).
+      #
+      # Note that this method cannot be made reproducible because its output includes
+      # not only random bits but also timestamp.
+      #
+      # See [RFC9562](https://www.rfc-editor.org/rfc/rfc9562) for details of UUIDv7.
+      #
+      # #### Monotonicity
+      #
+      # UUIDv7 has millisecond precision by default, so multiple UUIDs created within
+      # the same millisecond are not issued in monotonically increasing order.  To
+      # create UUIDs that are time-ordered with sub-millisecond precision, up to 12
+      # bits of additional timestamp may added with `extra_timestamp_bits`.  The extra
+      # timestamp precision comes at the expense of random bits.  Setting
+      # <code>extra_timestamp_bits: 12</code> provides ~244ns of precision, but only
+      # 62 random bits (7.75 random bytes).
+      #
+      #     prng = Random.new
+      #     Array.new(4) { prng.uuid_v7(extra_timestamp_bits: 12) }
+      #     # =>
+      #     ["0188d4c7-13da-74f9-8b53-22a786ffdd5a",
+      #      "0188d4c7-13da-753b-83a5-7fb9b2afaeea",
+      #      "0188d4c7-13da-754a-88ea-ac0baeedd8db",
+      #      "0188d4c7-13da-7557-83e1-7cad9cda0d8d"]
+      #     # |<--- sorted --->| |<-- random --->|
+      #
+      #     Array.new(4) { prng.uuid_v7(extra_timestamp_bits: 8) }
+      #     # =>
+      #     ["0188d4c7-3333-7a95-850a-de6edb858f7e",
+      #      "0188d4c7-3333-7ae8-842e-bc3a8b7d0cf9",  # <- out of order
+      #      "0188d4c7-3333-7ae2-995a-9f135dc44ead",  # <- out of order
+      #      "0188d4c7-3333-7af9-87c3-8f612edac82e"]
+      #     # |<--- sorted -->||<---- random --->|
+      #
+      # Any rollbacks of the system clock will break monotonicity.  UUIDv7 is based on
+      # UTC, which excludes leap seconds and can rollback the clock.  To avoid this,
+      # the system clock can synchronize with an NTP server configured to use a "leap
+      # smear" approach.  NTP or PTP will also be needed to synchronize across
+      # distributed nodes.
+      #
+      # Counters and other mechanisms for stronger guarantees of monotonicity are not
+      # implemented.  Applications with stricter requirements should follow [Section
+      # 6.2](https://www.rfc-editor.org/rfc/rfc9562.html#name-monotonicity-and-counter
+      # s) of the specification.
+      #
+      %a{annotate:rdoc:copy:Random::Formatter#uuid_v7}
+      def uuid_v7: (?extra_timestamp_bits: Integer) -> String
+
+      # <!--
+      #   rdoc-file=lib/random/formatter.rb
+      #   - alphanumeric(n = nil, chars: ALPHANUMERIC)
+      # -->
+      # Generate a random alphanumeric string.
+      #
+      # The argument *n* specifies the length, in characters, of the alphanumeric
+      # string to be generated. The argument *chars* specifies the character list
+      # which the result is consist of.
+      #
+      # If *n* is not specified or is nil, 16 is assumed. It may be larger in the
+      # future.
+      #
+      # The result may contain A-Z, a-z and 0-9, unless *chars* is specified.
+      #
+      #     require 'random/formatter'
+      #
+      #     Random.alphanumeric     #=> "2BuBuLf3WfSKyQbR"
+      #     # or
+      #     prng = Random.new
+      #     prng.alphanumeric(10) #=> "i6K93NdqiH"
+      #
+      #     Random.alphanumeric(4, chars: [*"0".."9"]) #=> "2952"
+      #     # or
+      #     prng = Random.new
+      #     prng.alphanumeric(10, chars: [*"!".."/"]) #=> ",.,++%/''."
+      #
+      %a{annotate:rdoc:copy:Random::Formatter#alphanumeric}
+      def alphanumeric: (?Numeric?, ?chars: Array[String]) -> String
+
+      # <!--
+      #   rdoc-file=lib/random/formatter.rb
+      #   - gen_random(n)
+      # -->
+      # Internal interface to Random; Generate random data *n* bytes.
+      #
+      %a{annotate:rdoc:copy:Random::Formatter#gen_random}
+      private def gen_random: (Integer n) -> String
+
+      # <!--
+      #   rdoc-file=lib/random/formatter.rb
+      #   - choose(source, n)
+      # -->
+      # Generate a string that randomly draws from a source array of characters.
+      #
+      # The argument *source* specifies the array of characters from which to generate
+      # the string. The argument *n* specifies the length, in characters, of the
+      # string to be generated.
+      #
+      # The result may contain whatever characters are in the source array.
+      #
+      #     require 'random/formatter'
+      #
+      #     prng.choose([*'l'..'r'], 16) #=> "lmrqpoonmmlqlron"
+      #     prng.choose([*'0'..'9'], 5)  #=> "27309"
+      #
+      %a{annotate:rdoc:copy:Random::Formatter#choose}
+      private def choose: (Array[String] source, Integer n) -> String
+    end
+  end
+end

data/stdlib/rdoc/0/code_object.rbs

@@ -0,0 +1,52 @@
+%a{annotate:rdoc:skip}
+module RDoc
+  # <!-- rdoc-file=lib/rdoc/code_object.rb -->
+  # Base class for the RDoc code tree.
+  #
+  # We contain the common stuff for contexts (which are containers) and other
+  # elements (methods, attributes and so on)
+  #
+  # Here's the tree of the CodeObject subclasses:
+  #
+  # *   RDoc::Context
+  #     *   RDoc::TopLevel
+  #     *   RDoc::ClassModule
+  #         *   RDoc::AnonClass (never used so far)
+  #         *   RDoc::NormalClass
+  #         *   RDoc::NormalModule
+  #         *   RDoc::SingleClass
+  # *   RDoc::MethodAttr
+  #     *   RDoc::Attr
+  #     *   RDoc::AnyMethod
+  #         *   RDoc::GhostMethod
+  #         *   RDoc::MetaMethod
+  # *   RDoc::Alias
+  # *   RDoc::Constant
+  # *   RDoc::Require
+  # *   RDoc::Mixin
+  #     *   RDoc::Include
+  #     *   RDoc::Extend
+  #
+  class CodeObject
+    # <!-- rdoc-file=lib/rdoc/code_object.rb -->
+    # Our comment
+    #
+    attr_reader comment: Comment | String
+
+    # <!--
+    #   rdoc-file=lib/rdoc/code_object.rb
+    #   - new()
+    # -->
+    # Creates a new CodeObject that will document itself and its children
+    #
+    def initialize: () -> void
+
+    # <!--
+    #   rdoc-file=lib/rdoc/code_object.rb
+    #   - comment=(comment)
+    # -->
+    # Replaces our comment with `comment`, unless it is empty.
+    #
+    def comment=: (Comment | String | nil) -> (Comment | String | nil)
+  end
+end

data/stdlib/rdoc/0/comment.rbs

@@ -0,0 +1,61 @@
+%a{annotate:rdoc:skip}
+module RDoc
+  # <!-- rdoc-file=lib/rdoc/comment.rb -->
+  # A comment holds the text comment for a RDoc::CodeObject and provides a unified
+  # way of cleaning it up and parsing it into an RDoc::Markup::Document.
+  #
+  # Each comment may have a different markup format set by #format=.  By default
+  # 'rdoc' is used.  The :markup: directive tells RDoc which format to use.
+  #
+  # See RDoc::MarkupReference@Directive+for+Specifying+RDoc+Source+Format.
+  #
+  class Comment
+    # <!-- rdoc-file=lib/rdoc/comment.rb -->
+    # The format of this comment.  Defaults to RDoc::Markup
+    #
+    attr_reader format: String
+
+    # <!-- rdoc-file=lib/rdoc/comment.rb -->
+    # The RDoc::TopLevel this comment was found in
+    #
+    attr_accessor location: String
+
+    alias file location
+
+    # <!--
+    #   rdoc-file=lib/rdoc/comment.rb
+    #   - new(text = nil, location = nil, language = nil)
+    # -->
+    # Creates a new comment with `text` that is found in the RDoc::TopLevel
+    # `location`.
+    #
+    def initialize: (?String? text, ?RDoc::Context? location, ?String? language) -> void
+
+    # <!--
+    #   rdoc-file=lib/rdoc/comment.rb
+    #   - format=(format)
+    # -->
+    # Sets the format of this comment and resets any parsed document
+    #
+    def format=: (String format) -> void
+
+    def normalized?: () -> bool
+
+    # <!--
+    #   rdoc-file=lib/rdoc/comment.rb
+    #   - normalize()
+    # -->
+    # Normalizes the text.  See RDoc::Text#normalize_comment for details
+    #
+    def normalize: () -> self
+
+    # <!--
+    #   rdoc-file=lib/rdoc/comment.rb
+    #   - parse()
+    # -->
+    # Parses the comment into an RDoc::Markup::Document.  The parsed document is
+    # cached until the text is changed.
+    #
+    def parse: () -> Markup::Document
+  end
+end