rbs 2.8.4 → 3.8.1

data/stdlib/{yaml → psych}/0/dbm.rbs

@@ -1,5 +1,5 @@
 %a{annotate:rdoc:skip}
-module YAML
+module Psych
   # <!-- rdoc-file=lib/yaml/dbm.rb -->
   # YAML + DBM = YDBM
   #
@@ -169,7 +169,7 @@ module YAML
     # object. Takes any object which implements the each_pair method, including Hash
     # and DBM objects.
     #
-    def replace: (Hash[untyped, untyped] | DBM hsh) -> YAML::DBM
+    def replace: (Hash[untyped, untyped] | DBM hsh) -> Psych::DBM
 
     # <!--
     #   rdoc-file=lib/yaml/dbm.rb
@@ -214,7 +214,7 @@ module YAML
     #
     # Returns `self`.
     #
-    def update: (Hash[untyped, untyped]) -> YAML::DBM
+    def update: (Hash[untyped, untyped]) -> Psych::DBM
 
     # <!--
     #   rdoc-file=lib/yaml/dbm.rb

data/stdlib/psych/0/manifest.yaml

@@ -0,0 +1,3 @@
+dependencies:
+  - name: dbm
+  - name: pstore

data/stdlib/psych/0/psych.rbs

@@ -0,0 +1,402 @@
+# <!-- rdoc-file=ext/psych/lib/psych.rb -->
+# # Overview
+#
+# Psych is a YAML parser and emitter. Psych leverages libyaml [Home page:
+# https://pyyaml.org/wiki/LibYAML] or [git repo:
+# https://github.com/yaml/libyaml] for its YAML parsing and emitting
+# capabilities. In addition to wrapping libyaml, Psych also knows how to
+# serialize and de-serialize most Ruby objects to and from the YAML format.
+#
+# # I NEED TO PARSE OR EMIT YAML RIGHT NOW!
+#
+#     # Parse some YAML
+#     Psych.load("--- foo") # => "foo"
+#
+#     # Emit some YAML
+#     Psych.dump("foo")     # => "--- foo\n...\n"
+#     { :a => 'b'}.to_yaml  # => "---\n:a: b\n"
+#
+# Got more time on your hands?  Keep on reading!
+#
+# ## YAML Parsing
+#
+# Psych provides a range of interfaces for parsing a YAML document ranging from
+# low level to high level, depending on your parsing needs.  At the lowest
+# level, is an event based parser.  Mid level is access to the raw YAML AST, and
+# at the highest level is the ability to unmarshal YAML to Ruby objects.
+#
+# ## YAML Emitting
+#
+# Psych provides a range of interfaces ranging from low to high level for
+# producing YAML documents.  Very similar to the YAML parsing interfaces, Psych
+# provides at the lowest level, an event based system, mid-level is building a
+# YAML AST, and the highest level is converting a Ruby object straight to a YAML
+# document.
+#
+# ## High-level API
+#
+# ### Parsing
+#
+# The high level YAML parser provided by Psych simply takes YAML as input and
+# returns a Ruby data structure.  For information on using the high level parser
+# see Psych.load
+#
+# #### Reading from a string
+#
+#     Psych.safe_load("--- a")             # => 'a'
+#     Psych.safe_load("---\n - a\n - b")   # => ['a', 'b']
+#     # From a trusted string:
+#     Psych.load("--- !ruby/range\nbegin: 0\nend: 42\nexcl: false\n") # => 0..42
+#
+# #### Reading from a file
+#
+#     Psych.safe_load_file("data.yml", permitted_classes: [Date])
+#     Psych.load_file("trusted_database.yml")
+#
+# #### Exception handling
+#
+#     begin
+#       # The second argument changes only the exception contents
+#       Psych.parse("--- `", "file.txt")
+#     rescue Psych::SyntaxError => ex
+#       ex.file    # => 'file.txt'
+#       ex.message # => "(file.txt): found character that cannot start any token"
+#     end
+#
+# ### Emitting
+#
+# The high level emitter has the easiest interface.  Psych simply takes a Ruby
+# data structure and converts it to a YAML document.  See Psych.dump for more
+# information on dumping a Ruby data structure.
+#
+# #### Writing to a string
+#
+#     # Dump an array, get back a YAML string
+#     Psych.dump(['a', 'b'])  # => "---\n- a\n- b\n"
+#
+#     # Dump an array to an IO object
+#     Psych.dump(['a', 'b'], StringIO.new)  # => #<StringIO:0x000001009d0890>
+#
+#     # Dump an array with indentation set
+#     Psych.dump(['a', ['b']], :indentation => 3) # => "---\n- a\n-  - b\n"
+#
+#     # Dump an array to an IO with indentation set
+#     Psych.dump(['a', ['b']], StringIO.new, :indentation => 3)
+#
+# #### Writing to a file
+#
+# Currently there is no direct API for dumping Ruby structure to file:
+#
+#     File.open('database.yml', 'w') do |file|
+#       file.write(Psych.dump(['a', 'b']))
+#     end
+#
+# ## Mid-level API
+#
+# ### Parsing
+#
+# Psych provides access to an AST produced from parsing a YAML document.  This
+# tree is built using the Psych::Parser and Psych::TreeBuilder.  The AST can be
+# examined and manipulated freely.  Please see Psych::parse_stream,
+# Psych::Nodes, and Psych::Nodes::Node for more information on dealing with YAML
+# syntax trees.
+#
+# #### Reading from a string
+#
+#     # Returns Psych::Nodes::Stream
+#     Psych.parse_stream("---\n - a\n - b")
+#
+#     # Returns Psych::Nodes::Document
+#     Psych.parse("---\n - a\n - b")
+#
+# #### Reading from a file
+#
+#     # Returns Psych::Nodes::Stream
+#     Psych.parse_stream(File.read('database.yml'))
+#
+#     # Returns Psych::Nodes::Document
+#     Psych.parse_file('database.yml')
+#
+# #### Exception handling
+#
+#     begin
+#       # The second argument changes only the exception contents
+#       Psych.parse("--- `", "file.txt")
+#     rescue Psych::SyntaxError => ex
+#       ex.file    # => 'file.txt'
+#       ex.message # => "(file.txt): found character that cannot start any token"
+#     end
+#
+# ### Emitting
+#
+# At the mid level is building an AST.  This AST is exactly the same as the AST
+# used when parsing a YAML document.  Users can build an AST by hand and the AST
+# knows how to emit itself as a YAML document.  See Psych::Nodes,
+# Psych::Nodes::Node, and Psych::TreeBuilder for more information on building a
+# YAML AST.
+#
+# #### Writing to a string
+#
+#     # We need Psych::Nodes::Stream (not Psych::Nodes::Document)
+#     stream = Psych.parse_stream("---\n - a\n - b")
+#
+#     stream.to_yaml # => "---\n- a\n- b\n"
+#
+# #### Writing to a file
+#
+#     # We need Psych::Nodes::Stream (not Psych::Nodes::Document)
+#     stream = Psych.parse_stream(File.read('database.yml'))
+#
+#     File.open('database.yml', 'w') do |file|
+#       file.write(stream.to_yaml)
+#     end
+#
+# ## Low-level API
+#
+# ### Parsing
+#
+# The lowest level parser should be used when the YAML input is already known,
+# and the developer does not want to pay the price of building an AST or
+# automatic detection and conversion to Ruby objects.  See Psych::Parser for
+# more information on using the event based parser.
+#
+# #### Reading to Psych::Nodes::Stream structure
+#
+#     parser = Psych::Parser.new(TreeBuilder.new) # => #<Psych::Parser>
+#     parser = Psych.parser                       # it's an alias for the above
+#
+#     parser.parse("---\n - a\n - b")             # => #<Psych::Parser>
+#     parser.handler                              # => #<Psych::TreeBuilder>
+#     parser.handler.root                         # => #<Psych::Nodes::Stream>
+#
+# #### Receiving an events stream
+#
+#     recorder = Psych::Handlers::Recorder.new
+#     parser = Psych::Parser.new(recorder)
+#
+#     parser.parse("---\n - a\n - b")
+#     recorder.events # => [list of [event, args] lists]
+#                     # event is one of: Psych::Handler::EVENTS
+#                     # args are the arguments passed to the event
+#
+# ### Emitting
+#
+# The lowest level emitter is an event based system.  Events are sent to a
+# Psych::Emitter object.  That object knows how to convert the events to a YAML
+# document.  This interface should be used when document format is known in
+# advance or speed is a concern.  See Psych::Emitter for more information.
+#
+# #### Writing to a Ruby structure
+#
+#     Psych.parser.parse("--- a")       # => #<Psych::Parser>
+#
+#     parser.handler.first              # => #<Psych::Nodes::Stream>
+#     parser.handler.first.to_ruby      # => ["a"]
+#
+#     parser.handler.root.first         # => #<Psych::Nodes::Document>
+#     parser.handler.root.first.to_ruby # => "a"
+#
+#     # You can instantiate an Emitter manually
+#     Psych::Visitors::ToRuby.new.accept(parser.handler.root.first)
+#     # => "a"
+#
+module Psych
+  # <!--
+  #   rdoc-file=ext/psych/lib/psych.rb
+  #   - Psych.dump(o)               -> string of yaml
+  #   - Psych.dump(o, options)      -> string of yaml
+  #   - Psych.dump(o, io)           -> io object passed in
+  #   - Psych.dump(o, io, options)  -> io object passed in
+  # -->
+  # Dump Ruby object `o` to a YAML string.  Optional `options` may be passed in to
+  # control the output format.  If an IO object is passed in, the YAML will be
+  # dumped to that IO object.
+  #
+  # Currently supported options are:
+  #
+  # `:indentation`
+  # :   Number of space characters used to indent. Acceptable value should be in
+  #     `0..9` range, otherwise option is ignored.
+  #
+  #     Default: `2`.
+  #
+  # `:line_width`
+  # :   Max character to wrap line at. For unlimited line width use `-1`.
+  #
+  #     Default: `0` (meaning "wrap at 81").
+  #
+  # `:canonical`
+  # :   Write "canonical" YAML form (very verbose, yet strictly formal).
+  #
+  #     Default: `false`.
+  #
+  # `:header`
+  # :   Write `%YAML [version]` at the beginning of document.
+  #
+  #     Default: `false`.
+  #
+  #
+  # `:stringify_names`
+  # :   Dump symbol keys in Hash objects as string.
+  #
+  #     Default: `false`.
+  #
+  #
+  # Example:
+  #
+  #     # Dump an array, get back a YAML string
+  #     Psych.dump(['a', 'b'])  # => "---\n- a\n- b\n"
+  #
+  #     # Dump an array to an IO object
+  #     Psych.dump(['a', 'b'], StringIO.new)  # => #<StringIO:0x000001009d0890>
+  #
+  #     # Dump an array with indentation set
+  #     Psych.dump(['a', ['b']], indentation: 3) # => "---\n- a\n-  - b\n"
+  #
+  #     # Dump an array to an IO with indentation set
+  #     Psych.dump(['a', ['b']], StringIO.new, indentation: 3)
+  #
+  #     # Dump hash with symbol keys as string
+  #     Psych.dump({a: "b"}, stringify_names: true) # => "---\na: b\n"
+  #
+  %a{annotate:rdoc:copy:Psych.dump}
+  def self.dump: (untyped o, ?indentation: Integer, ?line_width: Integer, ?canonical: bool, ?header: bool) -> String
+               | [IO] (untyped o, IO, ?indentation: Integer, ?line_width: Integer, ?canonical: bool, ?header: bool) -> IO
+
+  # <!--
+  #   rdoc-file=ext/psych/lib/psych.rb
+  #   - load(yaml, permitted_classes: [Symbol], permitted_symbols: [], aliases: false, filename: nil, fallback: nil, symbolize_names: false, freeze: false, strict_integer: false)
+  # -->
+  # Load `yaml` in to a Ruby data structure.  If multiple documents are provided,
+  # the object contained in the first document will be returned. `filename` will
+  # be used in the exception message if any exception is raised while parsing.  If
+  # `yaml` is empty, it returns the specified `fallback` return value, which
+  # defaults to `nil`.
+  #
+  # Raises a Psych::SyntaxError when a YAML syntax error is detected.
+  #
+  # Example:
+  #
+  #     Psych.load("--- a")             # => 'a'
+  #     Psych.load("---\n - a\n - b")   # => ['a', 'b']
+  #
+  #     begin
+  #       Psych.load("--- `", filename: "file.txt")
+  #     rescue Psych::SyntaxError => ex
+  #       ex.file    # => 'file.txt'
+  #       ex.message # => "(file.txt): found character that cannot start any token"
+  #     end
+  #
+  # When the optional `symbolize_names` keyword argument is set to a true value,
+  # returns symbols for keys in Hash objects (default: strings).
+  #
+  #     Psych.load("---\n foo: bar")                         # => {"foo"=>"bar"}
+  #     Psych.load("---\n foo: bar", symbolize_names: true)  # => {:foo=>"bar"}
+  #
+  # Raises a TypeError when `yaml` parameter is NilClass.  This method is similar
+  # to `safe_load` except that `Symbol` objects are allowed by default.
+  #
+  %a{annotate:rdoc:copy:Psych.load}
+  def self.load: (String yaml, ?filename: String | _ToStr | _ToS?, ?fallback: untyped, ?symbolize_names: bool, ?freeze: bool) -> untyped
+
+  # <!--
+  #   rdoc-file=ext/psych/lib/psych.rb
+  #   - load_file(filename, **kwargs)
+  # -->
+  # Loads the document contained in `filename`.  Returns the yaml contained in
+  # `filename` as a Ruby object, or if the file is empty, it returns the specified
+  # `fallback` return value, which defaults to `nil`. See load for options.
+  #
+  %a{annotate:rdoc:copy:Psych.load_file}
+  def self.load_file: (string | _ToPath, ?fallback: untyped, ?symbolize_names: bool, ?freeze: bool) -> untyped
+
+  # <!--
+  #   rdoc-file=ext/psych/lib/psych.rb
+  #   - safe_load(yaml, permitted_classes: [], permitted_symbols: [], aliases: false, filename: nil, fallback: nil, symbolize_names: false, freeze: false, strict_integer: false)
+  # -->
+  # Safely load the yaml string in `yaml`.  By default, only the following classes
+  # are allowed to be deserialized:
+  #
+  # *   TrueClass
+  # *   FalseClass
+  # *   NilClass
+  # *   Integer
+  # *   Float
+  # *   String
+  # *   Array
+  # *   Hash
+  #
+  # Recursive data structures are not allowed by default.  Arbitrary classes can
+  # be allowed by adding those classes to the `permitted_classes` keyword
+  # argument.  They are additive.  For example, to allow Date deserialization:
+  #
+  #     Psych.safe_load(yaml, permitted_classes: [Date])
+  #
+  # Now the Date class can be loaded in addition to the classes listed above.
+  #
+  # Aliases can be explicitly allowed by changing the `aliases` keyword argument.
+  # For example:
+  #
+  #     x = []
+  #     x << x
+  #     yaml = Psych.dump x
+  #     Psych.safe_load yaml               # => raises an exception
+  #     Psych.safe_load yaml, aliases: true # => loads the aliases
+  #
+  # A Psych::DisallowedClass exception will be raised if the yaml contains a class
+  # that isn't in the `permitted_classes` list.
+  #
+  # A Psych::AliasesNotEnabled exception will be raised if the yaml contains
+  # aliases but the `aliases` keyword argument is set to false.
+  #
+  # `filename` will be used in the exception message if any exception is raised
+  # while parsing.
+  #
+  # When the optional `symbolize_names` keyword argument is set to a true value,
+  # returns symbols for keys in Hash objects (default: strings).
+  #
+  #     Psych.safe_load("---\n foo: bar")                         # => {"foo"=>"bar"}
+  #     Psych.safe_load("---\n foo: bar", symbolize_names: true)  # => {:foo=>"bar"}
+  #
+  %a{annotate:rdoc:copy:Psych.safe_load}
+  def self.safe_load: (String yaml, ?permitted_classes: Array[Class], ?permitted_symbols: Array[Symbol], ?aliases: bool, ?filename: String | _ToStr | _ToS?, ?fallback: untyped, ?symbolize_names: bool, ?freeze: bool) -> untyped
+
+  # <!--
+  #   rdoc-file=ext/psych/lib/psych.rb
+  #   - unsafe_load(yaml, filename: nil, fallback: false, symbolize_names: false, freeze: false, strict_integer: false)
+  # -->
+  # Load `yaml` in to a Ruby data structure.  If multiple documents are provided,
+  # the object contained in the first document will be returned. `filename` will
+  # be used in the exception message if any exception is raised while parsing.  If
+  # `yaml` is empty, it returns the specified `fallback` return value, which
+  # defaults to `false`.
+  #
+  # Raises a Psych::SyntaxError when a YAML syntax error is detected.
+  #
+  # Example:
+  #
+  #     Psych.unsafe_load("--- a")             # => 'a'
+  #     Psych.unsafe_load("---\n - a\n - b")   # => ['a', 'b']
+  #
+  #     begin
+  #       Psych.unsafe_load("--- `", filename: "file.txt")
+  #     rescue Psych::SyntaxError => ex
+  #       ex.file    # => 'file.txt'
+  #       ex.message # => "(file.txt): found character that cannot start any token"
+  #     end
+  #
+  # When the optional `symbolize_names` keyword argument is set to a true value,
+  # returns symbols for keys in Hash objects (default: strings).
+  #
+  #     Psych.unsafe_load("---\n foo: bar")                         # => {"foo"=>"bar"}
+  #     Psych.unsafe_load("---\n foo: bar", symbolize_names: true)  # => {:foo=>"bar"}
+  #
+  # Raises a TypeError when `yaml` parameter is NilClass
+  #
+  # NOTE: This method *should not* be used to parse untrusted documents, such as
+  # YAML documents that are supplied via user input.  Instead, please use the load
+  # method or the safe_load method.
+  #
+  %a{annotate:rdoc:copy:Psych.unsafe_load}
+  def self.unsafe_load: (String yaml, ?filename: String | _ToStr | _ToS?, ?fallback: untyped, ?symbolize_names: bool, ?freeze: bool, ?strict_integer: bool) -> untyped
+end

data/stdlib/{yaml → psych}/0/store.rbs

@@ -30,7 +30,7 @@
 #     greeting:
 #       hello: world
 #
-class YAML::Store < ::PStore
+class Psych::Store < ::PStore
   # <!--
   #   rdoc-file=lib/yaml/store.rb
   #   - initialize( file_name, yaml_opts = {} )
@@ -45,7 +45,7 @@ class YAML::Store < ::PStore
   # Options passed in through `yaml_opts` will be used when converting the store
   # to YAML via Hash#to_yaml().
   #
-  def initialize: (*untyped o) -> YAML::Store
+  def initialize: (*untyped o) -> void
 
   def dump: (untyped table) -> String
 

data/stdlib/pty/0/pty.rbs

@@ -68,25 +68,36 @@ module PTY
   #
   # `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
-  #   - PTY.spawn(command_line)  { |r, w, pid| ... }
-  #   - PTY.spawn(command_line)  => [r, w, pid]
-  #   - PTY.spawn(command, arguments, ...)  { |r, w, pid| ... }
-  #   - PTY.spawn(command, arguments, ...)  => [r, w, pid]
-  # -->
+  # <!-- 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.
   #
@@ -99,11 +110,23 @@ module PTY
   # `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
 
   # <!--
@@ -134,6 +157,7 @@ module PTY
   #
   # `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 `slave_file.path`
@@ -152,10 +176,10 @@ module PTY
 
   # <!--
   #   rdoc-file=ext/pty/pty.c
-  #   - PTY.spawn(command_line)  { |r, w, pid| ... }
-  #   - PTY.spawn(command_line)  => [r, w, pid]
-  #   - PTY.spawn(command, arguments, ...)  { |r, w, pid| ... }
-  #   - PTY.spawn(command, arguments, ...)  => [r, w, pid]
+  #   - 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.
@@ -163,6 +187,22 @@ module PTY
   # 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.
   #
@@ -175,11 +215,23 @@ module PTY
   # `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/rdoc/0/code_object.rbs

@@ -0,0 +1,51 @@
+%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::Mixin
+  #     *   RDoc::Require
+  #     *   RDoc::Include
+  #
+  class CodeObject
+    # <!-- rdoc-file=lib/rdoc/code_object.rb -->
+    # Our comment
+    #
+    attr_reader comment: Markup::Document | 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=: (Markup::Document | Comment | String | nil) -> (Markup::Document | Comment | String)
+  end
+end

data/stdlib/rdoc/0/comment.rbs

@@ -0,0 +1,59 @@
+%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
+
+    # <!--
+    #   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