Merge attr sigs too

Author: dduugg

CHANGELOG.md

@@ -2,7 +2,11 @@
 
 ## main
 
-###
+### New Features
+
+* [#141](https://github.com/dduugg/yard-sorbet/issues/141) Merge RBI sigs into existing documentation
+
+### Bug Fixes
 
 * Handle multiple invocations of `mixes_in_class_methods` within a class
 

README.md

@@ -12,6 +12,7 @@ A YARD [plugin](https://rubydoc.info/gems/yard/file/docs/GettingStarted.md#Plugi
 - Generates constant definitions from `T::Enum` enums
 - Modules marked `abstract!` or `interface!` are tagged `@abstract`
 - Modules using `mixes_in_class_methods` will attach class methods
+- Merges `sig`s in rbi files with source code documentation (rbi files must come after source code in yard configuration)
 
 ## Usage
 

lib/yard-sorbet/handlers/sig_handler.rb

@@ -13,7 +13,7 @@ class SigHandler < YARD::Handlers::Ruby::Base
       # YARD types that can have docstrings attached to them
       Documentable = T.type_alias do
         T.any(
-          YARD::CodeObjects::MethodObject, YARD::Parser::Ruby::MethodDefinitionNode, YARD::Parser::Ruby::MethodCallNode
+          YARD::CodeObjects::MethodObject, YARD::Parser::Ruby::MethodCallNode, YARD::Parser::Ruby::MethodDefinitionNode
         )
       end
       private_constant :Documentable
@@ -29,6 +29,8 @@ def process
         end
       end
 
+      private
+
       sig { params(def_node: YARD::Parser::Ruby::MethodDefinitionNode).void }
       def process_def(def_node)
         separator = scope == :instance && def_node.type == :def ? '#' : '.'
@@ -44,12 +46,27 @@ def process_def(def_node)
 
       sig { params(attr_node: YARD::Parser::Ruby::MethodCallNode).void }
       def process_attr(attr_node)
-        # TODO: Merge with existing attr documentation (#141)
+        names = NodeUtils.validated_attribute_names(attr_node)
+        return if merged_into_attr?(attr_node, names)
+
         parse_node(attr_node, statement.docstring, include_params: false)
         statement.docstring = nil
       end
 
-      private
+      # An attr* sig can be merged into a previous attr* docstring if it is the only parameter passed to the attr*
+      # declaration. This is to avoid needing to rewrite the source code to separate merged and unmerged attr*
+      # declarations.
+      sig { params(attr_node: YARD::Parser::Ruby::MethodCallNode, names: T::Array[String]).returns(T::Boolean) }
+      def merged_into_attr?(attr_node, names)
+        return false if names.size == 1
+
+        nodes = namespace.attributes[scope][names.fetch(0)]
+        return false if nodes.nil? || nodes.empty?
+
+        nodes.each_value { parse_node(_1, _1.docstring, include_params: false) }
+        attr_node.docstring = statement.docstring = nil
+        true
+      end
 
       sig { params(attach_to: Documentable, docstring: T.nilable(String), include_params: T::Boolean).void }
       def parse_node(attach_to, docstring, include_params: true)

lib/yard-sorbet/node_utils.rb

@@ -51,5 +51,18 @@ def self.sigable_node?(node)
       else false
       end
     end
+
+    # @see https://github.com/lsegal/yard/blob/main/lib/yard/handlers/ruby/attribute_handler.rb
+    #   YARD::Handlers::Ruby::AttributeHandler.validated_attribute_names
+    sig { params(attr_node: YARD::Parser::Ruby::MethodCallNode).returns(T::Array[String]) }
+    def self.validated_attribute_names(attr_node)
+      attr_node.parameters(false).map do |obj|
+        case obj.type
+        when :symbol_literal then obj.jump(:ident, :op, :kw, :const).source
+        when :string_literal then obj.jump(:string_content).source
+        else raise YARD::Parser::UndocumentableError, obj.source
+        end
+      end
+    end
   end
 end

spec/data/sig_handler.rbi.txt

@@ -1,5 +1,14 @@
 module Merge
   class A
+    sig { returns(Numeric) }
+    attr_accessor :a_foo
+
+    sig { returns(T.nilable(String)) }
+    attr_reader :a_bar
+
+    sig { params(writer: Integer).returns(Integer) }
+    attr_writer :a_baz
+
     sig { returns(String) }
     def foo; end
 

spec/data/sig_handler.txt

@@ -340,6 +340,13 @@ end
 
 module Merge
   class A
+    # annotated attr_accessor
+    attr_accessor :a_foo
+
+    attr_reader :a_bar
+
+    attr_writer :a_baz
+
     # The foo instance method for A
     def foo; end
 

spec/yard_sorbet/handlers/sig_handler_spec.rb

@@ -2,19 +2,17 @@
 # frozen_string_literal: true
 
 RSpec.describe YARDSorbet::Handlers::SigHandler do
-  path = File.join(File.expand_path('../../data', __dir__), 'sig_handler.txt')
 
-  before do
+  # The rubocop disable isn't necessary, but it speeds up tests considerably
+  before(:all) do # rubocop:disable RSpec/BeforeAfterAll
     YARD::Registry.clear
+    path = File.join(File.expand_path('../../data', __dir__), 'sig_handler.txt')
     YARD::Parser::SourceParser.parse(path)
+    rbi_path = File.join(File.expand_path('../../data', __dir__), 'sig_handler.rbi.txt')
+    YARD::Parser::SourceParser.parse(rbi_path)
   end
 
   describe 'Merging an RBI file' do
-    before do
-      rbi_path = File.join(File.expand_path('../../data', __dir__), 'sig_handler.rbi.txt')
-      YARD::Parser::SourceParser.parse(rbi_path)
-    end
-
     it 'includes docstring from original instance def' do
       expect(YARD::Registry.at('Merge::A#foo').docstring).to eq('The foo instance method for A')
     end