yard 0.9.5 → 0.9.6

data/lib/yard/server/commands/list_command.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module YARD
   module Server
     module Commands

data/lib/yard/server/commands/root_request_command.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module YARD
   module Server
     module Commands

data/lib/yard/server/commands/search_command.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module YARD
   module Server
     module Commands
@@ -14,9 +15,10 @@ module YARD
           Registry.load_all
           self.query = request.query['q']
           redirect(abs_url(adapter.router.docs_prefix, single_library ? library : '')) if query.nil? || query =~ /\A\s*\Z/
-          if found = Registry.at(query)
-            redirect(url_for(found))
-          end
+
+          found = Registry.at(query)
+          redirect(url_for(found)) if found
+
           search_for_object
           request.xhr? ? serve_xhr : serve_normal
         end
@@ -33,13 +35,12 @@ module YARD
         end
 
         def serve_xhr
-          self.headers['Content-Type'] = 'text/plain'
+          headers['Content-Type'] = 'text/plain'
           self.body = visible_results.map {|o|
             [(o.type == :method ? o.name(true) : o.name).to_s,
              o.path,
              o.namespace.root? ? '' : o.namespace.path,
-             url_for(o)
-            ].join(",")
+             url_for(o)].join(",")
           }.join("\n")
         end
 
@@ -55,22 +56,22 @@ module YARD
         end
 
         def search_for_object
-          splitquery = query.split(/\s+/).map {|c| c.downcase }.reject {|m| m.empty? }
-          self.results = run_verifier(Registry.all).select {|o|
-              o.path.downcase.include?(query.downcase)
-            }.reject {|o|
-              name = (o.type == :method ? o.name(true) : o.name).to_s.downcase
-              !name.include?(query.downcase) ||
+          # rubocop:disable Style/MultilineBlockChain
+          self.results = run_verifier(Registry.all).select do |o|
+            o.path.downcase.include?(query.downcase)
+          end.reject do |o|
+            name = (o.type == :method ? o.name(true) : o.name).to_s.downcase
+            !name.include?(query.downcase) ||
               case o.type
               when :method
                 !(query =~ /[#.]/) && query.include?("::")
               when :class, :module, :constant, :class_variable
                 query =~ /[#.]/
               end
-            }.sort_by {|o|
-              name = (o.type == :method ? o.name(true) : o.name).to_s
-              name.length.to_f / query.length.to_f
-            }
+          end.sort_by do |o|
+            name = (o.type == :method ? o.name(true) : o.name).to_s
+            name.length.to_f / query.length.to_f
+          end
         end
       end
     end

data/lib/yard/server/commands/static_file_command.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module YARD
   module Server
     module Commands
@@ -19,4 +20,4 @@ module YARD
       end
     end
   end
-end
+end

data/lib/yard/server/commands/static_file_helpers.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'webrick/httputils'
 
 module YARD
@@ -7,13 +8,13 @@ module YARD
       # and {favicon?} helpers.
       module StaticFileHelpers
         include WEBrick::HTTPUtils
-        
+
         # Serves an empty favicon.
         # @raise [FinishRequest] finalizes an empty body if the path matches
         #   /favicon.ico so browsers don't complain.
         def favicon?
           return unless request.path == '/favicon.ico'
-          self.headers['Content-Type'] = 'image/png'
+          headers['Content-Type'] = 'image/png'
           self.status = 200
           self.body = ''
           raise FinishRequest
@@ -24,28 +25,36 @@ module YARD
         # @raise [FinishRequest] if a file was found and served
         # @return [void]
         def static_template_file?
-          # these consts were defined in StaticFileCommand originally 
-          static_paths = StaticFileCommand::STATIC_PATHS
+          # this const was defined in StaticFileCommand originally
           default_mime_types = StaticFileCommand::DefaultMimeTypes
 
-          assets_template = Templates::Engine.template(:default, :fulldoc, :html)
+          file = find_file(adapter, path)
+
+          if file
+            ext = "." + (path[/\.(\w+)$/, 1] || "html")
+            headers['Content-Type'] = mime_type(ext, default_mime_types)
+            self.body = File.read(file)
+            raise FinishRequest
+          end
+        end
+
+        module_function
+
+        def find_file(adapter, url)
+          # this const was defined in StaticFileCommand originally
+          static_paths = StaticFileCommand::STATIC_PATHS
 
           file = nil
           ([adapter.document_root] + static_paths.reverse).compact.each do |path_prefix|
-            file = File.join(path_prefix, path)
+            file = File.join(path_prefix, url)
+            p file
             break if File.exist?(file)
             file = nil
           end
 
           # Search in default/fulldoc/html template if nothing in static asset paths
-          file ||= assets_template.find_file(path)
-
-          if file
-            ext = "." + (path[/\.(\w+)$/, 1] || "html")
-            headers['Content-Type'] = mime_type(ext, default_mime_types)
-            self.body = File.read(file)
-            raise FinishRequest
-          end
+          assets_template = Templates::Engine.template(:default, :fulldoc, :html)
+          file || assets_template.find_file(url)
         end
       end
     end

data/lib/yard/server/doc_server_helper.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module YARD
   module Server
     # A module that is mixed into {Templates::Template} in order to customize
@@ -7,7 +8,7 @@ module YARD
       # of a disk location.
       # @param (see Templates::Helpers::HtmlHelper#url_for)
       # @return (see Templates::Helpers::HtmlHelper#url_for)
-      def url_for(obj, anchor = nil, relative = false)
+      def url_for(obj, anchor = nil, relative = false) # rubocop:disable Lint/UnusedMethodArgument
         return '' if obj.nil?
         return url_for_index if obj == '_index.html'
         return abs_url(base_path(router.static_prefix), obj) if String === obj
@@ -72,6 +73,19 @@ module YARD
 
       # @return [Router] convenience method for accessing the router
       def router; @adapter.router end
+
+      # @return [String] a timestamp for a given file
+      def mtime(file)
+        file = YARD::Server::Commands::StaticFileHelpers.find_file(@adapter, file)
+        file ? File.mtime(file).to_i : nil
+      end
+
+      # @return [String] a URL for a file with a timestamp
+      def mtime_url(file)
+        url = url_for(file)
+        time = mtime(file)
+        url + (time ? "?#{time}" : "")
+      end
     end
   end
 end

data/lib/yard/server/doc_server_serializer.rb

@@ -1,11 +1,10 @@
-require 'cgi'
-
+# frozen_string_literal: true
 module YARD
   module Server
     # A custom {Serializers::Base serializer} which returns resource URLs instead of
     # static relative paths to files on disk.
     class DocServerSerializer < Serializers::FileSystemSerializer
-      def initialize(command = nil)
+      def initialize(_command = nil)
         super(:basepath => '', :extension => '')
       end
 
@@ -14,7 +13,6 @@ module YARD
         when CodeObjects::RootObject
           "toplevel"
         when CodeObjects::ExtendedMethodObject
-          name = object.name.to_s
           serialized_path(object.namespace) + ':' + urlencode(object.name.to_s)
         when CodeObjects::MethodObject
           serialized_path(object.namespace) +
@@ -34,7 +32,7 @@ module YARD
         if name.respond_to?(:force_encoding)
           name = name.dup.force_encoding('binary')
         end
-        CGI.escape(name)
+        Templates::Helpers::HtmlHelper.urlencode(name)
       end
     end
   end

data/lib/yard/server/library_version.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'fileutils'
 require 'thread'
 
@@ -49,37 +50,42 @@ module YARD
     # YARD can be extended to support custom library sources in order to
     # build or retrieve a yardoc file at runtime from many different locations.
     #
-    # To implement this behaviour, two methods must be added to the +LibraryVersion+
-    # class, +#load_yardoc_from_SOURCE+ and +#source_path_for_SOURCE+. In both
-    # cases, "SOURCE" represents the source type used in {#source} when creating
-    # the library object. The +#source_path_for_SOURCE+ method is called upon
+    # To implement this behaviour, 3 methods can be added to the +LibraryVersion+
+    # class, +#load_yardoc_from_SOURCE+, +#yardoc_file_for_SOURCE+, and
+    # +#source_path_for_SOURCE+. In all cases, "SOURCE" represents the source
+    # type used in {#source} when creating the library object. The
+    # +#yardoc_file_for_SOURCE+ and +#source_path_for_SOURCE+ methods are called upon
     # creation and should return the location where the source code for the library
     # lives. The load method is called from {#prepare!} if there is no yardoc file
     # and should set {#yardoc_file}. Below is a full example for
     # implementing a custom library source, +:http+, which reads packaged .yardoc
     # databases from zipped archives off of an HTTP server.
     #
+    # Note that only +#load_yardoc_from_SOURCE+ is required. The other two
+    # methods are optional and can be set manually (via {#source_path=} and
+    # {#yardoc_file=}) on the object at any time.
+    #
     # @example Implementing a Custom Library Source
     #   # Adds the source type "http" for .yardoc files zipped on HTTP servers
     #   class LibraryVersion
     #     def load_yardoc_from_http
-    #       return if yardoc_file # we have the library
-    #
-    #       # otherwise download it in a thread and return immediately
     #       Thread.new do
     #         # zip/unzip method implementations are not shown
     #         download_zip_file("http://mysite.com/yardocs/#{self}.zip")
     #         unzip_file_to("/path/to/yardocs/#{self}")
-    #         self.yardoc_file = "/path/to/yardocs/#{self}/.yardoc"
-    #         self.source_path = self.yardoc_file
     #       end
     #
     #       # tell the server it's not ready yet (but it might be next time)
     #       raise LibraryNotPreparedError
     #     end
     #
-    #     # we set this later
-    #     def source_path_for_http; nil end
+    #     def yardoc_file_for_http
+    #       "/path/to/yardocs/#{self}/.yardoc"
+    #     end
+    #
+    #     def source_path_for_http
+    #       File.dirname(yardoc_file)
+    #     end
     #   end
     #
     #   # Creating a library of this source type:
@@ -96,7 +102,11 @@ module YARD
       #   information from.
       # @return [nil] if no yardoc file exists yet. In this case, {#prepare!} will
       #   be called on this library to build the yardoc file.
-      attr_accessor :yardoc_file
+      # @note To implement a custom yardoc file getter, implement
+      def yardoc_file
+        @yardoc_file ||= load_yardoc_file
+      end
+      attr_writer :yardoc_file
 
       # @return [Symbol] the source type representing where the yardoc should be
       #   loaded from. Defaults are +:disk+ and +:gem+, though custom sources
@@ -109,7 +119,10 @@ module YARD
       #   value is filled by calling +#source_path_for_SOURCE+ on this class.
       # @return [nil] if there is no source code
       # @see LibraryVersion LibraryVersion documentation for "Implementing a Custom Library Source"
-      attr_accessor :source_path
+      def source_path
+        @source_path ||= load_source_path
+      end
+      attr_writer :source_path
 
       # @param [String] name the name of the library
       # @param [String] version the specific (usually, but not always, numeric) library
@@ -123,7 +136,6 @@ module YARD
         self.yardoc_file = yardoc
         self.version = version
         self.source = source
-        self.source_path = load_source_path
       end
 
       # @param [Boolean] url_format if true, returns the string in a URI-compatible
@@ -131,7 +143,7 @@ module YARD
       #   readable format.
       # @return [String] the string representation of the library.
       def to_s(url_format = true)
-        version ? "#{name}#{url_format ? '/' : '-'}#{version}" : "#{name}"
+        version ? "#{name}#{url_format ? '/' : '-'}#{version}" : name.to_s
       end
 
       # @return [Fixnum] used for Hash mapping.
@@ -178,7 +190,7 @@ module YARD
       # @return [nil] if there is no installed gem for the library
       def gemspec
         ver = version ? "= #{version}" : ">= 0"
-        Gem.source_index.find_name(name, ver).last
+        YARD::GemIndex.find_all_by_name(name, ver).last
       end
 
       protected
@@ -212,17 +224,15 @@ module YARD
       # @raise [LibraryNotPreparedError] if the gem does not have an existing
       #   yardoc file.
       def load_yardoc_from_gem
-        require 'rubygems'
-        ver = version ? "= #{version}" : ">= 0"
-        self.yardoc_file = Registry.yardoc_file_for_gem(name, ver)
         return if ready?
+        ver = version ? "= #{version}" : ">= 0"
 
         @@chdir_mutex.synchronize do
           Thread.new do
             # Build gem docs on demand
             log.debug "Building gem docs for #{to_s(false)}"
             CLI::Gems.run(name, ver)
-            self.yardoc_file = Registry.yardoc_file_for_gem(name, ver)
+            log.debug "Done building gem docs for #{to_s(false)}"
           end
         end
 
@@ -239,6 +249,13 @@ module YARD
         gemspec.full_gem_path if gemspec
       end
 
+      # @return [String] the yardoc file for a gem source
+      def yardoc_file_for_gem
+        require 'rubygems'
+        ver = version ? "= #{version}" : ">= 0"
+        Registry.yardoc_file_for_gem(name, ver)
+      end
+
       private
 
       def load_source_path
@@ -246,10 +263,15 @@ module YARD
         send(meth) if respond_to?(meth, true)
       end
 
+      def load_yardoc_file
+        meth = "yardoc_file_for_#{source}"
+        send(meth) if respond_to?(meth, true)
+      end
+
       def serializer
         return if yardoc_file.nil?
-        @serializer ||= Serializers::YardocSerializer.new(yardoc_file)
+        Serializers::YardocSerializer.new(yardoc_file)
       end
     end
   end
-end
+end

data/lib/yard/server/rack_adapter.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'rack'
 require 'webrick/httputils'
 
@@ -84,5 +85,5 @@ end
 class Rack::Request
   attr_accessor :version_supplied
   alias query params
-  def xhr?; (env['HTTP_X_REQUESTED_WITH'] || "").downcase == "xmlhttprequest" end
+  def xhr?; (env['HTTP_X_REQUESTED_WITH'] || "").casecmp("xmlhttprequest") == 0 end
 end

data/lib/yard/server/router.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module YARD
   module Server
     # A router class implements the logic used to recognize a request for a specific
@@ -52,11 +53,8 @@ module YARD
       # @return [Array(Numeric,Hash,Array)] the Rack-style server response data
       def call(request)
         self.request = request
-        if result = (check_static_cache || route)
-          result
-        else
-          RootRequestCommand.new(adapter.options).call(request)
-        end
+        result = check_static_cache || route
+        result ? result : RootRequestCommand.new(adapter.options).call(request)
       end
 
       # @group Route Prefixes
@@ -80,10 +78,13 @@ module YARD
       #   will be nil if no matching library was found.
       def parse_library_from_path(paths)
         return [adapter.libraries.values.first.first, paths] if adapter.options[:single_library]
-        library, paths = nil, paths.dup
-        if libs = adapter.libraries[paths.first]
+        library = nil
+        paths = paths.dup
+        libs = adapter.libraries[paths.first]
+        if libs
           paths.shift
-          if library = libs.find {|l| l.version == paths.first }
+          library = libs.find {|l| l.version == paths.first }
+          if library
             request.version_supplied = true if request
             paths.shift
           else # use the last lib in the list
@@ -105,17 +106,17 @@ module YARD
         path = path.gsub(%r{//+}, '/').gsub(%r{^/|/$}, '')
         return route_index if path.empty? || path == docs_prefix
         case path
-        when /^(#{docs_prefix}|#{list_prefix}|#{search_prefix}|#{static_prefix})(\/.*|$)/
+        when %r{^(#{docs_prefix}|#{list_prefix}|#{search_prefix}|#{static_prefix})(/.*|$)}
           prefix = $1
           paths = $2.gsub(%r{^/|/$}, '').split('/')
           library, paths = *parse_library_from_path(paths)
           return unless library
           return case prefix
-          when docs_prefix;   route_docs(library, paths)
-          when list_prefix;   route_list(library, paths)
-          when search_prefix; route_search(library, paths)
-          when static_prefix; route_static(library, paths)
-          end
+                 when docs_prefix;   route_docs(library, paths)
+                 when list_prefix;   route_list(library, paths)
+                 when search_prefix; route_search(library, paths)
+                 when static_prefix; route_static(library, paths)
+                 end
         end
         nil
       end