yard 0.7.5 → 0.8.0

data/lib/yard/cli/list.rb

@@ -3,7 +3,7 @@ module YARD
     # Lists all constant and method names in the codebase. Uses {Yardoc} --list.
     class List < Command
       def description; 'Lists all constant and methods. Uses `yard doc --list`' end
-      
+
       # Runs the commandline utility, parsing arguments and displaying a
       # list of objects
       #

data/lib/yard/cli/server.rb

@@ -23,11 +23,9 @@ module YARD
       # @since 0.6.2
       attr_accessor :template_paths
 
-      def description
-        "Runs a local documentation server"
-      end
-
-      def run(*args)
+      # Creates a new instance of the Server command line utility
+      def initialize
+        super
         self.scripts = []
         self.template_paths = []
         self.libraries = {}
@@ -36,6 +34,13 @@ module YARD
           :caching => false
         )
         self.server_options = {:Port => 8808}
+      end
+
+      def description
+        "Runs a local documentation server"
+      end
+
+      def run(*args)
         optparse(*args)
 
         select_adapter.setup
@@ -71,7 +76,7 @@ module YARD
           yardoc = File.expand_path(yardoc)
           if File.exist?(yardoc)
             libraries[library] ||= []
-            libraries[library] << YARD::Server::LibraryVersion.new(library, nil, yardoc)
+            libraries[library] |= [YARD::Server::LibraryVersion.new(library, nil, yardoc)]
           else
             log.warn "Cannot find yardoc db for #{library}: #{yardoc}"
           end
@@ -82,10 +87,25 @@ module YARD
         require 'rubygems'
         Gem.source_index.find_name('').each do |spec|
           libraries[spec.name] ||= []
-          libraries[spec.name] << YARD::Server::LibraryVersion.new(spec.name, spec.version.to_s, nil, :gem)
+          libraries[spec.name] |= [YARD::Server::LibraryVersion.new(spec.name, spec.version.to_s, nil, :gem)]
         end
       end
 
+      def add_gems_from_gemfile(gemfile = nil)
+        require 'bundler'
+        gemfile ||= "Gemfile"
+        if File.exists?("#{gemfile}.lock")
+          Bundler::LockfileParser.new(File.read("#{gemfile}.lock")).specs.each do |spec|
+            libraries[spec.name] ||= []
+            libraries[spec.name] |= [YARD::Server::LibraryVersion.new(spec.name, spec.version.to_s, nil, :gem)]
+          end
+        else
+          log.warn "Cannot find #{gemfile}.lock, ignoring --gemfile option"
+        end
+      rescue LoadError
+        log.error "Bundler not available, ignoring --gemfile option"
+      end
+
       def optparse(*args)
         opts = OptionParser.new
         opts.banner = 'Usage: yard server [options] [[library yardoc_file] ...]'
@@ -109,6 +129,9 @@ module YARD
         opts.on('-g', '--gems', 'Serves documentation for installed gems') do
           add_gems
         end
+        opts.on('-G', '--gemfile [GEMFILE]', 'Serves documentation for gems from Gemfile') do |gemfile|
+          add_gems_from_gemfile(gemfile)
+        end
         opts.on('-t', '--template-path PATH',
                 'The template path to look for templates in. (used with -t).') do |path|
           self.template_paths << path

data/lib/yard/cli/stats.rb

@@ -33,11 +33,9 @@ module YARD
       def run(*args)
         parse_arguments(*args)
 
-        if parse
-          if use_cache
-            Registry.load!
-            checksums = Registry.checksums.dup
-          end
+        if use_cache
+          Registry.load!
+        elsif parse
           YARD.parse(files, excluded)
           Registry.save(use_cache) if save_yardoc
         end
@@ -75,7 +73,8 @@ module YARD
         max = objects.sort_by {|o| o.path.length }.last.path.length
         if @compact
           objects.each do |object|
-            puts("%-#{max}s     (%s)" % [object.path, object.file])
+            puts("%-#{max}s     (%s)" % [object.path,
+              [object.file, object.line].compact.join(":")])
           end
         else
           last_file = nil

data/lib/yard/cli/yardoc.rb

@@ -3,6 +3,50 @@ require 'fileutils'
 
 module YARD
   module CLI
+    # Default options used in +yard doc+ command.
+    class YardocOptions < Templates::TemplateOptions
+      # @return [Array<CodeObjects::ExtraFileObject>]
+      #   the list of extra files rendered along with objects
+      default_attr :files, lambda { [] }
+
+      # @return [String] the default title appended to each generated page
+      default_attr :title, "Documentation by YARD #{YARD::VERSION}"
+
+      # @return [Verifier] the default verifier object to filter queries
+      default_attr :verifier, lambda { Verifier.new }
+
+      # @return [Serializers::Base] the default serializer for generating output
+      #   to disk.
+      default_attr :serializer, lambda { Serializers::FileSystemSerializer.new }
+
+      # @return [Symbol] the default output format (:html).
+      default_attr :format, :html
+
+      # @return [Boolean] whether the data should be rendered in a single page,
+      #   if the template supports it.
+      default_attr :onefile, false
+
+      # @return [CodeObjects::ExtraFileObject] the README file object rendered
+      #   along with objects
+      attr_accessor :readme
+
+      # @return [Array<CodeObjects::Base>] the list of code objects to render
+      #   the templates with.
+      attr_accessor :objects
+
+      # @return [Numeric] An index value for rendering sequentially related templates
+      attr_accessor :index
+
+      # @return [CodeObjects::Base] an extra item to send to a template that is not
+      #   the main rendered object
+      attr_accessor :item
+
+      # @return [CodeObjects::ExtraFileObject] the file object being rendered.
+      #   The +object+ key is not used so that a file may be rendered in the context
+      #   of an object's namespace (for generating links).
+      attr_accessor :file
+    end
+
     # Yardoc is the default YARD CLI command (+yard doc+ and historic +yardoc+
     # executable) used to generate and output (mainly) HTML documentation given
     # a set of source files.
@@ -150,7 +194,7 @@ module YARD
       # @return [Array<String>] a list of assets to copy after generation
       # @since 0.6.0
       attr_accessor :assets
-      
+
       # @return [Boolean] whether markup option was specified
       # @since 0.7.0
       attr_accessor :has_markup
@@ -158,19 +202,8 @@ module YARD
       # Creates a new instance of the commandline utility
       def initialize
         super
-        @options = SymbolHash.new(false)
-        @options.update(
-          :format => :html,
-          :template => :default,
-          :markup => :rdoc, # default is :rdoc but falls back on :none
-          :serializer => YARD::Serializers::FileSystemSerializer.new,
-          :default_return => "Object",
-          :hide_void_return => false,
-          :no_highlight => false,
-          :files => [],
-          :title => "Documentation by YARD #{YARD::VERSION}",
-          :verifier => Verifier.new
-        )
+        @options = YardocOptions.new
+        @options.reset_defaults
         @visibilities = [:public]
         @assets = {}
         @excluded = []
@@ -248,13 +281,21 @@ module YARD
         self.files = ['{lib,app}/**/*.rb', 'ext/**/*.c'] if self.files.empty?
         self.files.delete_if {|x| x =~ /\A\s*\Z/ } # remove empty ones
         readme = Dir.glob('README*').first
-        readme ||= Dir.glob(files.first).first if options[:onefile]
-        options[:readme] ||= CodeObjects::ExtraFileObject.new(readme) if readme
-        options[:files].unshift(options[:readme]).uniq! if options[:readme]
+        readme ||= Dir.glob(files.first).first if options.onefile
+        options.readme ||= CodeObjects::ExtraFileObject.new(readme) if readme
+        options.files.unshift(options.readme).uniq! if options.readme
 
         Tags::Library.visible_tags -= hidden_tags
         add_visibility_verifier
 
+        # US-ASCII is invalid encoding for onefile
+        if defined?(::Encoding) && options.onefile
+          if ::Encoding.default_internal == ::Encoding::US_ASCII
+            log.warn "--one-file is not compatible with US-ASCII encoding, using ASCII-8BIT"
+            ::Encoding.default_external, ::Encoding.default_internal = ['ascii-8bit'] * 2
+          end
+        end
+
         if generate && !verify_markup_options
           false
         else
@@ -295,7 +336,7 @@ module YARD
         end
         Registry.load_all if use_cache
         objects = run_verifier(all_objects).reject do |object|
-          serialized = !options[:serializer] || options[:serializer].exists?(object)
+          serialized = !options.serializer || options.serializer.exists?(object)
           if checksums && serialized && !object.files.any? {|f, line| changed_files.include?(f) }
             true
           else
@@ -314,17 +355,17 @@ module YARD
         result, lvl = false, has_markup ? log.level : Logger::FATAL
         obj = Struct.new(:options).new(options)
         obj.extend(Templates::Helpers::MarkupHelper)
-        options[:files].each do |file|
+        options.files.each do |file|
           markup = file.attributes[:markup] || obj.markup_for_file('', file.filename)
           result = obj.load_markup_provider(markup)
           return false if !result && markup != :rdoc
         end
-        options[:markup] = :rdoc unless has_markup
+        options.markup = :rdoc unless has_markup
         log.enter_level(lvl) { result = obj.load_markup_provider }
         if !result && !has_markup
           log.warn "Could not load default RDoc formatter, " +
             "ignoring any markup (install RDoc to get default formatting)."
-          options[:markup] = :none
+          options.markup = :none
           true
         else
           result
@@ -335,8 +376,8 @@ module YARD
       # @return [void]
       # @since 0.6.0
       def copy_assets
-        return unless options[:serializer]
-        outpath = options[:serializer].basepath
+        return unless options.serializer
+        outpath = options.serializer.basepath
         assets.each do |from, to|
           to = File.join(outpath, to)
           log.debug "Copying asset '#{from}' to '#{to}'"
@@ -355,7 +396,7 @@ module YARD
           puts "#{item.file}:#{item.line}: #{item.path}"
         end
       end
-      
+
       # Parses out the yardopts/document options
       def parse_yardopts_options(*args)
         opts = OptionParser.new
@@ -386,7 +427,7 @@ module YARD
         files.map! {|f| f.include?("*") ? Dir.glob(f) : f }.flatten!
         files.each do |file|
           if File.file?(file)
-            options[:files] << CodeObjects::ExtraFileObject.new(file)
+            options.files << CodeObjects::ExtraFileObject.new(file)
           else
             log.warn "Could not find extra file: #{file}"
           end
@@ -424,12 +465,12 @@ module YARD
       # @since 0.5.6
       def add_visibility_verifier
         vis_expr = "object.type != :method || #{visibilities.uniq.inspect}.include?(object.visibility)"
-        options[:verifier].add_expressions(vis_expr)
+        options.verifier.add_expressions(vis_expr)
       end
 
       # (see Templates::Helpers::BaseHelper#run_verifier)
       def run_verifier(list)
-        options[:verifier] ? options[:verifier].run(list) : list
+        options.verifier ? options.verifier.run(list) : list
       end
 
       # @since 0.6.0
@@ -506,10 +547,10 @@ module YARD
           self.excluded << path
         end
       end
-      
+
       # Adds --[no-]yardopts / --[no-]document
       def yardopts_options(opts)
-        opts.on('--[no-]yardopts [FILE]', 
+        opts.on('--[no-]yardopts [FILE]',
                 "If arguments should be read from FILE",
                 "  (defaults to yes, FILE defaults to .yardopts)") do |use_yardopts|
           if use_yardopts.is_a?(String)
@@ -532,7 +573,7 @@ module YARD
         opts.separator "Output options:"
 
         opts.on('--one-file', 'Generates output as a single file') do
-          options[:onefile] = true
+          options.onefile = true
         end
 
         opts.on('--list', 'List objects to standard out (implies -n)') do |format|
@@ -553,37 +594,46 @@ module YARD
         end
 
         opts.on('--no-private', "Hide objects with @private tag") do
-          options[:verifier].add_expressions '!object.tag(:private) &&
+          options.verifier.add_expressions '!object.tag(:private) &&
             (object.namespace.is_a?(CodeObjects::Proxy) || !object.namespace.tag(:private))'
         end
 
+        opts.on('--embed-mixins', "Embeds mixin methods into class documentation") do
+          options.embed_mixins << '*'
+        end
+
+        opts.on('--embed-mixin [MODULE]', "Embeds mixin methods from a particular",
+                                          " module into class documentation") do |mod|
+          options.embed_mixins << mod
+        end
+
         opts.on('--no-highlight', "Don't highlight code blocks in output.") do
-          options[:no_highlight] = true
+          options.highlight = false
         end
 
         opts.on('--default-return TYPE', "Shown if method has no return type. ",
                                          "  (defaults to 'Object')") do |type|
-          options[:default_return] = type
+          options.default_return = type
         end
 
         opts.on('--hide-void-return', "Hides return types specified as 'void'. ",
                                       "  (default is shown)") do
-          options[:hide_void_return] = true
+          options.hide_void_return = true
         end
 
         opts.on('--query QUERY', "Only show objects that match a specific query") do |query|
           next if YARD::Config.options[:safe_mode]
-          options[:verifier].add_expressions(query.taint)
+          options.verifier.add_expressions(query.taint)
         end
 
         opts.on('--title TITLE', 'Add a specific title to HTML documents') do |title|
-          options[:title] = title
+          options.title = title
         end
 
         opts.on('-r', '--readme FILE', '--main FILE', 'The readme file used as the title page',
                                                       '  of documentation.') do |readme|
           if File.file?(readme)
-            options[:readme] = CodeObjects::ExtraFileObject.new(readme)
+            options.readme = CodeObjects::ExtraFileObject.new(readme)
           else
             log.warn "Could not find readme file: #{readme}"
           end
@@ -608,23 +658,23 @@ module YARD
 
         opts.on('-o', '--output-dir PATH',
                 'The output directory. (defaults to ./doc)') do |dir|
-          options[:serializer].basepath = dir
+          options.serializer.basepath = dir
         end
 
         opts.on('-m', '--markup MARKUP',
                 'Markup style used in documentation, like textile, ',
                 '  markdown or rdoc. (defaults to rdoc)') do |markup|
           self.has_markup = true
-          options[:markup] = markup.to_sym
+          options.markup = markup.to_sym
         end
 
         opts.on('-M', '--markup-provider MARKUP_PROVIDER',
-                'Overrides the library used to process markup ', 
+                'Overrides the library used to process markup ',
                 '  formatting (specify the gem name)') do |markup_provider|
-          options[:markup_provider] = markup_provider.to_sym
+          options.markup_provider = markup_provider.to_sym
         end
 
-        opts.on('--charset ENC', 'Character set to use when parsing files ', 
+        opts.on('--charset ENC', 'Character set to use when parsing files ',
                                  '  (default is system locale)') do |encoding|
           begin
             if defined?(Encoding) && Encoding.respond_to?(:default_external=)
@@ -637,20 +687,20 @@ module YARD
 
         opts.on('-t', '--template TEMPLATE',
                 'The template to use. (defaults to "default")') do |template|
-          options[:template] = template.to_sym
+          options.template = template.to_sym
         end
 
         opts.on('-p', '--template-path PATH',
                 'The template path to look for templates in.',
                 '  (used with -t).') do |path|
           next if YARD::Config.options[:safe_mode]
-          YARD::Templates::Engine.register_template_path(path)
+          YARD::Templates::Engine.register_template_path(File.expand_path(path))
         end
 
         opts.on('-f', '--format FORMAT',
                 'The output format for the template.',
                 '  (defaults to html)') do |format|
-          options[:format] = format.to_sym
+          options.format = format.to_sym
         end
 
         opts.on('--no-stats', 'Don\'t print statistics') do

data/lib/yard/cli/yri.rb

@@ -110,14 +110,18 @@ module YARD
         @search_paths.unshift(@cache[name]) if @cache[name]
         @search_paths.unshift(Registry.yardoc_file)
 
+        # Try to load it from in memory cache
+        log.debug "Searching for #{name} in memory"
+        if obj = try_load_object(name, nil)
+          return obj
+        end
+
         log.debug "Searching for #{name} in search paths"
         @search_paths.each do |path|
           next unless File.exist?(path)
           log.debug "Searching for #{name} in #{path}..."
           Registry.load(path)
-          obj = Registry.at(name)
-          if obj
-            cache_object(name, path)
+          if obj = try_load_object(name, path)
             return obj
           end
         end
@@ -126,6 +130,23 @@ module YARD
 
       private
 
+      # Tries to load the object with name. If successful, caches the object
+      # with the cache_path
+      #
+      # @param [String] name the object path
+      # @param [String] cache_path the location of the yardoc
+      #   db containing the object to cache for future lookups.
+      #   No caching is done if this is nil.
+      # @return [void]
+      def try_load_object(name, cache_path)
+        if obj = Registry.at(name)
+          if cache_path
+            cache_object(name, cache_path)
+          end
+          return obj
+        end
+      end
+
       # Loads {CACHE_FILE}
       # @return [void]
       def load_cache