rdoc.rbs

# <!-- 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
# requires.  It associates these with optional documentation contained in an
# immediately preceding comment block then renders the result using an output
# formatter.
#
# For a simple introduction to writing or generating documentation using RDoc
# see the README.
#
# ## Roadmap
#
# If you think you found a bug in RDoc see CONTRIBUTING@Bugs
#
# 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@Markup+Formats
#
# If you want to store rdoc configuration in your gem (such as the default
# markup format) see RDoc::Options@Saved+Options
#
# If you want to write documentation for Ruby files see RDoc::Parser::Ruby
#
# If you want to write documentation for extensions written in C see
# RDoc::Parser::C
#
# If you want to generate documentation using `rake` see RDoc::Task.
#
# If you want to drive RDoc programmatically, see RDoc::RDoc.
#
# If you want to use the library to format text blocks into HTML or other
# formats, look at RDoc::Markup.
#
# If you want to make an RDoc plugin such as a generator or directive handler
# see RDoc::RDoc.
#
# If you want to write your own output generator see RDoc::Generator.
#
# If you want an overview of how RDoc works see CONTRIBUTING
#
# ## Credits
#
# RDoc is currently being maintained by Eric Hodel <drbrain@segment7.net>.
#
# Dave Thomas <dave@pragmaticprogrammer.com> is the original author of RDoc.
#
# *   The Ruby parser in rdoc/parse.rb is based heavily on the outstanding work
#     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
  # (say a method). Entities populate these streams by being registered with the
  # lexer. Any class can collect tokens by including TokenStream. From the
  # outside, you use such an object by calling the start_collecting_tokens method,
  # followed by calls to add_token and pop_token.
  #
  module TokenStream
    # <!--
    #   rdoc-file=lib/rdoc/token_stream.rb
    #   - add_token(token)
    # -->
    # Adds one `token` to the collected tokens
    #
    def add_token: (Hash[untyped, untyped] token) -> void

    # <!--
    #   rdoc-file=lib/rdoc/token_stream.rb
    #   - collect_tokens()
    # -->
    # Starts collecting tokens
    #
    def collect_tokens: () -> void

    # <!--
    #   rdoc-file=lib/rdoc/token_stream.rb
    #   - start_collecting_tokens()
    # -->
    #
    alias start_collecting_tokens collect_tokens
  end

  # <!-- rdoc-file=lib/rdoc/class_module.rb -->
  # ClassModule is the base class for objects representing either a class or a
  # module.
  #
  class ClassModule < Context
    # <!--
    #   rdoc-file=lib/rdoc/class_module.rb
    #   - new(name, superclass = nil)
    # -->
    # Creates a new ClassModule with `name` with optional `superclass`
    #
    # This is a constructor for subclasses, and must never be called directly.
    #
    def initialize: (String name, ?String superclass) -> void

    # <!--
    #   rdoc-file=lib/rdoc/class_module.rb
    #   - add_comment(comment, location)
    # -->
    # Adds `comment` to this ClassModule's list of comments at `location`.  This
    # method is preferred over #comment= since it allows ri data to be updated
    # across multiple runs.
    #
    def add_comment: (RDoc::Comment comment, RDoc::Context location) -> void
  end

  # <!-- rdoc-file=lib/rdoc/normal_class.rb -->
  # A normal class, neither singleton nor anonymous
  #
  class NormalClass < ClassModule
    def initialize: (String name, ?String superclass) -> void
  end

  # <!-- rdoc-file=lib/rdoc/single_class.rb -->
  # A singleton class
  #
  class SingleClass < ClassModule
    def initialize: (String name, ?String superclass) -> void
  end

  # <!-- rdoc-file=lib/rdoc/normal_module.rb -->
  # A normal module, like NormalClass
  #
  class NormalModule < ClassModule
  end

  # <!-- rdoc-file=lib/rdoc/method_attr.rb -->
  # Abstract class representing either a method or an attribute.
  #
  class MethodAttr < CodeObject
    include Comparable

    # <!-- rdoc-file=lib/rdoc/method_attr.rb -->
    # The method/attribute we're aliasing
    #
    attr_reader is_alias_for: MethodAttr?

    # <!-- rdoc-file=lib/rdoc/method_attr.rb -->
    # The call_seq or the param_seq with method name, if there is no call_seq.
    #
    attr_reader arglists: String

    # <!-- rdoc-file=lib/rdoc/method_attr.rb -->
    # Name of this method/attribute.
    #
    attr_accessor name: String

    # <!-- rdoc-file=lib/rdoc/method_attr.rb -->
    # public, protected, private
    #
    attr_accessor visibility: untyped

    # <!-- rdoc-file=lib/rdoc/method_attr.rb -->
    # Is this a singleton method/attribute?
    #
    attr_accessor singleton: bool

    # <!-- rdoc-file=lib/rdoc/method_attr.rb -->
    # Source file token stream
    #
    attr_reader text: String

    # <!-- rdoc-file=lib/rdoc/method_attr.rb -->
    # Different ways to call this method
    #
    attr_accessor call_seq: String

    # <!--
    #   rdoc-file=lib/rdoc/method_attr.rb
    #   - new(text, name)
    # -->
    # Creates a new MethodAttr from token stream `text` and method or attribute name
    # `name`.
    #
    # Usually this is called by super from a subclass.
    #
    def initialize: (String text, String name, ?singleton: bool) -> void

    # <!--
    #   rdoc-file=lib/rdoc/method_attr.rb
    #   - pretty_name()
    # -->
    # Method/attribute name with class/instance indicator
    #
    def pretty_name: () -> ::String

    # <!--
    #   rdoc-file=lib/rdoc/method_attr.rb
    #   - type()
    # -->
    # Type of method/attribute (class or instance)
    #
    def type: () -> ("class" | "instance")

    # <!--
    #   rdoc-file=lib/rdoc/method_attr.rb
    #   - path()
    # -->
    # Path to this method for use with HTML generator output.
    #
    def path: () -> ::String

    def to_s: () -> ::String
  end

  # <!-- rdoc-file=lib/rdoc/any_method.rb -->
  # AnyMethod is the base class for objects representing methods
  #
  class AnyMethod < MethodAttr
    include TokenStream

    # <!--
    #   rdoc-file=lib/rdoc/any_method.rb
    #   - call_seq()
    # -->
    # Different ways to call this method
    # ----
    # <!--
    #   rdoc-file=lib/rdoc/any_method.rb
    #   - call_seq=(call_seq)
    # -->
    # Sets the different ways you can call this method.  If an empty `call_seq` is
    # given nil is assumed.
    #
    # See also #param_seq
    #
    attr_accessor call_seq: ::String

    # <!-- rdoc-file=lib/rdoc/any_method.rb -->
    # Parameters for this method
    #
    attr_accessor params: ::String

    attr_accessor line: Integer

    # <!--
    #   rdoc-file=lib/rdoc/any_method.rb
    #   - arglists()
    # -->
    # The call_seq or the param_seq with method name, if there is no call_seq.
    #
    # Use this for displaying a method's argument lists.
    #
    def arglists: () -> String?

    def callseq: () -> String?

    # <!--
    #   rdoc-file=lib/rdoc/any_method.rb
    #   - new(text, name)
    # -->
    # Creates a new AnyMethod with a token stream `text` and `name`
    #
    def initialize: (String? text, String name, ?singleton: bool) -> void
  end

  # <!-- rdoc-file=lib/rdoc/attr.rb -->
  # An attribute created by #attr, #attr_reader, #attr_writer or #attr_accessor
  #
  class Attr < MethodAttr
    # <!-- rdoc-file=lib/rdoc/attr.rb -->
    # Is the attribute readable ('R'), writable ('W') or both ('RW')?
    #
    attr_accessor rw: "RW" | "R" | "W"

    # <!--
    #   rdoc-file=lib/rdoc/attr.rb
    #   - new(text, name, rw, comment, singleton = false)
    # -->
    # Creates a new Attr with body `text`, `name`, read/write status `rw` and
    # `comment`.  `singleton` marks this as a class attribute.
    #
    def initialize: (String? text, String name, String rw, RDoc::Comment? comment, ?singleton: bool) -> void
  end

  # <!-- rdoc-file=lib/rdoc/constant.rb -->
  # A constant
  #
  class Constant < CodeObject
    # <!-- rdoc-file=lib/rdoc/constant.rb -->
    # Sets the module or class this is constant is an alias for.
    #
    attr_writer is_alias_for: String

    # <!-- rdoc-file=lib/rdoc/constant.rb -->
    # The constant's name
    #
    attr_accessor name: String

    # <!-- rdoc-file=lib/rdoc/constant.rb -->
    # The constant's value
    #
    attr_accessor value: String

    # <!-- rdoc-file=lib/rdoc/constant.rb -->
    # The constant's visibility
    #
    attr_accessor visibility: String

    # <!--
    #   rdoc-file=lib/rdoc/constant.rb
    #   - new(name, value, comment)
    # -->
    # Creates a new constant with `name`, `value` and `comment`
    #
    def initialize: (String name, String value, RDoc::Comment? comment) -> void
  end

  # <!-- rdoc-file=lib/rdoc/mixin.rb -->
  # A Mixin adds features from a module into another context.  RDoc::Include and
  # RDoc::Extend are both mixins.
  #
  class Mixin < CodeObject
    # <!-- rdoc-file=lib/rdoc/mixin.rb -->
    # Name of included module
    #
    attr_accessor name: String

    # <!--
    #   rdoc-file=lib/rdoc/mixin.rb
    #   - new(name, comment)
    # -->
    # Creates a new Mixin for `name` with `comment`
    #
    def initialize: (String name, RDoc::Comment? comment) -> void
  end

  # <!-- rdoc-file=lib/rdoc/include.rb -->
  # A Module included in a class with #include
  #
  #     RDoc::Include.new 'Enumerable', 'comment ...'
  #
  class Include < Mixin
  end

  # <!-- rdoc-file=lib/rdoc/extend.rb -->
  # A Module extension to a class with #extend
  #
  #     RDoc::Extend.new 'Enumerable', 'comment ...'
  #
  class Extend < Mixin
  end

  # <!-- rdoc-file=lib/rdoc/alias.rb -->
  # Represent an alias, which is an old_name/new_name pair associated with a
  # particular context
  #
  class Alias < CodeObject
    # <!-- rdoc-file=lib/rdoc/alias.rb -->
    # Aliased method's name
    #
    attr_accessor name: String

    # <!-- rdoc-file=lib/rdoc/alias.rb -->
    # Aliasee method's name
    #
    attr_accessor old_name: String

    attr_reader singleton: bool

    # <!--
    #   rdoc-file=lib/rdoc/alias.rb
    #   - new(text, old_name, new_name, comment, singleton = false)
    # -->
    # Creates a new Alias with a token stream of `text` that aliases `old_name` to
    # `new_name`, has `comment` and is a `singleton` context.
    #
    def initialize: (String? text, String name, String old_name, RDoc::Comment? comment, ?singleton: bool) -> void
  end

  # <!-- rdoc-file=lib/rdoc/stats.rb -->
  # RDoc statistics collector which prints a summary and report of a project's
  # documentation totals.
  #
  class Stats
  end
end