More annotations in Solargraph code (#801)

* More annotations in Solargraph code

* More annotations from strict typechecking

* More internal annotations

* Add some method overloads

Author: apiology

lib/solargraph/api_map.rb

@@ -76,6 +76,7 @@ def catalog bench
       self
     end
 
+    # @return [::Array<Gem::Specification>]
     def uncached_gemspecs
       @doc_map.uncached_gemspecs
     end

lib/solargraph/api_map/store.rb

@@ -144,7 +144,9 @@ def inspect
       # @param klass [Class]
       # @return [Enumerable<Solargraph::Pin::Base>]
       def pins_by_class klass
-        @pin_select_cache[klass] ||= @pin_class_hash.each_with_object(Set.new) { |(key, o), n| n.merge(o) if key <= klass }
+        # @type [Set<Solargraph::Pin::Base>]
+        s = Set.new
+        @pin_select_cache[klass] ||= @pin_class_hash.each_with_object(s) { |(key, o), n| n.merge(o) if key <= klass }
       end
 
       # @param fqns [String]

lib/solargraph/complex_type.rb

@@ -66,7 +66,9 @@ def each &block
     end
 
     # @yieldparam [UniqueType]
-    # @return [Enumerator<UniqueType>]
+    # @return [void]
+    # @overload each_unique_type()
+    #   @return [Enumerator<UniqueType>]
     def each_unique_type &block
       return enum_for(__method__) unless block_given?
 
@@ -218,8 +220,11 @@ class << self
       #   used internally.
       #
       # @param *strings [Array<String>] The type definitions to parse
-      # @param partial [Boolean] True if the string is part of a another type
-      # @return [ComplexType, Array<UniqueType>] Array if partial is true
+      # @return [ComplexType]
+      # @overload parse(*strings, partial: false)
+      #  @todo Need ability to use a literal true as a type below
+      #  @param partial [Boolean] True if the string is part of a another type
+      #  @return [Array<UniqueType>]
       def parse *strings, partial: false
         # @type [Hash{Array<String> => ComplexType}]
         @cache ||= {}

lib/solargraph/complex_type/type_methods.rb

@@ -13,6 +13,12 @@ class ComplexType
     #   methods:
     #     transform()
     module TypeMethods
+      # @!method transform(new_name = nil, &transform_type)
+      #   @param new_name [String, nil]
+      #   @yieldparam t [UniqueType]
+      #   @yieldreturn [UniqueType]
+      #   @return [UniqueType, nil]
+
       # @return [String]
       attr_reader :name
 

lib/solargraph/complex_type/unique_type.rb

@@ -135,8 +135,8 @@ def to_a
       end
 
       # @param new_name [String, nil]
-      # @param new_key_types [Enumerable<UniqueType>, nil]
-      # @param new_subtypes [Enumerable<UniqueType>, nil]
+      # @param new_key_types [Array<UniqueType>, nil]
+      # @param new_subtypes [Array<UniqueType>, nil]
       # @return [self]
       def recreate(new_name: nil, new_key_types: nil, new_subtypes: nil)
         new_name ||= name
@@ -175,8 +175,8 @@ def recreate(new_name: nil, new_key_types: nil, new_subtypes: nil)
       #
       # @param new_name [String, nil]
       # @yieldparam t [UniqueType]
-      # @yieldreturn [UniqueType]
-      # @return [UniqueType, nil]
+      # @yieldreturn [self]
+      # @return [self]
       def transform(new_name = nil, &transform_type)
         new_key_types = @key_types.flat_map { |ct| ct.map { |ut| ut.transform(&transform_type) } }.compact
         new_subtypes = @subtypes.flat_map { |ct| ct.map { |ut| ut.transform(&transform_type) } }.compact

lib/solargraph/doc_map.rb

@@ -59,6 +59,8 @@ def generate
       end
     end
 
+    # @param gemspec [Gem::Specification]
+    # @return [void]
     def try_rbs_map gemspec
       cache_file = File.join('gems', "#{gemspec.name}-#{gemspec.version}.ser")
       if Cache.exist?(cache_file)
@@ -69,6 +71,8 @@ def try_rbs_map gemspec
       end
     end
 
+    # @param name [String]
+    # @return [void]
     def try_stdlib_map name
       map = RbsMap::StdlibMap.new(name)
       return unless map.resolved?
@@ -93,6 +97,8 @@ def resolve_path_to_gemspec path
       end
     end
 
+    # @param gemspec [Gem::Specification]
+    # @param version [Gem::Version]
     def change_gemspec_version gemspec, version
       Gem::Specification.find_by_name(gemspec.name, "= #{version}")
     rescue Gem::MissingSpecError

lib/solargraph/gem_pins.rb

@@ -49,7 +49,7 @@ class << self
       def build_yard_pins(gemspec)
         Yardoc.cache(gemspec) unless Yardoc.cached?(gemspec)
         yardoc = Yardoc.load!(gemspec)
-        YardMap::Mapper.new(yardoc, gemspec).map  
+        YardMap::Mapper.new(yardoc, gemspec).map
       end
 
       # Select the first defined type.

lib/solargraph/language_server/message/workspace/did_change_configuration.rb

@@ -11,6 +11,7 @@ def process
 
     private
 
+    # @return [void]
     def register_from_options
       Solargraph.logger.debug "Registering capabilities from options: #{host.options.inspect}"
       # @type [Array<String>]

lib/solargraph/parser/node_methods.rb

@@ -10,6 +10,14 @@ def unpack_name node
         raise NotImplementedError
       end
 
+      # @abstract
+      # @todo Temporarily here for testing. Move to Solargraph::Parser.
+      # @param node [Parser::AST::Node]
+      # @return [Array<Parser::AST::Node>]
+      def call_nodes_from node
+        raise NotImplementedError
+      end
+
       # Find all the nodes within the provided node that potentially return a
       # value.
       #
@@ -27,6 +35,14 @@ def returns_from_method_body node
         raise NotImplementedError
       end
 
+      # @abstract
+      # @param node [Parser::AST::Node]
+      #
+      # @return [Array<Parser::AST::Node>]
+      def const_nodes_from node
+        raise NotImplementedError
+      end
+
       # @abstract
       # @param cursor [Solargraph::Source::Cursor]
       # @return [Parser::AST::Node, nil]
@@ -43,6 +59,11 @@ def value_position_nodes_only(node)
         raise NotImplementedError
       end
 
+      # @abstract
+      # @param nodes [Enumerable<Parser::AST::Node>]
+      def any_splatted_call?(nodes)
+        raise NotImplementedError
+      end
 
       # @abstract
       # @param node [Parser::AST::Node]

lib/solargraph/parser/parser_gem/class_methods.rb

@@ -32,7 +32,7 @@ def parse code, filename = nil, line = 0
           raise Parser::SyntaxError, e.message
         end
 
-        # @return [Parser::Base]
+        # @return [::Parser::Base]
         def parser
           # @todo Consider setting an instance variable. We might not need to
           #   recreate the parser every time we use it.
@@ -115,6 +115,7 @@ def infer_literal_node_type node
           NodeMethods.infer_literal_node_type node
         end
 
+        # @return [void]
         def version
           parser.version
         end

lib/solargraph/parser/parser_gem/node_chainer.rb

@@ -50,6 +50,7 @@ def load_string(code)
         def generate_links n
           return [] unless n.is_a?(::Parser::AST::Node)
           return generate_links(n.children[0]) if n.type == :splat
+          # @type [Array<Chain::Link>]
           result = []
           if n.type == :block
             result.concat NodeChainer.chain(n.children[0], @filename, n).links

lib/solargraph/pin/block.rb

@@ -8,6 +8,8 @@ class Block < Closure
       # @return [Parser::AST::Node]
       attr_reader :receiver
 
+      # @param receiver [Parser::AST::Node, nil]
+      # @param context [ComplexType, nil]
       # @param args [::Array<Parameter>]
       def initialize receiver: nil, args: [], context: nil, **splat
         super(**splat)

lib/solargraph/pin/namespace.rb

@@ -74,6 +74,7 @@ def return_type
         @return_type ||= ComplexType.try_parse( (type == :class ? 'Class' : 'Module') + "<#{path}>" )
       end
 
+      # @return [Array<String>]
       def domains
         @domains ||= []
       end

lib/solargraph/shell.rb

@@ -233,6 +233,9 @@ def bundle
     end
 
     desc 'cache', 'Cache a gem', hide: true
+    # @return [void]
+    # @param gem [String]
+    # @param version [String, nil]
     def cache gem, version = nil
       spec = Gem::Specification.find_by_name(gem, version)
       pins = GemPins.build(spec)
@@ -241,6 +244,7 @@ def cache gem, version = nil
 
     desc 'gems', 'Cache documentation for installed gems'
     option :rebuild, type: :boolean, desc: 'Rebuild existing documentation', default: false
+    # @return [void]
     def gems *names
       if names.empty?
         Gem::Specification.to_a.each do |spec|