solargraph 0.56.0 → 0.57.0

data/lib/solargraph/convention/struct_definition.rb

@@ -8,8 +8,9 @@ module Solargraph
 
       module NodeProcessors
         class StructNode < Parser::NodeProcessor::Base
+          # @return [Boolean] continue processing the next processor of the same node.
           def process
-            return if struct_definition_node.nil?
+            return true if struct_definition_node.nil?
 
             loc = get_node_location(node)
             nspin = Solargraph::Pin::Namespace.new(
@@ -17,9 +18,10 @@ module Solargraph
               location: loc,
               closure: region.closure,
               name: struct_definition_node.class_name,
-              comments: comments_for(node),
+              docstring: docstring,
               visibility: :public,
-              gates: region.closure.gates.freeze
+              gates: region.closure.gates.freeze,
+              source: :struct_definition
             )
             pins.push nspin
 
@@ -31,7 +33,8 @@ module Solargraph
               location: get_node_location(node),
               closure: nspin,
               visibility: :private,
-              comments: comments_for(node)
+              docstring: docstring,
+              source: :struct_definition
             )
 
             pins.push initialize_method_pin
@@ -42,7 +45,8 @@ module Solargraph
                   name: attribute_name,
                   decl: struct_definition_node.keyword_init? ? :kwarg : :arg,
                   location: get_node_location(attribute_node),
-                  closure: initialize_method_pin
+                  closure: initialize_method_pin,
+                  source: :struct_definition
                 )
               )
             end
@@ -50,49 +54,108 @@ module Solargraph
             # define attribute accessors and instance variables
             struct_definition_node.attributes.each do |attribute_node, attribute_name|
               [attribute_name, "#{attribute_name}="].each do |name|
+                docs = docstring.tags.find { |t| t.tag_name == 'param' && t.name == attribute_name }
+
+                attribute_type = ComplexType.parse(tag_string(docs))
+                return_type_comment = attribute_comment(docs, false)
+                param_comment = attribute_comment(docs, true)
+
                 method_pin = Pin::Method.new(
                   name: name,
                   parameters: [],
                   scope: :instance,
                   location: get_node_location(attribute_node),
                   closure: nspin,
-                  comments: attribute_comments(attribute_node, attribute_name),
-                  visibility: :public
+                  docstring: YARD::Docstring.new(return_type_comment),
+                  # even assignments return the value
+                  comments: return_type_comment,
+                  return_type: attribute_type,
+                  visibility: :public,
+                  source: :struct_definition
                 )
 
-                pins.push method_pin
+                if name.end_with?('=')
+                  method_pin.parameters << Pin::Parameter.new(
+                    name: attribute_name,
+                    location: get_node_location(attribute_node),
+                    closure: method_pin,
+                    return_type: attribute_type,
+                    comments: param_comment,
+                    source: :struct_definition
+                  )
 
-                next unless name.include?('=') # setter
-                pins.push Pin::InstanceVariable.new(name: "@#{attribute_name}",
-                                                    closure: method_pin,
-                                                    location: get_node_location(attribute_node),
-                                                    comments: attribute_comments(attribute_node, attribute_name))
+                  pins.push Pin::InstanceVariable.new(name: "@#{attribute_name}",
+                                                      closure: method_pin,
+                                                      location: get_node_location(attribute_node),
+                                                      return_type: attribute_type,
+                                                      comments: "@type [#{attribute_type.rooted_tags}]",
+                                                      source: :struct_definition)
+                end
+
+                pins.push method_pin
               end
             end
 
             process_children region.update(closure: nspin, visibility: :public)
+            false
           end
 
           private
 
-          # @return [StructDefintionNode, nil]
+          # @return [StructDefintionNode, StructAssignmentNode, nil]
           def struct_definition_node
-            @struct_definition_node ||= if StructDefintionNode.valid?(node)
+            @struct_definition_node ||= if StructDefintionNode.match?(node)
                                           StructDefintionNode.new(node)
-                                        elsif StructAssignmentNode.valid?(node)
+                                        elsif StructAssignmentNode.match?(node)
                                           StructAssignmentNode.new(node)
                                         end
           end
 
-          # @param attribute_node [Parser::AST::Node]
-          # @return [String, nil]
-          def attribute_comments(attribute_node, attribute_name)
-            struct_comments = comments_for(attribute_node)
-            return if struct_comments.nil? || struct_comments.empty?
+          # Gets/generates the relevant docstring for this struct & it's attributes
+          # @return [YARD::Docstring]
+          def docstring
+            @docstring ||= parse_comments
+          end
+
+          # Parses any relevant comments for a struct int a yard docstring
+          # @return [YARD::Docstring]
+          def parse_comments
+            struct_comments = comments_for(node) || ''
+            struct_definition_node.attributes.each do |attr_node, attr_name|
+              comment = comments_for(attr_node)
+              next if comment.nil?
 
-            struct_comments.split("\n").find do |row|
-              row.include?(attribute_name)
-            end&.gsub('@param', '@return')&.gsub(attribute_name, '')
+              # We should support specific comments for an attribute, and that can be either a @return on an @param
+              # But since we merge into the struct_comments, then we should interpret either as a param
+              comment = "@param #{attr_name}#{comment[7..]}" if comment.start_with?('@return')
+
+              struct_comments += "\n#{comment}"
+            end
+
+            Solargraph::Source.parse_docstring(struct_comments).to_docstring
+          end
+
+          # @param tag [YARD::Tags::Tag, nil] The param tag for this attribute.xtract_
+          #
+          # @return [String]
+          def tag_string(tag)
+            tag&.types&.join(',') || 'undefined'
+          end
+
+          # @param tag [YARD::Tags::Tag, nil] The param tag for this attribute. If nil, this method is a no-op
+          # @param for_setter [Boolean] If true, will return a @param tag instead of a @return tag
+          #
+          # @return [String] The formatted comment for the attribute
+          def attribute_comment(tag, for_setter)
+            return "" if tag.nil?
+
+            suffix = "[#{tag_string(tag)}] #{tag.text}"
+
+            if for_setter
+              "@param #{tag.name} #{suffix}"
+            else
+              "@return #{suffix}"
+            end
           end
         end
       end

data/lib/solargraph/convention.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-
 module Solargraph
   # Conventions provide a way to modify an ApiMap based on expectations about
   # one of its sources.
@@ -11,6 +10,8 @@ module Solargraph
     autoload :Gemspec, 'solargraph/convention/gemspec'
     autoload :Rakefile, 'solargraph/convention/rakefile'
     autoload :StructDefinition, 'solargraph/convention/struct_definition'
+    autoload :DataDefinition,   'solargraph/convention/data_definition'
+    autoload :ActiveSupportConcern, 'solargraph/convention/active_support_concern'
 
     # @type [Set<Convention::Base>]
     @@conventions = Set.new
@@ -21,6 +22,12 @@ module Solargraph
       @@conventions.add convention.new
     end
 
+    # @param convention [Class<Convention::Base>]
+    # @return [void]
+    def self.unregister convention
+      @@conventions.delete_if { |c| c.is_a?(convention) }
+    end
+
     # @param source_map [SourceMap]
     # @return [Environ]
     def self.for_local(source_map)
@@ -31,7 +38,7 @@ module Solargraph
       result
     end
 
-    # @param yard_map [DocMap]
+    # @param doc_map [DocMap]
     # @return [Environ]
     def self.for_global(doc_map)
       result = Environ.new
@@ -41,8 +48,31 @@ module Solargraph
       result
     end
 
+    # Provides any additional method pins based on the described object.
+    #
+    # @param api_map [ApiMap]
+    # @param rooted_tag [String] A fully qualified namespace, with
+    #   generic parameter values if applicable
+    # @param scope [Symbol] :class or :instance
+    # @param visibility [Array<Symbol>] :public, :protected, and/or :private
+    # @param deep [Boolean]
+    # @param skip [Set<String>]
+    # @param no_core [Boolean] Skip core classes if true
+    #
+    # @return [Environ]
+    def self.for_object api_map, rooted_tag, scope, visibility,
+                        deep, skip, no_core
+      result = Environ.new
+      @@conventions.each do |conv|
+        result.merge conv.object(api_map, rooted_tag, scope, visibility,
+                                 deep, skip, no_core)
+      end
+      result
+    end
+
     register Gemfile
     register Gemspec
     register Rakefile
+    register ActiveSupportConcern
   end
 end

data/lib/solargraph/diagnostics/rubocop.rb

@@ -28,7 +28,12 @@ module Solargraph
         options, paths = generate_options(source.filename, source.code)
         store = RuboCop::ConfigStore.new
         runner = RuboCop::Runner.new(options, store)
-        result = redirect_stdout{ runner.run(paths) }
+        # Ensure only one instance of RuboCop::Runner is running at
+        # a time - it uses 'chdir' to read config files with ERB,
+        # which can conflict with other chdirs.
+        result = Solargraph::CHDIR_MUTEX.synchronize do
+          redirect_stdout{ runner.run(paths) }
+        end
 
         return [] if result.empty?
 

data/lib/solargraph/diagnostics/rubocop_helpers.rb

@@ -15,10 +15,10 @@ module Solargraph
       # @return [void]
       def require_rubocop(version = nil)
         begin
+          # @type [String]
           gem_path = Gem::Specification.find_by_name('rubocop', version).full_gem_path
           gem_lib_path = File.join(gem_path, 'lib')
           $LOAD_PATH.unshift(gem_lib_path) unless $LOAD_PATH.include?(gem_lib_path)
-        # @todo Gem::MissingSpecVersionError is undocumented for some reason
         # @sg-ignore
         rescue Gem::MissingSpecVersionError => e
           raise InvalidRubocopVersionError,

data/lib/solargraph/doc_map.rb

@@ -2,6 +2,7 @@
 
 require 'pathname'
 require 'benchmark'
+require 'open3'
 
 module Solargraph
   # A collection of pins generated from required gems.
@@ -21,8 +22,9 @@ module Solargraph
 
     # @return [Array<Gem::Specification>]
     def uncached_gemspecs
-      (uncached_yard_gemspecs + uncached_rbs_collection_gemspecs).sort.
-        uniq { |gemspec| "#{gemspec.name}:#{gemspec.version}" }
+      uncached_yard_gemspecs.concat(uncached_rbs_collection_gemspecs)
+                            .sort
+                            .uniq { |gemspec| "#{gemspec.name}:#{gemspec.version}" }
     end
 
     # @return [Array<Gem::Specification>]
@@ -31,8 +33,10 @@ module Solargraph
     # @return [Array<Gem::Specification>]
     attr_reader :uncached_rbs_collection_gemspecs
 
+    # @return [String, nil]
     attr_reader :rbs_collection_path
 
+    # @return [String, nil]
     attr_reader :rbs_collection_config_path
 
     # @return [Workspace, nil]
@@ -51,10 +55,13 @@ module Solargraph
       @rbs_collection_path = workspace&.rbs_collection_path
       @rbs_collection_config_path = workspace&.rbs_collection_config_path
       @environ = Convention.for_global(self)
+      @requires.concat @environ.requires if @environ
       load_serialized_gem_pins
       pins.concat @environ.pins
     end
 
+    # @param out [IO]
+    # @return [void]
     def cache_all!(out)
       # if we log at debug level:
       if logger.info?
@@ -72,12 +79,18 @@ module Solargraph
       @uncached_yard_gemspecs = []
     end
 
+    # @param gemspec [Gem::Specification]
+    # @param out [IO]
+    # @return [void]
     def cache_yard_pins(gemspec, out)
-      pins = GemPins.build_yard_pins(gemspec)
+      pins = GemPins.build_yard_pins(yard_plugins, gemspec)
       PinCache.serialize_yard_gem(gemspec, pins)
       logger.info { "Cached #{pins.length} YARD pins for gem #{gemspec.name}:#{gemspec.version}" } unless pins.empty?
     end
 
+    # @param gemspec [Gem::Specification]
+    # @param out [IO]
+    # @return [void]
     def cache_rbs_collection_pins(gemspec, out)
       rbs_map = RbsMap.from_gemspec(gemspec, rbs_collection_path, rbs_collection_config_path)
       pins = rbs_map.pins
@@ -89,6 +102,9 @@ module Solargraph
     end
 
     # @param gemspec [Gem::Specification]
+    # @param rebuild [Boolean] whether to rebuild the pins even if they are cached
+    # @param out [IO, nil] output stream for logging
+    # @return [void]
     def cache(gemspec, rebuild: false, out: nil)
       build_yard = uncached_yard_gemspecs.include?(gemspec) || rebuild
       build_rbs_collection = uncached_rbs_collection_gemspecs.include?(gemspec) || rebuild
@@ -112,30 +128,42 @@ module Solargraph
       @unresolved_requires ||= required_gems_map.select { |_, gemspecs| gemspecs.nil? }.keys
     end
 
+    # @return [Hash{Array(String, String) => Array<Gem::Specification>}] Indexed by gemspec name and version
     def self.all_yard_gems_in_memory
       @yard_gems_in_memory ||= {}
     end
 
+    # @return [Hash{String => Hash{Array(String, String) => Array<Pin::Base>}}] stored by RBS collection path
     def self.all_rbs_collection_gems_in_memory
       @rbs_collection_gems_in_memory ||= {}
     end
 
+    # @return [Hash{Array(String, String) => Array<Pin::Base>}] Indexed by gemspec name and version
     def yard_pins_in_memory
       self.class.all_yard_gems_in_memory
     end
 
+    # @return [Hash{Array(String, String) => Array<Pin::Base>}] Indexed by gemspec name and version
     def rbs_collection_pins_in_memory
       self.class.all_rbs_collection_gems_in_memory[rbs_collection_path] ||= {}
     end
 
+    # @return [Hash{Array(String, String) => Array<Pin::Base>}] Indexed by gemspec name and version
     def self.all_combined_pins_in_memory
       @combined_pins_in_memory ||= {}
     end
 
+    # @todo this should also include an index by the hash of the RBS collection
+    # @return [Hash{Array(String, String) => Array<Pin::Base>}] Indexed by gemspec name and version
     def combined_pins_in_memory
       self.class.all_combined_pins_in_memory
     end
 
+    # @return [Array<String>]
+    def yard_plugins
+      @environ.yard_plugins
+    end
+
     # @return [Set<Gem::Specification>]
     def dependencies
       @dependencies ||= (gemspecs.flat_map { |spec| fetch_dependencies(spec) } - gemspecs).to_set
@@ -149,7 +177,11 @@ module Solargraph
       @uncached_yard_gemspecs = []
       @uncached_rbs_collection_gemspecs = []
       with_gemspecs, without_gemspecs = required_gems_map.partition { |_, v| v }
+      # @sg-ignore Wrong argument type for Hash.[]: arg_0 expected _ToHash<Array(String, Array<Gem::Specification>), undefined>, received Array<Array(String, Array<Gem::Specification>)>
+      # @type [Array<String>]
       paths = Hash[without_gemspecs].keys
+      # @sg-ignore Wrong argument type for Hash.[]: arg_0 expected _ToHash<Array(String, Array<Gem::Specification>), undefined>, received Array<Array(String, Array<Gem::Specification>)>
+      # @type [Array<Gem::Specification>]
       gemspecs = Hash[with_gemspecs].values.flatten.compact + dependencies.to_a
 
       paths.each do |path|
@@ -258,6 +290,8 @@ module Solargraph
       end
     end
 
+    # @param gemspec [Gem::Specification]
+    # @param rbs_version_cache_key [String]
     # @return [Array<Pin::Base>, nil]
     def deserialize_rbs_collection_cache gemspec, rbs_version_cache_key
       return if rbs_collection_pins_in_memory.key?([gemspec, rbs_version_cache_key])
@@ -273,22 +307,13 @@ module Solargraph
       end
     end
 
-    # @param gemspec [Gem::Specification]
-    # @return [Boolean]
-    def try_gem_in_memory gemspec
-      gempins = DocMap.gems_in_memory[gemspec]
-      return false unless gempins
-      Solargraph.logger.debug "Found #{gemspec.name} #{gemspec.version} in memory"
-      @pins.concat gempins
-      true
-    end
-
     # @param path [String]
     # @return [::Array<Gem::Specification>, nil]
     def resolve_path_to_gemspecs path
       return nil if path.empty?
       return gemspecs_required_from_bundler if path == 'bundler/require'
 
+      # @type [Gem::Specification, nil]
       gemspec = Gem::Specification.find_by_path(path)
       if gemspec.nil?
         gem_name_guess = path.split('/').first
@@ -312,10 +337,12 @@ module Solargraph
     # @param gemspec [Gem::Specification]
     # @return [Gem::Specification]
     def gemspec_or_preference gemspec
+      # :nocov: dormant feature
       return gemspec unless preference_map.key?(gemspec.name)
       return gemspec if gemspec.version == preference_map[gemspec.name].version
 
-      change_gemspec_version gemspec, preference_map[by_path.name].version
+      change_gemspec_version gemspec, preference_map[gemspec.name].version
+      # :nocov:
     end
 
     # @param gemspec [Gem::Specification]
@@ -354,8 +381,12 @@ module Solargraph
       self.class.inspect
     end
 
+    # @return [Array<Gem::Specification>]
     def gemspecs_required_from_bundler
-      if workspace&.directory && Bundler.definition&.lockfile&.to_s&.start_with?(workspace.directory)
+      # @todo Handle projects with custom Bundler/Gemfile setups
+      return unless workspace.gemfile?
+
+      if workspace.gemfile? && Bundler.definition&.lockfile&.to_s&.start_with?(workspace.directory)
         # Find only the gems bundler is now using
         Bundler.definition.locked_gems.specs.flat_map do |lazy_spec|
           logger.info "Handling #{lazy_spec.name}:#{lazy_spec.version}"
@@ -373,6 +404,7 @@ module Solargraph
       end
     end
 
+    # @return [Array<Gem::Specification>]
     def gemspecs_required_from_external_bundle
       logger.info 'Fetching gemspecs required from external bundle'
       return [] unless workspace&.directory
@@ -396,8 +428,7 @@ module Solargraph
             next specs
           end.compact
         else
-          Solargraph.logger.warn e
-          raise BundleNotFoundError, "Failed to load gems from bundle at #{workspace&.directory}"
+          Solargraph.logger.warn "Failed to load gems from bundle at #{workspace&.directory}: #{e}"
         end
       end
     end

data/lib/solargraph/environ.rb

@@ -13,16 +13,21 @@ module Solargraph
     # @return [Array<String>]
     attr_reader :domains
 
-    # @return [Array<Pin::Reference::Override>]
+    # @return [Array<Pin::Base>]
     attr_reader :pins
 
+    # @return [Array<String>]
+    attr_reader :yard_plugins
+
     # @param requires [Array<String>]
     # @param domains [Array<String>]
     # @param pins [Array<Pin::Base>]
-    def initialize requires: [], domains: [], pins: []
+    # @param yard_plugins[Array<String>]
+    def initialize requires: [], domains: [], pins: [], yard_plugins: []
       @requires = requires
       @domains = domains
       @pins = pins
+      @yard_plugins = yard_plugins
     end
 
     # @return [self]
@@ -30,6 +35,7 @@ module Solargraph
       domains.clear
       requires.clear
       pins.clear
+      yard_plugins.clear
       self
     end
 
@@ -39,6 +45,7 @@ module Solargraph
       domains.concat other.domains
       requires.concat other.requires
       pins.concat other.pins
+      yard_plugins.concat other.yard_plugins
       self
     end
   end

data/lib/solargraph/gem_pins.rb

@@ -11,17 +11,9 @@ module Solargraph
       include Logging
     end
 
-    # @param gemspec [Gem::Specification]
-    # @return [Array<Pin::Base>]
-    def self.build_yard_pins(gemspec)
-      Yardoc.cache(gemspec) unless Yardoc.cached?(gemspec)
-      yardoc = Yardoc.load!(gemspec)
-      YardMap::Mapper.new(yardoc, gemspec).map
-    end
-
     # @param pins [Array<Pin::Base>]
+    # @return [Array<Pin::Base>]
     def self.combine_method_pins_by_path(pins)
-      # bad_pins = pins.select { |pin| pin.is_a?(Pin::Method) && pin.path == 'StringIO.open' && pin.source == :rbs }; raise "wtf: #{bad_pins}" if bad_pins.length > 1
       method_pins, alias_pins = pins.partition { |pin| pin.class == Pin::Method }
       by_path = method_pins.group_by(&:path)
       by_path.transform_values! do |pins|
@@ -30,8 +22,12 @@ module Solargraph
       by_path.values + alias_pins
     end
 
+    # @param pins [Array<Pin::Method>]
+    # @return [Pin::Method, nil]
     def self.combine_method_pins(*pins)
-      out = pins.reduce(nil) do |memo, pin|
+      # @type [Pin::Method, nil]
+      combined_pin = nil
+      out = pins.reduce(combined_pin) do |memo, pin|
         next pin if memo.nil?
         if memo == pin && memo.source != :combined
           # @todo we should track down situations where we are handled
@@ -45,8 +41,18 @@ module Solargraph
       out
     end
 
+    # @param yard_plugins [Array<String>] The names of YARD plugins to use.
+    # @param gemspec [Gem::Specification]
+    # @return [Array<Pin::Base>]
+    def self.build_yard_pins(yard_plugins, gemspec)
+      Yardoc.cache(yard_plugins, gemspec) unless Yardoc.cached?(gemspec)
+      yardoc = Yardoc.load!(gemspec)
+      YardMap::Mapper.new(yardoc, gemspec).map
+    end
+
     # @param yard_pins [Array<Pin::Base>]
-    # @param rbs_map [RbsMap]
+    # @param rbs_pins [Array<Pin::Base>]
+    #
     # @return [Array<Pin::Base>]
     def self.combine(yard_pins, rbs_pins)
       in_yard = Set.new

data/lib/solargraph/language_server/host/dispatch.rb

@@ -95,6 +95,7 @@ module Solargraph
           nil
         end
 
+        # @return [Hash{String => undefined}]
         def options
           @options ||= {}.freeze
         end
@@ -118,6 +119,7 @@ module Solargraph
         end
 
         # @param library [Solargraph::Library]
+        # @param progress [Solargraph::LanguageServer::Progress, nil]
         # @return [void]
         def update progress
           progress&.send(self)

data/lib/solargraph/language_server/host/message_worker.rb

@@ -72,10 +72,12 @@ module Solargraph
 
         private
 
+        # @return [Hash, nil]
         def next_message
           cancel_message || next_priority
         end
 
+        # @return [Hash, nil]
         def cancel_message
           # Handle cancellations first
           idx = messages.find_index { |msg| msg['method'] == '$/cancelRequest' }
@@ -86,6 +88,7 @@ module Solargraph
           msg
         end
 
+        # @return [Hash, nil]
         def next_priority
           # Prioritize updates and version-dependent messages for performance
           idx = messages.find_index do |msg|

data/lib/solargraph/language_server/host.rb

@@ -299,6 +299,7 @@ module Solargraph
         end
       end
 
+      # @return [String]
       def command_path
         options['commandPath'] || 'solargraph'
       end
@@ -716,7 +717,7 @@ module Solargraph
       # A hash of client requests by ID. The host uses this to keep track of
       # pending responses.
       #
-      # @return [Hash{Integer => Solargraph::LanguageServer::Host}]
+      # @return [Hash{Integer => Solargraph::LanguageServer::Request}]
       def requests
         @requests ||= {}
       end

data/lib/solargraph/language_server/message/base.rb

@@ -16,7 +16,7 @@ module Solargraph
         # @return [String]
         attr_reader :method
 
-        # @return [Hash{String => Array<undefined>, Hash{String => undefined}, String, Integer}]
+        # @return [Hash{String => undefined}]
         attr_reader :params
 
         # @return [Hash, Array, nil]
@@ -79,6 +79,7 @@ module Solargraph
 
         private
 
+        # @return [void]
         def accept_or_cancel
           if host.cancel?(id)
             # https://microsoft.github.io/language-server-protocol/specifications/specification-current/#cancelRequest

data/lib/solargraph/language_server/message/extended/check_gem_version.rb

@@ -83,7 +83,7 @@ module Solargraph
               @fetched = true
               begin
                 @available ||= begin
-                  # @sg-ignore
+                  # @sg-ignore Variable type could not be inferred for tuple
                   # @type [Gem::Dependency, nil]
                   tuple = CheckGemVersion.fetcher.search_for_dependency(Gem::Dependency.new('solargraph')).flatten.first
                   if tuple.nil?

data/lib/solargraph/language_server/message/text_document/definition.rb

@@ -10,6 +10,7 @@ module Solargraph::LanguageServer::Message::TextDocument
 
     private
 
+    # @return [Array<Hash>]
     def code_location
       suggestions = host.definitions_at(params['textDocument']['uri'], @line, @column)
       return nil if suggestions.empty?
@@ -21,6 +22,7 @@ module Solargraph::LanguageServer::Message::TextDocument
       end
     end
 
+    # @return [Array<Hash>]
     def require_location
       # @todo Terrible hack
       lib = host.library_for(params['textDocument']['uri'])