yard 0.8.2.1 → 0.8.3

data/docs/WhatsNew.md

@@ -16,6 +16,7 @@
 12. **Added line numbers to `yard stats --list-undoc --compact`** (0.8.0)
 13. **Single object db now default (multi-object db unsupported)** (0.8.0)
 14. **Added `--api` tag to generate documentation for API sets** (0.8.1)
+15. **Added `--non-transitive-tag` to disable transitive tag** (0.8.3)
 
 ## Directives (new behavioural tag syntax) (0.8.0)
 
@@ -278,6 +279,19 @@ due to security concerns, whereas `--api` works in either mode.
 This enables `--api` to function on remote documentation sites like
 [rubydoc.info](http://rubydoc.info).
 
+## Added `--non-transitive-tag` to disable transitive tag (0.8.3)
+
+You can now use `--non-transitive-tag` to disable transitivity on
+tags that are defined as transitive by default. For instance, in
+some cases you might not want the @api tag to apply to all methods
+when you define it on a class. Only the class itself has a specific
+@api tag. To do this, you can mark @api as non-transitive with:
+
+    $ yard doc --non-transitive-tag api --api some_api
+
+Which will avoid classifying treating @api as a transitive tag
+when parsing modules and classes.
+
 
 # What's New in 0.7.x?
 
@@ -1048,14 +1062,14 @@ New tags (@abstract, @private)
 
 Two new tags were added to the list of builtin meta-tags in YARD. `@abstract`
 marks a class/module/method as abstract while `@private` marks an object
-as "private". The latter tag is unsed in situations where an object is public
+as "private". The latter tag is used in situations where an object is public
 due to Ruby's own visibility limitations (constants, classes and modules
 can never be private) but not actually part of your public API. You should
 use this tag sparingly, as it is not meant to be an equivalent to RDoc's
 `:nodoc:` tag. Remember, YARD recommends documenting private objects too.
 This tag exists so that you can create a query (`--query !@private`) to
 ignore all of these private objects in your documentation. You can also
-use the new `--no-private` switch, which is a shortcut to the afformentioned
+use the new `--no-private` switch, which is a shortcut to the aforementioned
 query. You can read more about the new tags in the {file:docs/GettingStarted.md}
 guide.
 

data/lib/yard.rb

@@ -1,6 +1,6 @@
-module YARD
-  VERSION = "0.8.2.1"
+require File.expand_path('../yard/version.rb', __FILE__)
 
+module YARD
   # The root path for YARD source libraries
   ROOT = File.expand_path(File.dirname(__FILE__))
 
@@ -27,10 +27,30 @@ module YARD
   # (see YARD::Config.load_plugins)
   # @deprecated Use {Config.load_plugins}
   def self.load_plugins; YARD::Config.load_plugins end
+
+  # @return [Boolean] whether YARD is being run inside of Windows
+  def self.windows?
+    return @windows if defined? @windows
+    require 'rbconfig'
+    if ::RbConfig::CONFIG['host_os'] =~ /mingw|win32|cygwin/
+      @wnidows = true
+    else
+      @windows = false
+    end
+  ensure
+    @windows ||= false
+  end
+
+  # @return [Boolean] whether YARD is being run in Ruby 1.8 mode
+  def self.ruby18?; !ruby19? end
+
+  # @return [Boolean] whether YARD is being run in Ruby 1.9 mode
+  def self.ruby19?; @ruby19 ||= (RUBY_VERSION >= "1.9.1") end
 end
 
 # Keep track of Ruby version for compatibility code
-RUBY19, RUBY18 = *(RUBY_VERSION >= "1.9.1" ? [true, false] : [false, true])
+# @deprecated Use {YARD.ruby18?} or {YARD.ruby19?} instead.
+RUBY18, RUBY19 = YARD.ruby18?, YARD.ruby19?
 
 # Load Ruby core extension classes
 Dir.glob(File.join(YARD::ROOT, 'yard', 'core_ext', '*.rb')).each do |file|

data/lib/yard/autoload.rb

@@ -3,19 +3,20 @@ def __p(path) File.join(YARD::ROOT, 'yard', *path.split('/')); end
 
 module YARD
   module CLI # Namespace for command-line interface components
-    autoload :Command,        __p('cli/command')
-    autoload :CommandParser,  __p('cli/command_parser')
-    autoload :Config,         __p('cli/config')
-    autoload :Diff,           __p('cli/diff')
-    autoload :Gems,           __p('cli/gems')
-    autoload :Graph,          __p('cli/graph')
-    autoload :Help,           __p('cli/help')
-    autoload :List,           __p('cli/list')
-    autoload :Server,         __p('cli/server')
-    autoload :Stats,          __p('cli/stats')
-    autoload :Yardoc,         __p('cli/yardoc')
-    autoload :YRI,            __p('cli/yri')
-    autoload :I18n,           __p('cli/i18n')
+    autoload :Command,         __p('cli/command')
+    autoload :CommandParser,   __p('cli/command_parser')
+    autoload :Config,          __p('cli/config')
+    autoload :Diff,            __p('cli/diff')
+    autoload :Gems,            __p('cli/gems')
+    autoload :Graph,           __p('cli/graph')
+    autoload :Help,            __p('cli/help')
+    autoload :List,            __p('cli/list')
+    autoload :Server,          __p('cli/server')
+    autoload :Stats,           __p('cli/stats')
+    autoload :Yardoc,          __p('cli/yardoc')
+    autoload :YardoptsCommand, __p('cli/yardopts_command')
+    autoload :YRI,             __p('cli/yri')
+    autoload :I18n,            __p('cli/i18n')
   end
 
   # A "code object" is defined as any entity in the Ruby language.

data/lib/yard/cli/command.rb

@@ -41,8 +41,8 @@ module YARD
         opts.on_tail('--verbose', 'Show more information.') { log.level = Logger::INFO }
         opts.on_tail('--debug', 'Show debugging information.') { log.level = Logger::DEBUG }
         opts.on_tail('--backtrace', 'Show stack traces') { log.show_backtraces = true }
-        opts.on_tail('-v', '--version', 'Show version.') { puts "yard #{YARD::VERSION}"; exit }
-        opts.on_tail('-h', '--help', 'Show this help.')  { puts opts; exit }
+        opts.on_tail('-v', '--version', 'Show version.') { log.puts "yard #{YARD::VERSION}"; exit }
+        opts.on_tail('-h', '--help', 'Show this help.')  { log.puts opts; exit }
       end
 
       # Parses the option and gracefully handles invalid switches
@@ -54,7 +54,7 @@ module YARD
       def parse_options(opts, args)
         opts.parse!(args)
       rescue OptionParser::ParseError => err
-        log.warn "Unrecognized/#{err.message}"
+        unrecognized_option(err)
         args.shift if args.first && args.first[0,1] != '-'
         retry
       end
@@ -71,6 +71,14 @@ module YARD
         log.error "The file `#{file}' could not be loaded:\n#{load_exception}"
         exit
       end
+
+      # Callback when an unrecognize option is parsed
+      #
+      # @param [OptionParser::ParseError] err the exception raised by the
+      #   option parser
+      def unrecognized_option(err)
+        log.warn "Unrecognized/#{err.message}"
+      end
     end
   end
 end

data/lib/yard/cli/command_parser.rb

@@ -77,12 +77,12 @@ module YARD
       def commands; self.class.commands end
 
       def list_commands
-        puts "Usage: yard <command> [options]"
-        puts
-        puts "Commands:"
+        log.puts "Usage: yard <command> [options]"
+        log.puts
+        log.puts "Commands:"
         commands.keys.sort_by {|k| k.to_s }.each do |command_name|
           command = commands[command_name].new
-          puts "%-8s %s" % [command_name, command.description]
+          log.puts "%-8s %s" % [command_name, command.description]
         end
       end
     end

data/lib/yard/cli/config.rb

@@ -61,13 +61,13 @@ module YARD
 
       def view_item
         log.debug "Viewing #{key}"
-        puts YARD::Config.options[key].inspect
+        log.puts YARD::Config.options[key].inspect
       end
 
       def list_configuration
         log.debug "Listing configuration"
         require 'yaml'
-        puts YAML.dump(YARD::Config.options).sub(/\A--.*\n/, '').gsub(/\n\n/, "\n")
+        log.puts YAML.dump(YARD::Config.options).sub(/\A--.*\n/, '').gsub(/\n\n/, "\n")
       end
 
       def encode_values

data/lib/yard/cli/diff.rb

@@ -12,6 +12,9 @@ module YARD
         super
         @list_all = false
         @use_git = false
+        @compact = false
+        @modified = true
+        @verifier = Verifier.new
         @old_git_commit = nil
         @old_path = Dir.pwd
         log.show_backtraces = true
@@ -25,11 +28,11 @@ module YARD
         registry = optparse(*args).map do |gemfile|
           if @use_git
             load_git_commit(gemfile)
-            Registry.all.map {|o| o.path }
+            all_objects
           else
             if load_gem_data(gemfile)
               log.info "Found #{gemfile}"
-              Registry.all.map {|o| o.path }
+              all_objects
             else
               log.error "Cannot find gem #{gemfile}"
               nil
@@ -39,31 +42,64 @@ module YARD
 
         return if registry.size != 2
 
-        [   ["Added objects", registry[1] - registry[0]],
-            ["Removed objects", registry[0] - registry[1]]].each do |name, objects|
+        first_object = nil
+        [   ["Added objects", "A", added_objects(*registry)],
+            ["Modified objects", "M", modified_objects(*registry)],
+            ["Removed objects", "D", removed_objects(*registry)]].each do |name, short, objects|
+          next if short == "M" && @modified == false
           next if objects.empty?
           last_object = nil
           all_objects_notice = false
-          puts name + ":"
-          objects.sort.each do |object|
-            if !@list_all && last_object && object =~ /#{Regexp.quote last_object}(::|\.|#)/
-              print " (...)" unless all_objects_notice
+          log.puts name + ":" unless @compact
+          objects.sort_by {|o| o.path }.each do |object|
+            if !@list_all && last_object && object.parent == last_object
+              log.print " (...)" unless all_objects_notice
               all_objects_notice = true
               next
+            elsif @compact
+              log.puts if first_object
             else
-              puts
+              log.puts
             end
             all_objects_notice = false
-            print "  " + object
+            log.print "" + (@compact ? "#{short} " : "  ") +
+              object.path + " (#{object.file}:#{object.line})"
             last_object = object
+            first_object = true
+          end
+          unless @compact
+            log.puts; log.puts
           end
-          puts
-          puts
         end
+        log.puts if @compact
       end
 
       private
 
+      def all_objects
+        return Registry.all if @verifier.expressions.empty?
+        @verifier.run(Registry.all)
+      end
+
+      def added_objects(registry1, registry2)
+        registry2.reject {|o| registry1.find {|o2| o2.path == o.path } }
+      end
+
+      def modified_objects(registry1, registry2)
+        registry1.select do |obj|
+          case obj
+          when CodeObjects::MethodObject
+            registry2.find {|o| obj == o && o.source != obj.source }
+          when CodeObjects::ConstantObject
+            registry2.find {|o| obj == o && o.value != obj.value }
+          end
+        end.compact
+      end
+
+      def removed_objects(registry1, registry2)
+        registry1.reject {|o| registry2.find {|o2| o2.path == o.path } }
+      end
+
       def load_git_commit(commit)
         commit_path = 'git_commit' + commit.gsub(/\W/, '_')
         tmpdir = File.join(Dir.tmpdir, commit_path)
@@ -74,6 +110,7 @@ module YARD
         Dir.chdir(tmpdir)
         log.info("git says: " + `git reset --hard #{commit}`.chomp)
         generate_yardoc(tmpdir)
+      ensure
         Dir.chdir(@old_path)
         cleanup(commit_path)
       end
@@ -140,9 +177,9 @@ module YARD
 
       def generate_yardoc(dir)
         olddir = Dir.pwd
-        Dir.chdir(dir)
-        log.enter_level(Logger::ERROR) { Yardoc.run('-n', '--no-save') }
-        Dir.chdir(olddir)
+        Dir.chdir(dir) do
+          log.enter_level(Logger::ERROR) { Yardoc.run('-n', '--no-save') }
+        end
       end
 
       def expand_gem(gemfile, io)
@@ -184,13 +221,20 @@ module YARD
         opts.on('-a', '--all', 'List all objects, even if they are inside added/removed module/class') do
           @list_all = true
         end
+        opts.on('--compact', 'Show compact results') { @compact = true }
         opts.on('--git', 'Compare versions from two git commit/branches') do
           @use_git = true
         end
+        opts.on('--query QUERY', 'Only diff filtered objects') do |query|
+          @verifier.add_expressions(query)
+        end
+        opts.on('--no-modified', 'Ignore modified objects') do
+          @modified = false
+        end
         common_options(opts)
         parse_options(opts, args)
         unless args.size == 2
-          puts opts.banner
+          log.puts opts.banner
           exit(0)
         end
 

data/lib/yard/cli/graph.rb

@@ -20,7 +20,7 @@ module YARD
     #
     # @see Graph#run
     # @since 0.6.0
-    class Graph < Command
+    class Graph < YardoptsCommand
       # The options parsed out of the commandline.
       # Default options are:
       #   :format => :dot
@@ -32,6 +32,7 @@ module YARD
       # Creates a new instance of the command-line utility
       def initialize
         super
+        @use_document_file = false
         @options = GraphOptions.new
         options.reset_defaults
         options.serializer = YARD::Serializers::StdoutSerializer.new
@@ -48,8 +49,8 @@ module YARD
       #   grapher.run('--private')
       # @param [Array<String>] args each tokenized argument
       def run(*args)
+        parse_arguments(*args)
         Registry.load
-        optparse(*args)
 
         contents = objects.map do |o|
           o.format(options.merge(:serialize => false))
@@ -61,6 +62,8 @@ module YARD
 
       private
 
+      def unrecognized_option(err) end
+
       # Parses commandline options.
       # @param [Array<String>] args each tokenized argument
       def optparse(*args)

data/lib/yard/cli/help.rb

@@ -9,7 +9,7 @@ module YARD
         if args.first && cmd = CommandParser.commands[args.first.to_sym]
           cmd.run('--help')
         else
-          puts "Command #{args.first} not found." if args.first
+          log.puts "Command #{args.first} not found." if args.first
           CommandParser.run('--help')
         end
       end

data/lib/yard/cli/list.rb

@@ -11,8 +11,8 @@ module YARD
       # @return [void]
       def run(*args)
         if args.include?('--help')
-          puts "Usage: yard list [yardoc_options]"
-          puts "Takes the same arguments as yardoc. See yardoc --help"
+          log.puts "Usage: yard list [yardoc_options]"
+          log.puts "Takes the same arguments as yardoc. See yardoc --help"
         else
           Yardoc.run('-c', '--list', *args)
         end

data/lib/yard/cli/server.rb

@@ -71,18 +71,58 @@ module YARD
 
       def add_libraries(args)
         (0...args.size).step(2) do |index|
-          library, yardoc = args[index], args[index + 1]
-          yardoc ||= '.yardoc'
-          yardoc = File.expand_path(yardoc)
-          if File.exist?(yardoc)
+          library, dir = args[index], args[index + 1]
+
+          libver = nil
+          if dir
+            if File.exist?(dir)
+              # Provided dir contains a .yardopts file
+              libver = create_library_version_if_yardopts_exist(library, dir)
+              libver ||= YARD::Server::LibraryVersion.new(library, nil, dir)
+            end
+          else
+            # Check if this dir contains a .yardopts file
+            pwd = Dir.pwd
+            libver = create_library_version_if_yardopts_exist(library, pwd)
+
+            # Check default location
+            yfile = File.join(pwd, '.yardoc')
+            libver ||= YARD::Server::LibraryVersion.new(library, nil, yfile)
+          end
+
+          # Register library
+          if libver
+            libver.yardoc_file = File.expand_path(libver.yardoc_file) if libver.yardoc_file
+            libver.source_path = File.expand_path(libver.source_path) if libver.source_path
             libraries[library] ||= []
-            libraries[library] |= [YARD::Server::LibraryVersion.new(library, nil, yardoc)]
+            libraries[library] |= [libver]
           else
-            log.warn "Cannot find yardoc db for #{library}: #{yardoc}"
+            log.warn "Cannot find yardoc db for #{library}: #{dir.inspect}"
           end
         end
       end
 
+      # @param [String] library The library name.
+      # @param [String, nil] dir The argument provided on the CLI after the
+      #   library name. Is supposed to point to either a project directory
+      #   with a Yard options file, or a yardoc db.
+      # @return [LibraryVersion, nil]
+      def create_library_version_if_yardopts_exist(library, dir)
+        if dir
+         options_file = File.join(dir, Yardoc::DEFAULT_YARDOPTS_FILE)
+         if File.exist?(options_file)
+           # Found yardopts, extract db path
+           yfile = extract_db_from_options_file(options_file)
+           db = File.expand_path(yfile, dir)
+
+           # Create libver
+           libver = YARD::Server::LibraryVersion.new(library, nil, db)
+           libver.source_path = dir
+           libver
+         end
+        end
+      end
+
       def add_gems
         require 'rubygems'
         Gem.source_index.find_name('').each do |spec|
@@ -94,7 +134,7 @@ module YARD
       def add_gems_from_gemfile(gemfile = nil)
         require 'bundler'
         gemfile ||= "Gemfile"
-        if File.exists?("#{gemfile}.lock")
+        if File.exist?("#{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)]
@@ -166,18 +206,45 @@ module YARD
         parse_options(opts, args)
 
         if args.empty? && libraries.empty?
-          if !File.exist? File.expand_path('.yardoc')
-            log.enter_level(Logger::INFO) do
-              log.info "No .yardoc file found in current directory, parsing source before starting server..."
-            end
-            Yardoc.run('-n')
+          # No args - try to use current dir
+          add_libraries([File.basename(Dir.pwd), nil])
+
+          # Generate doc for first time
+          libver = libraries.empty? ? nil : libraries.values.first.first
+          if libver and !File.exist?(libver.yardoc_file)
+            generate_doc_for_first_time(libver)
           end
-          add_libraries([File.basename(Dir.pwd), File.expand_path('.yardoc')])
         else
           add_libraries(args)
           options[:single_library] = false if libraries.size > 1
         end
       end
+
+      def generate_doc_for_first_time(libver)
+        log.enter_level(Logger::INFO) do
+          yardoc_file = libver.yardoc_file.sub /^#{Regexp.quote Dir.pwd}[\\\/]+/, ''
+          log.info "No yardoc db found in #{yardoc_file}, parsing source before starting server..."
+        end
+        Dir.chdir(libver.source_path) do
+          Yardoc.run('-n')
+        end
+      end
+
+      def extract_db_from_options_file(options_file)
+        args = File.read_binary(options_file).shell_split
+        db = YARD::Registry.yardoc_file
+        opts = OptionParser.new
+        opts.on('-b', '--db FILE') {|file| db = file }
+
+        begin
+          opts.parse!(args)
+        rescue OptionParser::ParseError
+          args.shift if args.first && args.first[0,1] != '-'
+          retry
+        end
+
+        db
+      end
     end
   end
 end