yard-inline-rbs 0.1.0

data/lib/yard_inline_rbs/rbs_type_formatter.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module YardInlineRbs
+  # Converts RBS types into YARD type strings. RBS `bool` becomes YARD's `Boolean`.
+  class RbsTypeFormatter
+    BASE_TYPE_STRINGS = { #: Hash[Class, String]
+      RBS::Types::Bases::Nil => 'nil',
+      RBS::Types::Bases::Void => 'void',
+      RBS::Types::Bases::Bool => 'Boolean',
+      RBS::Types::Bases::Any => 'untyped',
+      RBS::Types::Bases::Top => 'top',
+      RBS::Types::Bases::Bottom => 'bot',
+      RBS::Types::Bases::Self => 'self'
+    }.freeze
+
+    # @rbs (RBS::Types::t rbs_type) -> String
+    def self.format(rbs_type)
+      BASE_TYPE_STRINGS[rbs_type.class] || format_structured(rbs_type)
+    end
+
+    # A comma-separated YARD type list.
+    # @rbs (RBS::Types::t rbs_type) -> String
+    def self.format_structured(rbs_type)
+      case rbs_type
+      when RBS::Types::Optional then "#{format(rbs_type.type)}, nil"
+      when RBS::Types::Union then format_list(rbs_type.types)
+      when RBS::Types::Intersection then format_list(rbs_type.types, ' & ')
+      else format_collection(rbs_type)
+      end
+    end
+    private_class_method :format_structured
+
+    # @rbs (RBS::Types::t rbs_type) -> String
+    def self.format_collection(rbs_type)
+      case rbs_type
+      when RBS::Types::Proc then 'Proc'
+      when RBS::Types::Tuple then format_tuple(rbs_type)
+      when RBS::Types::Record then format_record(rbs_type)
+      else format_named(rbs_type)
+      end
+    end
+    private_class_method :format_collection
+
+    # @rbs (Array[RBS::Types::t] types, ?String separator) -> String
+    def self.format_list(types, separator = ', ')
+      types.map {|type| format(type)}.join(separator)
+    end
+    private_class_method :format_list
+
+    # `Array(Integer, String)`, YARD's notation for an array of fixed length, or `Array` for `[]`.
+    # @rbs (RBS::Types::Tuple rbs_type) -> String
+    def self.format_tuple(rbs_type)
+      return 'Array' if rbs_type.types.empty?
+
+      "Array(#{rbs_type.types.map {|type| format_element(type)}.join(', ')})"
+    end
+    private_class_method :format_tuple
+
+    # An optional or a union is a list of types itself, so it is grouped in a tuple:
+    # `Array((Integer, nil), String)`.
+    # @rbs (RBS::Types::t type) -> String
+    def self.format_element(type)
+      case type
+      when RBS::Types::Optional, RBS::Types::Union then "(#{format(type)})"
+      else format(type)
+      end
+    end
+    private_class_method :format_element
+
+    # `Hash{Symbol => String, Integer}` for `{ name: String, age: Integer }`: the names of the keys
+    # are lost, YARD has no notation for them. `Hash` for `{}`.
+    # @rbs (RBS::Types::Record rbs_type) -> String
+    def self.format_record(rbs_type)
+      fields = rbs_type.all_fields
+      return 'Hash' if fields.empty?
+
+      keys = fields.keys.map(&:class).uniq.join(', ')
+      values = fields.values.map {|type, _required| format(type)}.uniq.join(', ')
+      "Hash{#{keys} => #{values}}"
+    end
+    private_class_method :format_record
+
+    # Literals and type variables keep their RBS spelling, such as `:ok` and `T`.
+    # @rbs (RBS::Types::t rbs_type) -> String
+    def self.format_named(rbs_type)
+      case rbs_type
+      when RBS::Types::ClassInstance, RBS::Types::Alias, RBS::Types::Interface
+        format_class_instance(rbs_type)
+      else rbs_type.to_s
+      end
+    end
+    private_class_method :format_named
+
+    # A class, alias or interface, with its namespace and type arguments: `Shop::path`,
+    # `_Each<Integer>`.
+    # @rbs (RBS::Types::ClassInstance | RBS::Types::Alias | RBS::Types::Interface rbs_type)
+    #   -> String
+    def self.format_class_instance(rbs_type)
+      name = rbs_type.name.to_s.delete_prefix('::')
+      return name if rbs_type.args.empty?
+      return format_hash_instance(rbs_type) if name == 'Hash' && rbs_type.args.length == 2
+
+      "#{name}<#{format_list(rbs_type.args)}>"
+    end
+    private_class_method :format_class_instance
+
+    # @rbs (RBS::Types::ClassInstance | RBS::Types::Alias | RBS::Types::Interface rbs_type)
+    #   -> String
+    def self.format_hash_instance(rbs_type)
+      "Hash{#{format(rbs_type.args[0])} => #{format(rbs_type.args[1])}}"
+    end
+    private_class_method :format_hash_instance
+  end
+end

data/lib/yard_inline_rbs/result_applier.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module YardInlineRbs
+  # Injects the typed tags of a ParseResult into a tag target: a YARD DocstringParser or an
+  # ObjectTags. RBS types replace existing ones, unless `keep_existing` is set. A parameter that
+  # a named and a positional annotation both type keeps the first, the named one, and is recorded
+  # in the result as a duplicate. With `keep_existing`, a kept tag that an inline annotation
+  # typed is a duplicate too.
+  class ResultApplier
+    # @rbs @target: YARD::DocstringParser | ObjectTags
+    # @rbs @object: YARD::CodeObjects::Base
+    # @rbs @keep_existing: bool
+    # @rbs @parameter_names: ParameterNames
+    # @rbs @tags: Array[YARD::Tags::Tag]
+    # @rbs @result: ParseResult
+
+    # What the last #apply typed, such as `parameter 'count'` and `the return type`.
+    attr_reader :typed #: Array[String]
+
+    # @rbs (YARD::DocstringParser | ObjectTags target, ?keep_existing: bool) -> void
+    def initialize(target, keep_existing: false)
+      @target = target
+      # YARD types the object of a parser as optional, but TagInjector skips a parser without one.
+      @object = target.object #: YARD::CodeObjects::Base
+      @keep_existing = keep_existing
+      @parameter_names = ParameterNames.new(@object)
+      @typed = []
+    end
+
+    # @rbs (ParseResult result) -> void
+    def apply(result)
+      @result = result
+      @typed = []
+      @tags = @target.tags
+      inject_overload_tags(result.overloads)
+      inject_param_tags
+      inject_return_or_writer_param_tag(result.return_type, result.return_description)
+      inject_yield_tags(result.block_annotation)
+      @target.tags = @tags
+    end
+
+    private
+
+    # The @overload tags of the docstring win: they are written by hand. A declaration that an
+    # inline annotation already typed adds none.
+    # @rbs (Array[signature] signatures) -> void
+    def inject_overload_tags(signatures)
+      return if signatures.empty? || @tags.any? {|tag| tag.tag_name == 'overload'}
+      if @keep_existing && InlineTypes.any?(@object)
+        return @result.add_duplicate(Annotated::SIGNATURE)
+      end
+
+      @tags += signatures.map do |signature|
+        YARD::Tags::OverloadTag.new(:overload, OverloadText.new(@object.name, signature).to_s)
+      end
+      @typed |= [Annotated::SIGNATURE]
+    end
+
+    # @rbs () -> void
+    def inject_param_tags
+      @result.named_param_types.each do |name, annotation|
+        inject_param_tag(@parameter_names.resolve_splat(name), annotation.type,
+                         annotation.description)
+      end
+      inject_positional_param_tags(@result.positional_param_types)
+      sort_param_tags
+    end
+
+    # YARD renders @param tags in tag order. Unknown names keep their order, at the end.
+    # @rbs () -> void
+    def sort_param_tags
+      tag_order = @parameter_names.tag_order
+      param_tags, other_tags = @tags.partition {|tag| tag.tag_name == 'param'}
+      @tags = other_tags + param_tags.sort_by.with_index do |tag, index|
+        [tag_order.index(tag.name) || tag_order.size, index]
+      end
+    end
+
+    # The Ruby names win, because Steep does not check RBS parameter names. Without Ruby
+    # parameters, e.g. a method that only exists in a `.rbs` file, the RBS names are used, and
+    # the unnamed parameters are called arg0, arg1, ...
+    # @rbs (Array[PositionalParamType] positional_param_types) -> void
+    def inject_positional_param_tags(positional_param_types)
+      names = @parameter_names.positional
+      positional_param_types.each_with_index do |param, index|
+        name = if @parameter_names.empty?
+                 param.name || ParameterNames.placeholder(index)
+               else
+                 names[index]
+               end
+        inject_param_tag(name, param.type, param.description) if name
+      end
+    end
+
+    # @rbs (String name, String? yard_type, String? description) -> void
+    def inject_param_tag(name, yard_type, description)
+      return if yard_type.nil?
+
+      annotated = Annotated.parameter(name)
+      return @result.add_duplicate(annotated) if @typed.include?(annotated)
+
+      replace_tag('param', name, [yard_type], description, annotated)
+    end
+
+    # @rbs (BlockAnnotation? block_annotation) -> void
+    def inject_yield_tags(block_annotation)
+      return if block_annotation.nil?
+
+      replace_tag('yield', nil, block_annotation.yield_types, nil, Annotated::BLOCK)
+      return_type = block_annotation.return_type
+      replace_tag('yieldreturn', nil, [return_type], nil, Annotated::BLOCK) if return_type
+    end
+
+    # Replaces the tags of `tag_name` and `name` with one of `types`, and records `annotated` as
+    # typed. The description of the annotation wins, else that of the tag it replaces. A kept tag
+    # stays as it is, and is a duplicate when an inline annotation typed it.
+    # @rbs (String tag_name, String? name, Array[String?] types, String? description,
+    #   String annotated) -> void
+    def replace_tag(tag_name, name, types, description, annotated)
+      replaced, other_tags = @tags.partition {|tag| tag.tag_name == tag_name && tag.name == name}
+      return record_kept(annotated) if kept?(replaced)
+
+      text = description || replaced.first&.text || ''
+      @tags = other_tags + [YARD::Tags::Tag.new(tag_name, text, types, name)]
+      @typed |= [annotated]
+    end
+
+    # A writer's type describes its parameter. `writer?` is not set yet in after_parse. A
+    # signature such as `(Symbol, Integer) -> Integer` types the value twice, which is no duplicate.
+    # @rbs (String? yard_type, String? description) -> void
+    def inject_return_or_writer_param_tag(yard_type, description)
+      return unless yard_type
+
+      if @object.name.match?(/\A(\w+|\[\])=\z/)
+        value = value_parameter_name
+        inject_param_tag(value, yard_type, description) if @typed.none?(Annotated.parameter(value))
+      else
+        replace_tag('return', nil, [yard_type], description, Annotated::RETURN_TYPE)
+      end
+    end
+
+    # The parameter that a writer sets: the last one, as in `[]=(key, value)`. Without Ruby
+    # parameters, the one that the last annotated parameter was tagged as.
+    # @rbs () -> String
+    def value_parameter_name
+      @parameter_names.positional.last || annotated_value_name || 'value'
+    end
+
+    # @rbs () -> String?
+    def annotated_value_name
+      params = @result.positional_param_types
+      last = params.last
+      return if last.nil?
+
+      last.name || ParameterNames.placeholder(params.size - 1)
+    end
+
+    # With keep_existing, a tag that already has types is kept; one with only a description gets
+    # the RBS type.
+    # @rbs (Array[YARD::Tags::Tag] tags) -> bool
+    def kept?(tags)
+      @keep_existing && tags.any? {|tag| tag.types.to_a.any?}
+    end
+
+    # @rbs (String annotated) -> void
+    def record_kept(annotated)
+      @result.add_duplicate(annotated) if InlineTypes.typed?(@object, annotated)
+    end
+  end
+end

data/lib/yard_inline_rbs/tag_injector.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module YardInlineRbs
+  # Injects typed tags from the RBS annotations of a YARD DocstringParser. RBS types override
+  # YARD types. The annotations are always stripped from the docstring, also when invalid: the
+  # warning reports the problem, and the raw text would only clutter the documentation.
+  class TagInjector
+    # @rbs @parser: YARD::DocstringParser
+
+    # @rbs (YARD::DocstringParser parser) -> void
+    def initialize(parser)
+      @parser = parser
+    end
+
+    # @rbs () -> void
+    def inject
+      object = @parser.object
+      return if object.nil?
+
+      source = DeclarationSource.new(object, @parser.handler)
+      inline_annotations = collect_inline_annotations
+      rbs_tag_texts = collect_rbs_tag_texts
+      result = parse_rbs_annotations(source, rbs_tag_texts, inline_annotations)
+
+      annotated = inline_annotations.any? || rbs_tag_texts.any?
+      record_and_report(object, source, result, apply_result(source, result, inline_annotations))
+      keep_previous_description(object) if annotated && @parser.text.empty?
+    end
+
+    private
+
+    # Records what the annotations typed, for RbsFileTags, and warns about their problems. The
+    # warnings come after the tags are applied, which finds more duplicates.
+    # @rbs (YARD::CodeObjects::Base object, DeclarationSource source, ParseResult result,
+    #   Array[String] typed) -> void
+    def record_and_report(object, source, result, typed)
+      location = source.location_text
+      InlineTypes.record(object, typed, location)
+      AnnotationWarnings.new(location).report(result)
+    end
+
+    # @rbs (DeclarationSource source, Array[String] rbs_tag_texts, Array[String] inline_annotations)
+    #   -> ParseResult
+    def parse_rbs_annotations(source, rbs_tag_texts, inline_annotations)
+      RbsCommentParser.new(rbs_tag_texts, own_annotations(source, inline_annotations),
+                           source.trailing_comment_line).parse
+    end
+
+    # The `#:` lines of a comment that YARD took from an earlier statement belong to that
+    # statement, so they are skipped; they are still removed from the description.
+    # @rbs (DeclarationSource source, Array[String] inline_annotations) -> Array[String]
+    def own_annotations(source, inline_annotations)
+      return [] if source.comment_of_earlier_statement?
+
+      inline_annotations
+    end
+
+    # The tags are only rewritten when there is a type to apply.
+    # @rbs (DeclarationSource source, ParseResult result, Array[String] inline_annotations)
+    #   -> Array[String]
+    # @return [Array<String>] What the annotations typed, such as `the return type`.
+    def apply_result(source, result, inline_annotations)
+      clean_description(source, inline_annotations)
+      remove_rbs_tags
+      return [] if result.empty?
+
+      applier = ResultApplier.new(@parser)
+      applier.apply(result)
+      applier.typed
+    end
+
+    # YARD replaces the docstring of an object with each comment it parses, also with a comment
+    # that only holds annotations. The previous description, such as that of a `.rbs`
+    # declaration, is still on the object while the new one is parsed.
+    # @rbs (YARD::CodeObjects::Base object) -> void
+    def keep_previous_description(object)
+      @parser.text = object.docstring.to_s
+    end
+
+    # @rbs () -> Array[String]
+    def collect_rbs_tag_texts
+      @parser.tags.select {|tag| tag.tag_name == 'rbs'}.map(&:text)
+    end
+
+    # The description lines of each `#:` annotation: the line starting with `:` and the indented
+    # lines below it, on which a signature can continue.
+    # @rbs () -> Array[String]
+    def collect_inline_annotations
+      annotations = [] #: Array[String]
+      continued = false
+      @parser.text.each_line do |line|
+        continuation = continued && line.match?(/\A\s+\S/)
+        annotations << line if inline_annotation?(line)
+        annotations << "#{annotations.pop}#{line}" if continuation
+        continued = continuation || inline_annotation?(line)
+      end
+      annotations
+    end
+
+    # `: Type`, or only `:`, which is reported as an invalid type.
+    # @rbs (String line) -> bool
+    def inline_annotation?(line)
+      stripped = line.strip
+      stripped == ':' || stripped.start_with?(': ')
+    end
+
+    # @rbs (DeclarationSource source, Array[String] inline_annotations) -> void
+    def clean_description(source, inline_annotations)
+      annotation_lines = inline_annotations.flat_map(&:lines).map(&:strip)
+      application = source.superclass_type_application
+      annotation_lines << application if application
+      return if annotation_lines.empty?
+
+      @parser.text = @parser.text.lines
+                            .reject {|line| annotation_lines.include?(line.strip)}
+                            .join
+                            .strip
+    end
+
+    # @rbs () -> void
+    def remove_rbs_tags
+      @parser.tags = @parser.tags.reject {|tag| tag.tag_name == 'rbs'}
+    end
+  end
+end

data/lib/yard_inline_rbs/type_parser.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module YardInlineRbs
+  # Parses RBS type strings into YARD types, recording invalid ones as parse errors.
+  class TypeParser
+    # @rbs @parse_errors: Array[String]
+
+    # @rbs (Array[String] parse_errors) -> void
+    def initialize(parse_errors)
+      @parse_errors = parse_errors
+    end
+
+    # RBS returns nil for empty text instead of raising.
+    # @rbs (String text) -> String?
+    def type(text)
+      rbs_type = RBS::Parser.parse_type(text, require_eof: true)
+      rbs_type ? RbsTypeFormatter.format(rbs_type) : record_error(text)
+    rescue RBS::ParsingError
+      record_error(text)
+    end
+
+    # A method type starts with its parameters, type parameters, block or arrow:
+    # `(Integer) -> String`, `[T] (T) -> T`, `{ () -> void } -> void`, `-> Integer`. A proc type
+    # (`^(Integer) -> String`) and a tuple, record or generic type that contains one also have an
+    # arrow, but they are plain types. Invalid text such as `(Integer` is recorded as the same parse
+    # error, whether it is parsed as a method type or as a plain type.
+    # @rbs (String text) -> bool
+    def method_type?(text)
+      text.start_with?('(', '[', '{', '->') && !plain_type?(text)
+    end
+
+    # @rbs (String text) -> signature?
+    def method_signature(text)
+      method_type = RBS::Parser.parse_method_type(text, require_eof: true)
+      method_type ? signature_of(method_type) : record_error(text)
+    rescue RBS::ParsingError
+      record_error(text)
+    end
+
+    # @rbs (RBS::MethodType method_type) -> signature
+    def signature_of(method_type)
+      function = method_type.type
+      return untyped_signature(function) if function.is_a?(RBS::Types::UntypedFunction)
+
+      function_types = RbsFunctionTypes.new(function)
+      block = method_type.block
+      { positional_types: function_types.positional_types,
+        named_types: function_types.named_types,
+        return_type: function_types.return_type,
+        block_annotation: block && block_annotation_of(block.type) }
+    end
+
+    # A plain type such as `Proc` yields no types.
+    #
+    # @rbs (String text) -> BlockAnnotation?
+    def block_annotation(text)
+      method_type = RBS::Parser.parse_method_type(text, require_eof: true)
+      method_type ? block_annotation_of(method_type.type) : plain_block_annotation(text)
+    rescue RBS::ParsingError
+      plain_block_annotation(text)
+    end
+
+    private
+
+    # `(?) -> untyped` has no parameters to document.
+    # @rbs (RBS::Types::UntypedFunction function) -> signature
+    def untyped_signature(function)
+      { positional_types: [], named_types: {}, block_annotation: nil,
+        return_type: RbsTypeFormatter.format(function.return_type) }
+    end
+
+    # @rbs (RBS::Types::function function) -> BlockAnnotation
+    def block_annotation_of(function)
+      if function.is_a?(RBS::Types::UntypedFunction)
+        return BlockAnnotation.new(yield_types: [],
+                                   return_type: RbsTypeFormatter.format(function.return_type))
+      end
+
+      function_types = RbsFunctionTypes.new(function)
+      BlockAnnotation.new(yield_types: function_types.yield_types,
+                          return_type: function_types.return_type)
+    end
+
+    # @rbs (String text) -> BlockAnnotation?
+    def plain_block_annotation(text)
+      return record_error(text) unless RBS::Parser.parse_type(text, require_eof: true)
+
+      BlockAnnotation.new(yield_types: [], return_type: nil)
+    rescue RBS::ParsingError
+      record_error(text)
+    end
+
+    # @rbs (String text) -> bool
+    def plain_type?(text)
+      !RBS::Parser.parse_type(text, require_eof: true).nil?
+    rescue RBS::ParsingError
+      false
+    end
+
+    # @rbs (String text) -> nil
+    def record_error(text)
+      @parse_errors << text
+      nil
+    end
+  end
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: yard-inline-rbs
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- yard-inline-rbs contributors
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-11-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rbs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.45
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.45
+description:
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/yard-inline-rbs.rb
+- lib/yard_inline_rbs/annotation_warnings.rb
+- lib/yard_inline_rbs/declaration_source.rb
+- lib/yard_inline_rbs/inline_annotations.rb
+- lib/yard_inline_rbs/inline_types.rb
+- lib/yard_inline_rbs/member_tags.rb
+- lib/yard_inline_rbs/object_tags.rb
+- lib/yard_inline_rbs/overload_text.rb
+- lib/yard_inline_rbs/parameter_names.rb
+- lib/yard_inline_rbs/parse_result.rb
+- lib/yard_inline_rbs/plugin.rb
+- lib/yard_inline_rbs/rbs_comment_parser.rb
+- lib/yard_inline_rbs/rbs_description.rb
+- lib/yard_inline_rbs/rbs_file_tags.rb
+- lib/yard_inline_rbs/rbs_function_types.rb
+- lib/yard_inline_rbs/rbs_handler_patches.rb
+- lib/yard_inline_rbs/rbs_type_formatter.rb
+- lib/yard_inline_rbs/result_applier.rb
+- lib/yard_inline_rbs/tag_injector.rb
+- lib/yard_inline_rbs/type_parser.rb
+homepage: https://github.com/vdbijl/yard_inline_rbs_plugin
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/vdbijl/yard_inline_rbs_plugin
+  changelog_uri: https://github.com/vdbijl/yard_inline_rbs_plugin/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/vdbijl/yard_inline_rbs_plugin/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.22
+signing_key:
+specification_version: 4
+summary: 'YARD plugin: use inline RBS type annotations in documentation'
+test_files: []