yard-inline-rbs 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: eadf817f51b889044ba2a36a401178e947a87d5ccc723652c6ff383a667babce
+  data.tar.gz: 9d98968fa49153690fdf1391981abd99c09f4742891faa863337ef4a7fc66617
+SHA512:
+  metadata.gz: 72352816a0e4d88c490d9bedc9a8f12be780a0073e5370fc6c5cff24e1b541fb4d50bb2a1fd7638a7adf3a984eb81c5fd78b3b744b04197d7872d30b7a47c80b
+  data.tar.gz: e0dbb396bf8a57e62d04d5ff7bbf34236dd38977bb5cd8ad48e1744f559a2c49106ea8dfd24ae919d75b34e83dacb2cc9e075b41f5350f46fb8b38067620223f

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0
+
+First release.
+
+- Types from `@rbs` tags, `#:` comments and trailing `#:` comments become `@param`, `@return`,
+  `@yield` and `@yieldreturn` tags.
+- The declarations of `.rbs` files become the same tags.
+- A method with overloads gets an `@overload` tag for each signature.
+- A tuple is `Array(Integer, String)`, a record is `Hash{Symbol => Integer}` and an intersection is
+  `A & B`.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yard-inline-rbs contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,174 @@
+# yard-inline-rbs
+
+A YARD plugin that uses [inline RBS] type annotations in the generated documentation, so types are
+written once: Steep checks them, YARD documents them.
+
+Without the plugin, a typed and documented method needs two type annotations that easily drift
+apart:
+
+```ruby
+# @param name [String] who to greet
+# @return [Array<String>]
+# @rbs name: String
+# @rbs return: Array[String]
+def greet(name); end
+```
+
+With the plugin, the RBS annotations are enough:
+
+```ruby
+# Greets someone.
+# @rbs name: String -- who to greet
+# @rbs return: Array[String] -- the greetings
+def greet(name); end
+```
+
+YARD then documents `@param name [String] who to greet` and
+`@return [Array<String>] the greetings`. The RBS types replace any YARD types for the same
+parameter or return value, and the `@rbs` lines are removed from the description. A YARD tag
+keeps its description when the annotation has none; this includes `@yield` and `@yieldreturn`.
+A parameter, the return value or the block that is typed twice, such as by an `@rbs` tag and a
+`#:` line, gets a warning; the first annotation wins, and `@rbs` tags come before `#:` lines.
+
+## Installation
+
+Add the gem to the Gemfile of the project to document:
+
+```ruby
+gem 'yard-inline-rbs', path: '../yard_inline_rbs_plugin'
+```
+
+Enable the plugin in its `.yardopts`:
+
+```
+--plugin inline-rbs
+```
+
+Then run `yard doc` as usual.
+
+## Regular RBS files
+
+The plugin also documents the types in regular `.rbs` files. YARD parses `sig/**/*.rbs` by
+default; when `.yardopts` lists files, add them to the list:
+
+```
+--plugin inline-rbs
+lib/**/*.rb
+sig/**/*.rbs
+```
+
+The methods, attributes and constants of a `.rbs` file get the same tags as inline annotations:
+`@param`, `@return`, `@yield` and `@yieldreturn`, with types in YARD notation (`Array<String>`,
+not `Array[String]`). A method with several signatures gets an `@overload` tag for each.
+Parameters take the name of the Ruby parameter, also when the signature names them differently:
+Steep does not check RBS parameter names. Without a Ruby method, they keep the name in the
+signature, or are called `arg0`, `arg1`, ...
+
+YARD 0.9.45 or later is required, because it parses the `.rbs` files into objects. The
+plugin parses the `.rbs` files before the Ruby files and writes the tags once all files are
+parsed, so the order of the files in `.yardopts` does not matter.
+
+- **Existing tags win.** A `.rbs` declaration only adds types that are missing, so a type in the
+  Ruby docstring or an inline annotation takes precedence over `sig/`. A tag with only a
+  description, such as `@param name The name.`, gets the type of the `.rbs` file. This differs from inline
+  annotations, which replace YARD types. A type that an inline annotation and a `.rbs` file both
+  declare gets a warning, such as `lib/shop.rb:7: two RBS annotations for the return type, one
+  in sig/shop.rbs`; a YARD type such as `@param [String] name` does not.
+- **Comments in `.rbs` files** show up only where the Ruby declaration has no description. A
+  Ruby comment with only annotations, such as a trailing `#: String`, has no description.
+- `def self?.name` is not supported: YARD does not create objects for it.
+
+## Supported annotations
+
+The plugin follows the inline RBS syntax built into the rbs gem, as specified in [inline RBS].
+
+| Annotation | Result |
+|---|---|
+| `# @rbs (Integer, ?String, *Symbol, name: String, **bool) -> void` | `@param` for every parameter, `@return` |
+| `#: (Integer) -> String` above a method | `@param`, `@return` |
+| `# @rbs (String) { (Integer) -> void } -> void` | `@param`, `@yield`, `@yieldreturn`, `@return` |
+| `# @rbs { () -> void } -> void`, without parameter list | `@yield`, `@yieldreturn`, `@return` |
+| `# @rbs (Integer) -> String`, then `#    \| (Float) -> Float` on the next line | An `@overload` tag for each signature, and no `@param` or `@return` on the method itself |
+| A signature that continues on indented comment lines (`#   -> String`) | As on one line |
+| `# @rbs name: String -- description` | `@param` with description |
+| `# @rbs *names: String`, `# @rbs **options: bool`, also unnamed | `@param` for the splat or keyword rest |
+| `# @rbs &block: (String) -> void`, also optional (`? (…) -> …`) | `@yield`, `@yieldreturn` |
+| `# @rbs return: String -- description` | `@return` with description |
+| `def name #: String` and `def name = value #: String` | `@return` |
+| `attr_reader :name #: String`, also `attr_writer` and `attr_accessor` | `@return` on the reader, `@param` on the writer |
+| `ITEMS = [] #: Array[String]` | `@return` on the constant |
+
+A description after `--` may continue on the next lines, or start on the line below a trailing
+`--`. Annotations that only instruct the type checker are removed without a trace: `@rbs skip`,
+`@rbs ...`, `@rbs module-self:`, `#: class-alias`, `#: module-alias` and generic superclass
+comments such as `class StringArray < Array #[String]`.
+
+RBS types are converted to the YARD notation:
+
+| RBS | YARD |
+|---|---|
+| `Integer?` | `Integer, nil` |
+| `String \| Symbol` | `String, Symbol` |
+| `bool` | `Boolean` |
+| `Array[String]` | `Array<String>` |
+| `Hash[Symbol, Integer]` | `Hash{Symbol => Integer}` |
+| `Comparable & Enumerable[Integer]` | `Comparable & Enumerable<Integer>` |
+| `Shop::path` (alias), `_Each[Integer]` (interface) | `Shop::path`, `_Each<Integer>` |
+| `[Integer, String]` (tuple) | `Array(Integer, String)` |
+| `{ id: Integer, name: String }` (record) | `Hash{Symbol => Integer, String}` |
+| `^(Integer) -> String` (proc) | `Proc` |
+
+A record loses the names of its keys: YARD has no notation for them. A tuple or record without
+elements (`[]`, `{ }`) is `Array` or `Hash`.
+
+When an annotation cannot be parsed or is not supported, the plugin logs a warning with the file
+and line, and still generates the documentation:
+
+```
+[warn]: [yard-inline-rbs] lib/foo.rb:12: could not parse RBS type 'BadType!!!'
+```
+
+## Limitations
+
+Some Ruby constructs, such as `Struct.new` and `Data.define`, cannot be typed with inline RBS
+yet. See [docs/limitations.md](docs/limitations.md) for what is not supported and why.
+
+Not yet implemented in the plugin itself:
+
+- A `#:` signature cannot have overloads; Steep rejects them too. Use `@rbs` for overloads.
+- A hand-written `@overload` tag wins: the overloads of an annotation or of a `.rbs` file are not
+  added next to it.
+- RBS types without a YARD equivalent are shown as written, e.g. `singleton(Foo)`, `boolish` and
+  `instance`.
+- YARD has no notation for nested lists. A tuple groups an optional or a union element:
+  `[Integer?, String]` is `Array((Integer, nil), String)`. A record joins the types of its values
+  into one list, so `{ a: Integer?, b: String }` is `Hash{Symbol => Integer, nil, String}`.
+- Instance variable annotations (`@rbs @name: String`) are reported as unsupported, because YARD
+  does not document instance variables.
+
+## Development
+
+```shell
+bundle install
+bundle exec rake
+```
+
+`rake` runs all checks: RuboCop, Steep, the dependency audit, the specs with coverage minimums,
+and YARD documentation and RSpec coverage. [AGENTS.md](AGENTS.md#running-checks) explains each
+check and how to run one on its own.
+
+The plugin hooks into `YARD::DocstringParser.after_parse` (see `lib/yard_inline_rbs/plugin.rb`):
+
+- `TagInjector` collects the annotations of a docstring and replaces them with YARD tags.
+- `RbsCommentParser` parses the annotations with the rbs gem.
+- `RbsFunctionTypes` converts the parameters, return type and block of a method type.
+- `RbsDescription` splits an annotation into its type and `--` description.
+- `RbsTypeFormatter` converts RBS types into YARD type strings.
+- `RbsFileTags` writes the types of `.rbs` files onto the YARD objects after all files are parsed,
+  using `MemberTags` and `ResultApplier`.
+
+[inline RBS]: https://github.com/ruby/rbs/blob/master/docs/inline.md
+
+## License
+
+Released under the [MIT License](LICENSE).

data/lib/yard-inline-rbs.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'yard'
+require 'rbs'
+require_relative 'yard_inline_rbs/rbs_type_formatter'
+require_relative 'yard_inline_rbs/rbs_description'
+require_relative 'yard_inline_rbs/rbs_function_types'
+require_relative 'yard_inline_rbs/parse_result'
+require_relative 'yard_inline_rbs/type_parser'
+require_relative 'yard_inline_rbs/inline_annotations'
+require_relative 'yard_inline_rbs/rbs_comment_parser'
+require_relative 'yard_inline_rbs/parameter_names'
+require_relative 'yard_inline_rbs/annotation_warnings'
+require_relative 'yard_inline_rbs/declaration_source'
+require_relative 'yard_inline_rbs/inline_types'
+require_relative 'yard_inline_rbs/result_applier'
+require_relative 'yard_inline_rbs/object_tags'
+require_relative 'yard_inline_rbs/tag_injector'
+require_relative 'yard_inline_rbs/overload_text'
+require_relative 'yard_inline_rbs/member_tags'
+require_relative 'yard_inline_rbs/rbs_file_tags'
+require_relative 'yard_inline_rbs/rbs_handler_patches'
+require_relative 'yard_inline_rbs/plugin'
+
+# YARD plugin that turns inline RBS annotations into `@param`, `@return`, `@yield` and
+# `@yieldreturn` tags, so the documented types are the ones Steep checks.
+module YardInlineRbs
+  # @rbs (String message) -> void
+  def self.warn(message)
+    YARD::Logger.instance.warn("[yard-inline-rbs] #{message}")
+  end
+end

data/lib/yard_inline_rbs/annotation_warnings.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module YardInlineRbs
+  # Warns about annotations the plugin cannot use, once per location. YARD parses some docstrings
+  # more than once: an attribute with its default docstring, both methods of an attr_accessor, and
+  # a trailing comment that is also the docstring.
+  class AnnotationWarnings
+    # @rbs @location: String
+
+    # The warnings that were logged, so each is logged once.
+    LOGGED = Set.new #: Set[String]
+
+    # Forgets the warnings that were logged. Called before each file is parsed: the location of a
+    # warning includes the file, so a file parsed again warns again.
+    # @rbs () -> nil
+    def self.clear_logged
+      LOGGED.clear
+      nil
+    end
+
+    # The location is that of the declaration, such as `lib/shop.rb:7`.
+    # @rbs (String location) -> void
+    def initialize(location)
+      @location = location
+    end
+
+    # @rbs (ParseResult result) -> void
+    def report(result)
+      warn_each(result.parse_errors, 'could not parse RBS type')
+      warn_each(result.unsupported_annotations, 'unsupported RBS annotation')
+      warn_duplicates(result.duplicate_annotations)
+    end
+
+    # Types that both an inline annotation and the `.rbs` file at `rbs_path` declare.
+    # @rbs (Array[String] duplicate_annotations, String rbs_path) -> void
+    def report_rbs_file_duplicates(duplicate_annotations, rbs_path)
+      warn_duplicates(duplicate_annotations, ", one in #{rbs_path}")
+    end
+
+    private
+
+    # @rbs (Array[String] duplicate_annotations, ?String suffix) -> void
+    def warn_duplicates(duplicate_annotations, suffix = '')
+      duplicate_annotations.each {|annotated| log("two RBS annotations for #{annotated}#{suffix}")}
+    end
+
+    # @rbs (Array[String] annotations, String problem) -> void
+    def warn_each(annotations, problem)
+      annotations.each {|annotation| log("#{problem} '#{annotation}'")}
+    end
+
+    # @rbs (String problem) -> void
+    def log(problem)
+      message = "#{@location}: #{problem}"
+      YardInlineRbs.warn(message) if LOGGED.add?(message)
+    end
+  end
+end

data/lib/yard_inline_rbs/declaration_source.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module YardInlineRbs
+  # Where the declaration of a code object is, and its source line.
+  class DeclarationSource
+    # @rbs @object: YARD::CodeObjects::Base
+    # @rbs @handler: YARD::Handlers::Base?
+    # @rbs @first_line: String?
+
+    # Forgets the files that were read. Called when the class loads, before each parse list,
+    # because a file can change between two parses in a long-running process, and after it, to
+    # free the memory.
+    # @rbs () -> void
+    def self.clear_cache
+      @lines = {} #: Hash[String, Array[String]]
+    end
+    clear_cache
+
+    # @rbs (String file) -> Array[String]
+    def self.lines_of(file)
+      @lines[file] ||= File.readlines(file)
+    end
+
+    # The handler is the one that parses the docstring, if any.
+    # @rbs (YARD::CodeObjects::Base object, ?YARD::Handlers::Base? handler) -> void
+    def initialize(object, handler = nil)
+      @object = object
+      @handler = handler
+    end
+
+    # The statement of the handler, else the first declaration outside a `.rbs` file. YARD's own
+    # `object.file` is the first declaration with a comment: the `.rbs` file when it has a
+    # comment, because the plugin parses the `.rbs` files first.
+    # @rbs () -> [String, Integer?]?
+    def location
+      handler = @handler
+      return [handler.parser.file, handler.statement.line] if handler
+
+      files = @object.files
+      files.find {|file, _line| !file.end_with?('.rbs')} || files.first
+    end
+
+    # The first line, for its trailing `#:` comment, or nil when that comment is the docstring:
+    # without a comment above it, its annotation is already among the description lines.
+    # @rbs () -> String?
+    def trailing_comment_line
+      first_line if !comment_on_declaration_line?
+    end
+
+    # YARD takes the trailing comment of a statement as the docstring of the next statement when
+    # that has no comment above it, e.g. after a statement with a comment above it. The
+    # annotations in such a comment belong to the earlier statement.
+    # @rbs () -> bool
+    def comment_of_earlier_statement?
+      handler = @handler
+      return false if handler.nil?
+
+      comments_range = handler.statement.comments_range
+      line = handler.statement.line
+      return false if comments_range.nil? || line.nil? || comments_range.first >= line
+
+      comment_line = file_line(handler.parser.file, comments_range.first)
+      !comment_line.nil? && !comment_line.match?(/\A\s*#/)
+    end
+
+    # `lib/shop.rb:7`, or an empty string without a location.
+    # @rbs () -> String
+    def location_text
+      location.to_a.compact.join(':')
+    end
+
+    # The first line. YARD's source of attr_* methods is synthetic, so the original file line
+    # is read.
+    # @rbs () -> String
+    def first_line
+      @first_line ||= original_line || @object.source.to_s.lines.first.to_s
+    end
+
+    # The `[String]` of `class StringArray < Array #[String]`.
+    # @rbs () -> String?
+    def superclass_type_application
+      first_line[/\A\s*class\b[^#]*<[^#]*#(\[.+\])\s*\z/, 1]
+    end
+
+    private
+
+    # @rbs () -> bool
+    def comment_on_declaration_line?
+      handler = @handler
+      return false if handler.nil?
+
+      statement = handler.statement
+      comments_range = statement.comments_range
+      !comments_range.nil? && comments_range.first == statement.line
+    end
+
+    # nil without a file, e.g. with YARD.parse_string, when the file cannot be read, or when it
+    # has no such line.
+    # @rbs () -> String?
+    def original_line
+      file, line = location
+      file_line(file, line) if file && line
+    end
+
+    # nil when the file cannot be read, e.g. `(stdin)` with YARD.parse_string, or has no such line.
+    # @rbs (String file, Integer line) -> String?
+    def file_line(file, line)
+      return if file == '(stdin)'
+
+      self.class.lines_of(file)[line - 1]
+    rescue SystemCallError
+      nil
+    end
+  end
+end

data/lib/yard_inline_rbs/inline_annotations.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module YardInlineRbs
+  # Reads the inline `#:` annotations. Values already in the result win, because `@rbs`
+  # tags take precedence; the result records the duplicates.
+  class InlineAnnotations
+    # @rbs @types: TypeParser
+    # @rbs @result: ParseResult
+
+    # @rbs (TypeParser types, ParseResult result) -> void
+    def initialize(types, result)
+      @types = types
+      @result = result
+    end
+
+    # A description line starting with `:`, with the indented lines below it. Unlike `@rbs`, a
+    # `#:` signature cannot have overloads: Steep rejects it.
+    # @rbs (String line) -> void
+    def process_line(line)
+      annotation = line.strip.delete_prefix(':')
+      if overloads?(annotation)
+        @result.parse_errors << annotation.lines.map(&:strip).join(' ')
+      else
+        annotate(annotation) {|type_str| @result.add_signature(@types.method_signature(type_str))}
+      end
+    end
+
+    # The declaration line may end in `#: Type`.
+    # @rbs (String source_line) -> void
+    def process_trailing(source_line)
+      match = source_line.match(/(?:\A|\s)#:\s*(.+)$/)
+      return unless match
+
+      annotate(match[1]) do |type_str|
+        signature = @types.method_signature(type_str)
+        @result.add_return_type(signature[:return_type]) if signature
+      end
+    end
+
+    private
+
+    # @rbs (String annotation) -> bool
+    def overloads?(annotation)
+      RbsDescription.overloads(annotation).size > 1
+    end
+
+    # `class-alias` and `module-alias` declare a type name, not a type.
+    # @rbs (String type_str) -> bool
+    def alias_annotation?(type_str)
+      type_str.match?(/\A(class|module)-alias\b/)
+    end
+
+    # Yields method types; any other type is the return type.
+    # @rbs (String annotation) { (String) -> void } -> void
+    def annotate(annotation)
+      type_str, = RbsDescription.split(annotation)
+      return if alias_annotation?(type_str)
+      return yield(type_str) if @types.method_type?(type_str)
+
+      @result.add_return_type(@types.type(type_str))
+    end
+  end
+end

data/lib/yard_inline_rbs/inline_types.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module YardInlineRbs
+  # What the inline annotations of an object typed, such as `the return type`, and where they
+  # are. RbsFileTags warns when a `.rbs` file types the same. It is stored on the object and
+  # replaced with each docstring, so it follows the docstring that YARD keeps, also in its cache.
+  class InlineTypes
+    # Stores nothing on an object that had no inline types and still has none.
+    # @rbs (YARD::CodeObjects::Base object, Array[String] typed, String location) -> void
+    def self.record(object, typed, location)
+      return if typed.empty? && !any?(object)
+
+      object[:rbs_inline_typed] = typed
+      object[:rbs_inline_location] = location
+    end
+
+    # @rbs (YARD::CodeObjects::Base object, String annotated) -> bool
+    def self.typed?(object, annotated)
+      typed(object).include?(annotated)
+    end
+
+    # @rbs (YARD::CodeObjects::Base object) -> bool
+    def self.any?(object)
+      typed(object).any?
+    end
+
+    # @rbs (YARD::CodeObjects::Base object) -> String?
+    # @return [String, nil] The location of the inline annotations, such as `lib/shop.rb:7`.
+    def self.location(object)
+      object[:rbs_inline_location]
+    end
+
+    # @rbs (YARD::CodeObjects::Base object) -> Array[String]
+    def self.typed(object)
+      Array(object[:rbs_inline_typed])
+    end
+    private_class_method :typed
+  end
+end

data/lib/yard_inline_rbs/member_tags.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module YardInlineRbs
+  # Tags a registered YARD object with the types of an RBS declaration. Tags that are already
+  # there win, so a Ruby docstring or an inline annotation beats a `.rbs` declaration.
+  class MemberTags
+    # @rbs @object: YARD::CodeObjects::Base
+    # @rbs @tags: ObjectTags
+    # @rbs @types: TypeParser
+
+    # What an inline annotation typed as well, such as `the return type`.
+    attr_reader :duplicate_annotations #: Array[String]
+
+    # @rbs (YARD::CodeObjects::Base object) -> void
+    def initialize(object)
+      @object = object
+      @tags = ObjectTags.new(object)
+      @types = TypeParser.new([])
+      @duplicate_annotations = []
+    end
+
+    # A method with several signatures gets an @overload tag for each.
+    # @rbs (Array[RBS::MethodType] method_types) -> void
+    def method_types(method_types)
+      signatures = method_types.map {|method_type| @types.signature_of(method_type)}
+      apply(ParseResult.new.tap {|result| result.add_signatures(signatures)})
+    end
+
+    # The type of an attribute or constant.
+    # @rbs (RBS::Types::t type) -> void
+    def type(type)
+      apply(ParseResult.new.tap {|result| result.add_return_type(RbsTypeFormatter.format(type))})
+    end
+
+    private
+
+    # @rbs (ParseResult result) -> void
+    def apply(result)
+      ResultApplier.new(@tags, keep_existing: true).apply(result)
+      @duplicate_annotations.concat(result.duplicate_annotations)
+    end
+  end
+end

data/lib/yard_inline_rbs/object_tags.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module YardInlineRbs
+  # Gives a registered code object the `tags` and `tags=` of a DocstringParser. The docstring
+  # of an object returns a copy of its tags, so changes must go through its own mutators.
+  class ObjectTags
+    attr_reader :object #: YARD::CodeObjects::Base
+
+    # @rbs (YARD::CodeObjects::Base object) -> void
+    def initialize(object)
+      @object = object
+    end
+
+    # @rbs () -> Array[YARD::Tags::Tag]
+    def tags
+      @object.tags
+    end
+
+    # @rbs (Array[YARD::Tags::Tag] new_tags) -> void
+    def tags=(new_tags)
+      docstring = @object.docstring
+      docstring.delete_tag_if {true}
+      new_tags.each {|tag| docstring.add_tag(tag)}
+    end
+  end
+end

data/lib/yard_inline_rbs/overload_text.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module YardInlineRbs
+  # The text of an @overload tag for one signature of a method, in the format YARD parses:
+  # the call on the first line, then the nested tags.
+  class OverloadText
+    # @rbs @name: Symbol
+    # @rbs @signature: signature
+
+    # The name of a keyword rest that has none.
+    KEYWORD_REST_NAME = 'options' #: String
+
+    # @rbs (Symbol name, signature signature) -> void
+    def initialize(name, signature)
+      @name = name
+      @signature = signature
+    end
+
+    # @rbs () -> String
+    def to_s
+      lines = ["#{@name}(#{call_arguments.join(', ')})"]
+      lines += params.map {|name, type| "  @param #{name} [#{type}]"}
+      lines += block_lines
+      lines << "  @return [#{@signature[:return_type]}]"
+      lines.join("\n")
+    end
+
+    private
+
+    # @rbs () -> Array[String]
+    def call_arguments
+      positional_names + keywords.map do |name, annotation|
+        annotation.rest ? "**#{name}" : "#{name}:"
+      end
+    end
+
+    # @rbs () -> Array[String]
+    def positional_names
+      @signature[:positional_types].each_with_index.map do |param, index|
+        param.name || ParameterNames.placeholder(index)
+      end
+    end
+
+    # @rbs () -> Array[[String, String?]]
+    def params
+      positional = @signature[:positional_types].map(&:type)
+      positional_names.zip(positional) + keywords.transform_values(&:type).to_a
+    end
+
+    # @rbs () -> Hash[String, NamedParamAnnotation]
+    def keywords
+      @signature[:named_types].transform_keys do |name|
+        name == ParameterNames::KEYWORD_REST_KEY ? KEYWORD_REST_NAME : name
+      end
+    end
+
+    # @rbs () -> Array[String]
+    def block_lines
+      block = @signature[:block_annotation]
+      return [] if block.nil?
+
+      ["  @yield [#{block.yield_types.join(', ')}]", "  @yieldreturn [#{block.return_type}]"]
+    end
+  end
+end