%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
