Improve type annotations based on typechecker feedback

lib/solargraph/api_map.rb

@@ -343,6 +343,7 @@ def get_block_pins
     def get_methods rooted_tag, scope: :instance, visibility: [:public], deep: true
       cached = cache.get_methods(rooted_tag, scope, visibility, deep)
       return cached.clone unless cached.nil?
+      # @type [Array<Solargraph::Pin::Method>]
       result = []
       skip = Set.new
       if rooted_tag == ''
@@ -768,8 +769,8 @@ def get_namespace_type fqns
 
     # Sort an array of pins to put nil or undefined variables last.
     #
-    # @param pins [Enumerable<Solargraph::Pin::Base>]
-    # @return [Enumerable<Solargraph::Pin::Base>]
+    # @param pins [Enumerable<Pin::BaseVariable>]
+    # @return [Enumerable<Pin::BaseVariable>]
     def prefer_non_nil_variables pins
       result = []
       nil_pins = []

lib/solargraph/api_map/cache.rb

@@ -8,7 +8,7 @@ def initialize
         @methods = {}
         # @type [Hash{(String, Array<String>) => Array<Pin::Base>}]
         @constants = {}
-        # @type [Hash{(String, String) => String}]
+        # @type [Hash{String => String}]
         @qualified_namespaces = {}
         # @type [Hash{String => Pin::Method}]
         @receiver_definitions = {}

lib/solargraph/api_map/store.rb

@@ -104,7 +104,7 @@ def namespaces
         @namespaces ||= Set.new
       end
 
-      # @return [Enumerable<Solargraph::Pin::Base>]
+      # @return [Enumerable<Solargraph::Pin::Namespace>]
       def namespace_pins
         pins_by_class(Solargraph::Pin::Namespace)
       end
@@ -149,8 +149,8 @@ def inspect
       end
 
       # @generic T
-      # @param klass [Class<T>]
-      # @return [Set<T>]
+      # @param klass [Class<generic<T>>]
+      # @return [Set<generic<T>>]
       def pins_by_class klass
         # @type [Set<Solargraph::Pin::Base>]
         s = Set.new
@@ -298,8 +298,8 @@ def index
         end
       end
 
-      # @param pin [Pin::Base]
-      # @param tag [String]
+      # @param pin [Pin::Method]
+      # @param tag [YARD::Tags::Tag]
       # @return [void]
       def redefine_return_type pin, tag
         return unless pin && tag.tag_name == 'return'

lib/solargraph/complex_type.rb

@@ -158,10 +158,14 @@ def rooted_tags
       map(&:rooted_tag).join(', ')
     end
 
+    # @yieldparam [UniqueType]
     def all? &block
       @items.all? &block
     end
 
+    # @yieldparam [UniqueType]
+    # @yieldreturn [Boolean]
+    # @return [Boolean]
     def any? &block
       @items.compact.any? &block
     end
@@ -263,7 +267,7 @@ class << self
       #   Consumers should not need to use this parameter; it should only be
       #   used internally.
       #
-      # @param *strings [Array<String>] The type definitions to parse
+      # @param strings [Array<String>] The type definitions to parse
       # @return [ComplexType]
       # # @overload parse(*strings, partial: false)
       # #  @todo Need ability to use a literal true as a type below

lib/solargraph/convention.rb

@@ -11,6 +11,7 @@ module Convention
     autoload :Gemspec, 'solargraph/convention/gemspec'
     autoload :Rakefile, 'solargraph/convention/rakefile'
 
+    # @type [Set<Convention::Base>]
     @@conventions = Set.new
 
     # @param convention [Class<Convention::Base>]

lib/solargraph/doc_map.rb

@@ -112,6 +112,7 @@ def try_gem_in_memory gemspec
       true
     end
 
+    # @param gemspec [Gem::Specification]
     def update_from_collection gemspec, gempins
       return gempins unless @rbs_path && File.directory?(@rbs_path)
       return gempins if RbsMap.new(gemspec.name, gemspec.version).resolved?

lib/solargraph/language_server/host.rb

@@ -476,6 +476,7 @@ def stopped?
       def locate_pins params
         return [] unless params['data'] && params['data']['uri']
         library = library_for(params['data']['uri'])
+        # @type [Array<Pin::Base>]
         result = []
         if params['data']['location']
           location = Location.new(
@@ -575,7 +576,7 @@ def signatures_at uri, line, column
       # @param column [Integer]
       # @param strip [Boolean] Strip special characters from variable names
       # @param only [Boolean] If true, search current file only
-      # @return [Array<Solargraph::Range>]
+      # @return [Array<Solargraph::Location>]
       def references_from uri, line, column, strip: true, only: false
         library = library_for(uri)
         library.references_from(uri_to_file(uri), line, column, strip: strip, only: only)

lib/solargraph/language_server/host/message_worker.rb

@@ -80,6 +80,9 @@ def next_message
         # True if the message requires a previous update to have executed in
         # order to work correctly.
         #
+        # @param msg [Hash{String => Object}]
+        # @todo need boolish type from RBS
+        # @return [Object]
         def version_dependent? msg
           msg['textDocument'] && msg['position']
         end

lib/solargraph/language_server/message/base.rb

@@ -16,7 +16,7 @@ class Base
         # @return [String]
         attr_reader :method
 
-        # @return [Hash{String => Array, Hash, String, Integer}]
+        # @return [Hash{String => Array<undefined>, Hash{String => undefined}, String, Integer}]
         attr_reader :params
 
         # @return [Hash, Array, nil]

lib/solargraph/language_server/message/text_document/formatting.rb

@@ -33,6 +33,7 @@ def process
 
           private
 
+          # @param corrections [String]
           def log_corrections(corrections)
             corrections = corrections&.strip
             return if corrections&.empty?
@@ -51,6 +52,7 @@ def config_for(file_uri)
             conf['rubocop'] || {}
           end
 
+          # @param config [Hash{String => String}]
           def cli_args file_uri, config
             file = UriHelpers.uri_to_file(file_uri)
             args = [
@@ -68,6 +70,7 @@ def cli_args file_uri, config
             args + [file]
           end
 
+          # @param config [Hash{String => String}]
           def formatter_class(config)
             if self.class.const_defined?('BlankRubocopFormatter')
               # @sg-ignore
@@ -79,6 +82,7 @@ def formatter_class(config)
             end
           end
 
+          # @param value [Array, String]
           def cop_list(value)
             value = value.join(',') if value.respond_to?(:join)
             return nil if value == '' || !value.is_a?(String)

lib/solargraph/library.rb

@@ -240,7 +240,7 @@ def signatures_at filename, line, column
     # @param column [Integer]
     # @param strip [Boolean] Strip special characters from variable names
     # @param only [Boolean] Search for references in the current file only
-    # @return [Array<Solargraph::Range>]
+    # @return [Array<Solargraph::Location>]
     # @todo Take a Location instead of filename/line/column
     def references_from filename, line, column, strip: false, only: false
       sync_catalog
@@ -398,6 +398,8 @@ def diagnose filename
       return [] unless open?(filename)
       result = []
       source = read(filename)
+
+      # @type [Hash{Class<Solargraph::Diagnostics::Base> => Array<String>}]
       repargs = {}
       workspace.config.reporters.each do |line|
         if line == 'all!'

lib/solargraph/parser/node_methods.rb

@@ -74,7 +74,7 @@ def process node
 
       # @abstract
       # @param node [Parser::AST::Node]
-      # @return [Hash{Parser::AST::Node => Chain}]
+      # @return [Hash{Parser::AST::Node => Source::Chain}]
       def convert_hash node
         raise NotImplementedError
       end

lib/solargraph/parser/node_processor.rb

@@ -9,6 +9,7 @@ module NodeProcessor
       autoload :Base, 'solargraph/parser/node_processor/base'
 
       class << self
+        # @type [Hash<Symbol, Class<NodeProcessor::Base>>]
         @@processors ||= {}
 
         # Register a processor for a node type.

lib/solargraph/parser/parser_gem/node_methods.rb

@@ -12,7 +12,7 @@
 #     class Node
 #       # New children
 #
-#       # @return [Array<AST::Node>]
+#       # @return [Array<self>]
 #       attr_reader :children
 #     end
 #   end
@@ -462,7 +462,7 @@ def explicit_return_values_from_compound_statement parent
               result
             end
 
-            # @param nodes [Enumerable<Parser::AST::Node, BaseObject>]
+            # @param nodes [Enumerable<Parser::AST::Node, BasicObject>]
             # @return [Array<Parser::AST::Node, nil>]
             def reduce_to_value_nodes nodes
               result = []

lib/solargraph/pin/base.rb

@@ -79,7 +79,7 @@ def all_rooted?
         !return_type || return_type.all_rooted?
       end
 
-      # @param generics_to_erase [Enumerable<String>]
+      # @param generics_to_erase [::Array<String>]
       # @return [self]
       def erase_generics(generics_to_erase)
         return self if generics_to_erase.empty?

lib/solargraph/pin/base_variable.rb

@@ -93,6 +93,7 @@ def == other
         assignment == other.assignment
       end
 
+      # @param pin [self]
       def try_merge! pin
         return false unless super
         @assignment = pin.assignment

lib/solargraph/pin/callable.rb

@@ -3,7 +3,7 @@
 module Solargraph
   module Pin
     class Callable < Closure
-      # @return [self]
+      # @return [Signature]
       attr_reader :block
 
       attr_reader :parameters
@@ -57,7 +57,7 @@ def resolve_generics_from_context(generics_to_resolve,
         callable
       end
 
-      # @param generics_to_resolve [Enumerable<String>]
+      # @param generics_to_resolve [::Array<String>]
       # @param arg_types [Array<ComplexType>, nil]
       # @param return_type_context [ComplexType, nil]
       # @param yield_arg_types [Array<ComplexType>, nil]
@@ -113,7 +113,7 @@ def transform_types(&transform)
       end
 
       # @param arguments [::Array<Chain>]
-      # @param signature [Pin::Signature]
+      # @param with_block [Boolean]
       # @return [Boolean]
       def arity_matches? arguments, with_block
         argcount = arguments.length

lib/solargraph/pin/method.rb

@@ -262,6 +262,7 @@ def attribute?
         @attribute
       end
 
+      # @parm other [Method]
       def nearly? other
         super &&
           parameters == other.parameters &&
@@ -273,6 +274,7 @@ def probe api_map
         attribute? ? infer_from_iv(api_map) : infer_from_return_nodes(api_map)
       end
 
+      # @param pin [Pin::Method]
       def try_merge! pin
         return false unless super
         @node = pin.node

lib/solargraph/pin/parameter.rb

@@ -3,7 +3,7 @@
 module Solargraph
   module Pin
     class Parameter < LocalVariable
-      # @return [Symbol]
+      # @return [::Symbol]
       attr_reader :decl
 
       # @return [String]
@@ -121,6 +121,7 @@ def documentation
         tag.text
       end
 
+      # @param pin [Pin::Parameter]
       def try_merge! pin
         return false unless super && closure == pin.closure
         true

lib/solargraph/rbs_map.rb

@@ -64,6 +64,7 @@ def self.load library
       @@rbs_maps_hash[library] ||= RbsMap.new(library)
     end
 
+    # @param gemspec [Gem::Specification]
     def self.from_gemspec(gemspec)
       RbsMap.new(gemspec.name, gemspec.version)
     end

lib/solargraph/shell.rb

@@ -111,6 +111,7 @@ def cache gem, version = nil
       also be specified to clear cached system documentation.
       Documentation will be regenerated as needed.
     )
+    # @param gems [Array<String>]
     # @return [void]
     def uncache *gems
       raise ArgumentError, 'No gems specified.' if gems.empty?
@@ -133,6 +134,7 @@ def uncache *gems
 
     desc 'gems [GEM[=VERSION]]', 'Cache documentation for installed gems'
     option :rebuild, type: :boolean, desc: 'Rebuild existing documentation', default: false
+    # @param names [Array<String>]
     # @return [void]
     def gems *names
       if names.empty?

lib/solargraph/source.rb

@@ -307,7 +307,7 @@ def stringify_comment_array comments
 
     # A hash of line numbers and their associated comments.
     #
-    # @return [Hash{Integer => Array<String>}]
+    # @return [Hash{Integer => Array<String>, nil}]
     def stringified_comments
       @stringified_comments ||= {}
     end
@@ -375,6 +375,7 @@ def inner_tree_at node, position, stack
 
     protected
 
+    # @return [Array<Change>]
     def changes
       @changes ||= []
     end

lib/solargraph/source/chain.rb

@@ -107,8 +107,8 @@ def define api_map, name_pin, locals
       end
 
       # @param api_map [ApiMap]
-      # @param name_pin [Pin::Base] The pin for the closure in which this code runs
-      # @param locals [::Enumerable<Pin::LocalVariable>]
+      # @param name_pin [Pin::Base]
+      # @param locals [::Array<Pin::LocalVariable>]
       # @return [ComplexType]
       # @sg-ignore
       def infer api_map, name_pin, locals
@@ -126,7 +126,7 @@ def infer api_map, name_pin, locals
 
       # @param api_map [ApiMap]
       # @param name_pin [Pin::Base]
-      # @param locals [::Enumerable<Pin::LocalVariable>]
+      # @param locals [::Array<Pin::LocalVariable>]
       # @return [ComplexType]
       def infer_uncached api_map, name_pin, locals
         pins = define(api_map, name_pin, locals)

lib/solargraph/source/chain/array.rb

@@ -14,7 +14,7 @@ def word
 
         # @param api_map [ApiMap]
         # @param name_pin [Pin::Base]
-        # @param locals [Enumerable<Pin::LocalVariable>]
+        # @param locals [::Array<Pin::Parameter, Pin::LocalVariable>]
         def resolve api_map, name_pin, locals
           child_types = @children.map do |child|
             child.infer(api_map, name_pin, locals)