yard 0.9.5 → 0.9.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f93ca569b327f662d35892e83a4799a91868da56
-  data.tar.gz: c185c90879b8b862d40bb3eee2da95e67311e568
+  metadata.gz: 3c4860f6272d455388884ec3b5b0e5bf1908eca8
+  data.tar.gz: 66dab77e0af3f3a08aeb774e108c9861fc3d9139
 SHA512:
-  metadata.gz: 1f0cf4b6767842dcd90879cd6039e510767af156c17f6722b46028d239bca925dc854b5399009a27615761a50875523f7e2aa27f89b4e6f5f7d9d101d48f9ef2
-  data.tar.gz: 85d0822f567fb4caad941758e54f7805bceae24dbe1f84a31c4c0ae79658ddafb152c1646e3d65201847a69288133d7227a442825fbf0560b8399ff26714a6e6
+  metadata.gz: 0cdde30bedcc5c8d6bedbbc5d1f6e66db612059407ec9d1d7bc3d66813602e7e835949897bc844db74497315444139be9d098489b22b31c5998182b3b39c98fb
+  data.tar.gz: 3e463b1aac3301801bf496dc3fb474bd229fb40c3d585b4fabf5a6018f6dc70db787e4e18179b06627a59b59fd9f3cfb53883e9a1feebf2e88838052d55f5f47

data/CHANGELOG.md

@@ -1,3 +1,23 @@
+# Master branch (unreleased)
+
+- Removed official support for Ruby 1.x (1.8/1.9). YARD can still be installed
+  in these versions, but support is not guaranteed. Simple bug fixes may still
+  be considered via pull request only. Issues without code will be automatically
+  closed.
+- Added {YARD::Tags::Tag#explain_types} returning a plain English summary
+  of the type specification of a given tag. Also adds {YARD::Tags::TypesExplainer}
+  as an implementation class for the method.
+- Added support for automatic linking of constants and method calls of
+  Ruby syntax highlighted source code in generated HTML. Also adds the
+  {YARD::Parser::Ruby::TokenResolver} implementation class to iterate over
+  tokenized code with extra resolved object information.
+- Added support for compound constant assignments (`A::B::C = true`).
+- Added `LibraryVersion#yardoc_file_for_SOURCE` callback method for sources with
+  a pre-determined yardoc file location. Implement this method instead of
+  manually setting `library.yardoc_file = ...` in your load method (you can
+  still assign the attribute manually).
+- Use RubyGems 2.x+ API to query gems when available instead of using backport.
+
 # 0.9.5 - July 22nd, 2016
 
 - `yard doc` will now generate `.yardoc/processing` and `.yardoc/complete` files

data/README.md

@@ -7,6 +7,7 @@
 
 [![Gem Version](https://badge.fury.io/rb/yard.svg)](http://github.com/lsegal/yard/releases)
 [![Build Status](https://travis-ci.org/lsegal/yard.svg?branch=master)](https://travis-ci.org/lsegal/yard)
+[![Coverage Status](https://coveralls.io/repos/github/lsegal/yard/badge.svg)](https://coveralls.io/github/lsegal/yard)
 [![License](http://img.shields.io/badge/license-MIT-yellowgreen.svg)](#license)
 
 ## Synopsis
@@ -42,14 +43,16 @@ describing this data in the body of the description, a developer may formally
 declare the parameter or return type(s) in a single line. Consider the
 following method documented with YARD formatting:
 
-     # Reverses the contents of a String or IO object.
-     #
-     # @param [String, #read] contents the contents to reverse
-     # @return [String] the contents reversed lexically
-     def reverse(contents)
-       contents = contents.read if contents.respond_to? :read
-       contents.reverse
-     end
+```ruby
+# Reverses the contents of a String or IO object.
+#
+# @param [String, #read] contents the contents to reverse
+# @return [String] the contents reversed lexically
+def reverse(contents)
+  contents = contents.read if contents.respond_to? :read
+  contents.reverse
+end
+```
 
 With the above @param tag, we learn that the contents parameter can either be
 a String or any object that responds to the 'read' method, which is more
@@ -63,10 +66,12 @@ descriptive.
 extended and customized by plugins. Take for instance the scenario where you
 need to document the following code:
 
-    class List
-      # Sets the publisher name for the list.
-      cattr_accessor :publisher
-    end
+```ruby
+class List
+ # Sets the publisher name for the list.
+ cattr_accessor :publisher
+end
+```
 
 This custom declaration provides dynamically generated code that is hard for a
 documentation tool to properly document without help from the developer. To
@@ -103,7 +108,9 @@ documentation a much faster process.
 
 To install YARD, use the following command:
 
-    $ gem install yard
+```sh
+$ gem install yard
+```
 
 (Add `sudo` if you're installing under a POSIX system as root)
 
@@ -114,7 +121,9 @@ Alternatively, if you've checked the source out directly, you can call
 install lacks RDoc, which is occasionally used by YARD to convert markup to HTML.
 If running `which rdoc` turns up empty, install RDoc by issuing:
 
-    $ sudo apt-get install rdoc
+```sh
+$ sudo apt-get install rdoc
+```
 
 
 ## Usage
@@ -128,7 +137,9 @@ YARD comes packaged with a executable named `yard` which can control the many
 functions of YARD, including generating documentation, graphs running the
 YARD server, and so on. To view a list of available YARD commands, type:
 
-    $ yard --help
+```sh
+$ yard --help
+```
 
 Plugins can also add commands to the `yard` executable to provide extra
 functionality.
@@ -144,7 +155,9 @@ project root. This will assume your files are
 located in the `lib/` directory. If they are located elsewhere, you can specify
 paths and globs from the commandline via:
 
-    $ yardoc 'lib/**/*.rb' 'app/**/*.rb' ...etc...
+```sh
+$ yardoc 'lib/**/*.rb' 'app/**/*.rb' ...etc...
+```
 
 The tool will generate a `.yardoc` file which will store the cached database
 of your source code and documentation. If you want to re-generate your docs
@@ -163,12 +176,16 @@ maintainer/developer consumption).
 You can also add extra informative files (README, LICENSE) by separating
 the globs and the filenames with '-'.
 
-    $ yardoc 'app/**/*.rb' - README LICENSE FAQ
+```sh
+$ yardoc 'app/**/*.rb' - README LICENSE FAQ
+```
 
 If no globs precede the '-' argument, the default glob (`lib/**/*.rb`) is
 used:
 
-    $ yardoc - README LICENSE FAQ
+```sh
+$ yardoc - README LICENSE FAQ
+```
 
 Note that the README file can be specified with its own `--readme` switch.
 
@@ -185,9 +202,11 @@ a few shortcuts are available. For instance, to document only objects that have
 an "@api" tag with the value "public", all of the following syntaxes would give
 the same result:
 
-    --query '@api.text == "public"'
-    --query 'object.has_tag?(:api) && object.tag(:api).text == "public"'
-    --query 'has_tag?(:api) && tag(:api).text == "public"'
+```sh
+--query '@api.text == "public"'
+--query 'object.has_tag?(:api) && object.tag(:api).text == "public"'
+--query 'has_tag?(:api) && tag(:api).text == "public"'
+```
 
 Note that the "@tag" syntax returns the first tag named "tag" on the object.
 To return the array of all tags named "tag", use "@@tag".
@@ -195,8 +214,10 @@ To return the array of all tags named "tag", use "@@tag".
 Multiple `--query` arguments are allowed in the command line parameters. The
 following two lines both check for the existence of a return and param tag:
 
-    --query '@return' --query '@param'
-    --query '@return && @param'
+```sh
+--query '@return' --query '@param'
+--query '@return && @param'
+```
 
 For more information about the query syntax, see the {YARD::Verifier} class.
 
@@ -205,11 +226,13 @@ For more information about the query syntax, see the {YARD::Verifier} class.
 The second most obvious is to generate docs via a Rake task. You can do this by
 adding the following to your `Rakefile`:
 
-    YARD::Rake::YardocTask.new do |t|
-      t.files   = ['lib/**/*.rb', OTHER_PATHS]   # optional
-      t.options = ['--any', '--extra', '--opts'] # optional
-      t.stats_options = ['--list-undoc']         # optional
-    end
+```ruby
+YARD::Rake::YardocTask.new do |t|
+ t.files   = ['lib/**/*.rb', OTHER_PATHS]   # optional
+ t.options = ['--any', '--extra', '--opts'] # optional
+ t.stats_options = ['--list-undoc']         # optional
+end
+```
 
 All the settings: `files`, `options` and `stats_options` are optional. `files` will default to
 `lib/**/*.rb`, `options` will represents any options you might want
@@ -218,7 +241,9 @@ Again, a full list of options is available by typing `yardoc --help`
 in a shell. You can also override the options at the Rake command-line with the
 OPTS environment variable:
 
-    $ rake yard OPTS='--any --extra --opts'
+```sh
+$ rake yard OPTS='--any --extra --opts'
+```
 
 **3. `yri` RI Implementation**
 
@@ -226,8 +251,10 @@ The yri binary will use the cached .yardoc database to give you quick ri-style
 access to your documentation. It's way faster than ri but currently does not
 work with the stdlib or core Ruby libraries, only the active project. Example:
 
-    $ yri YARD::Handlers::Base#register
-    $ yri File.relative_path
+```sh
+$ yri YARD::Handlers::Base#register
+$ yri File.relative_path
+```
 
 Note that class methods must not be referred to with the "::" namespace
 separator. Only modules, classes and constants should use "::".
@@ -235,7 +262,9 @@ separator. Only modules, classes and constants should use "::".
 You can also do lookups on any installed gems. Just make sure to build the
 .yardoc databases for installed gems with:
 
-    $ sudo yard gems
+```sh
+$ yard gems
+```
 
 If you don't have sudo access, it will write these files to your `~/.yard`
 directory. `yri` will also cache lookups there.
@@ -245,7 +274,9 @@ directory. `yri` will also cache lookups there.
 The `yard server` command serves documentation for a local project or all installed
 RubyGems. To serve documentation for a project you are working on, simply run:
 
-    $ yard server
+```sh
+$ yard server
+```
 
 And the project inside the current directory will be parsed (if the source has
 not yet been scanned by YARD) and served at [http://localhost:8808](http://localhost:8808).
@@ -261,7 +292,9 @@ change any documentation in the source and refresh to see the new contents.
 
 To serve documentation for all installed gems, call:
 
-    $ yard server --gems
+```sh
+$ yard server --gems
+```
 
 This will also automatically build documentation for any gems that have not
 been previously scanned. Note that in this case there will be a slight delay
@@ -279,7 +312,9 @@ option to show mixin inclusions. You can output to stdout or a file, or pipe dir
 to `dot`. The same public, protected and private visibility rules apply to `yard graph`.
 More options can be seen by typing `yard graph --help`, but here is an example:
 
-    $ yard graph --protected --full --dependencies
+```sh
+$ yard graph --protected --full --dependencies
+```
 
 
 ## Changelog

data/Rakefile

@@ -1,19 +1,17 @@
+# frozen_string_literal: true
 require File.dirname(__FILE__) + '/lib/yard'
 require File.dirname(__FILE__) + '/lib/yard/rubygems/specification'
 require 'rbconfig'
 
 YARD::VERSION.replace(ENV['YARD_VERSION']) if ENV['YARD_VERSION']
 
-task :default => :travis_ci
-
 desc "Publish gem"
 task :publish do
   ver = ENV['VERSION']
 
-  if ver.nil? || ver.empty?
-    fail "missing VERSION=x.y.z"
-  elsif ver < YARD::VERSION
-    fail "invalid version `#{ver}' (must be >= `#{YARD::VERSION}')"
+  raise "missing VERSION=x.y.z" if ver.nil? || ver.empty?
+  if ver < YARD::VERSION
+    raise "invalid version `#{ver}' (must be >= `#{YARD::VERSION}')"
   end
 
   file = "release-v#{ver}.tar.gz"
@@ -32,44 +30,17 @@ task :install => :gem do
 end
 
 begin
-require 'rvm-tester'
-RVM::Tester::TesterTask.new do |t|
-  t.rubies = %w(1.8.6 ree jruby 1.8.7 1.9.2 1.9.3)
-  t.bundle_install = false # don't need to do this all the time
-  t.verbose = true
-end
+  require 'rspec/core/rake_task'
+  RSpec::Core::RakeTask.new(:spec)
 rescue LoadError
+  nil # noop
 end
 
-task :travis_ci do
-  ENV['SUITE'] = '1'
-  ENV['CI'] = '1'
-  ENV['LEGACY'] = nil
-  Rake::Task['specs'].execute
-  if RUBY_VERSION >= '1.9' && RUBY_PLATFORM != 'java'
-    puts ""
-    puts "Running specs with in legacy mode"
-    ENV['LEGACY'] = '1'
-    Rake::Task['specs'].execute
-  end
+task :rubocop do
+  sh "rubocop"
 end
 
-desc "Run all specs"
-task :specs do
-  opts = ['rspec', '-c']
-  opts += ["--require", File.join(File.dirname(__FILE__), 'spec', 'spec_helper')]
-  opts += ['-I', YARD::ROOT]
-  if ENV['DEBUG']
-    $DEBUG = true
-    opts += ['-d']
-  end
-  opts += FileList["spec/**/*_spec.rb"].sort
-  cmd = opts.join(' ')
-  puts cmd if Rake.application.options.trace
-  system(cmd)
-  raise "Command failed with status (#{$?.to_i}): #{cmd}" if $?.to_i != 0
-end
-task :spec => :specs
+task :default => [:rubocop, :spec]
 
 YARD::Rake::YardocTask.new do |t|
   t.options += ['--title', "YARD #{YARD::VERSION} Documentation"]

data/benchmarks/builtins_vs_eval.rb

@@ -1,10 +1,11 @@
+# frozen_string_literal: true
 require 'benchmark'
 require File.join(File.dirname(__FILE__), '..', 'lib', 'yard')
 
 TIMES = (ARGV[0] || 10_000).to_i
 
 def bench_builtins(name)
-  YARD::CodeObjects::BUILTIN_EXCEPTIONS_HASH.has_key? name
+  YARD::CodeObjects::BUILTIN_EXCEPTIONS_HASH.key? name
 end
 
 def bench_eval(name)
@@ -14,10 +15,10 @@ rescue
 end
 
 Benchmark.bmbm do |b|
-  b.report("builtins PASS") { TIMES.times {YARD::CodeObjects::BUILTIN_EXCEPTIONS.each {|y| bench_builtins(y) } } }
-  b.report("eval PASS") { TIMES.times {YARD::CodeObjects::BUILTIN_EXCEPTIONS.each {|y| bench_eval(y) }} }
-  b.report("builtins FAIL") { TIMES.times {YARD::CodeObjects::BUILTIN_MODULES.each {|y| bench_builtins(y) } } }
-  b.report("eval FAIL") { TIMES.times {YARD::CodeObjects::BUILTIN_MODULES.each {|y| bench_eval(y) }} }
-  b.report("builtins ANY") { TIMES.times {YARD::CodeObjects::BUILTIN_CLASSES.each {|y| bench_builtins(y) } } }
-  b.report("eval ANY") { TIMES.times {YARD::CodeObjects::BUILTIN_CLASSES.each {|y| bench_eval(y) }} }
-end
+  b.report("builtins PASS") { TIMES.times { YARD::CodeObjects::BUILTIN_EXCEPTIONS.each {|y| bench_builtins(y) } } }
+  b.report("eval PASS") { TIMES.times { YARD::CodeObjects::BUILTIN_EXCEPTIONS.each {|y| bench_eval(y) } } }
+  b.report("builtins FAIL") { TIMES.times { YARD::CodeObjects::BUILTIN_MODULES.each {|y| bench_builtins(y) } } }
+  b.report("eval FAIL") { TIMES.times { YARD::CodeObjects::BUILTIN_MODULES.each {|y| bench_eval(y) } } }
+  b.report("builtins ANY") { TIMES.times { YARD::CodeObjects::BUILTIN_CLASSES.each {|y| bench_builtins(y) } } }
+  b.report("eval ANY") { TIMES.times { YARD::CodeObjects::BUILTIN_CLASSES.each {|y| bench_eval(y) } } }
+end

data/benchmarks/concat_vs_join.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require "benchmark"
 
 STR1 = "Hello"

data/benchmarks/erb_vs_erubis.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'rubygems'
 require 'erubis'
 require 'erubis/tiny'
@@ -41,7 +42,7 @@ Benchmark.bmbm do |x|
     rungen
   end
 
-  x.report("erb")  do
+  x.report("erb") do
     eval <<-eof
        module YARD; module Templates; module Template
         def erb_with(str, x) ERB.new(str, nil) end
@@ -50,4 +51,4 @@ Benchmark.bmbm do |x|
 
     rungen
   end
-end
+end

data/benchmarks/format_args.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require "benchmark"
 require 'lib/yard'
 

data/benchmarks/generation.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require "benchmark"
 require File.join(File.dirname(__FILE__), '..', 'lib', 'yard')
 
@@ -34,4 +35,4 @@ gen-with-locking   7.790000   0.400000   8.190000 (  8.373811)
                        user     system      total        real
 gen-w/o-locking    9.820000   0.430000  10.250000 ( 10.293283)
 gen-with-locking   7.820000   0.380000   8.200000 (  8.243326)
-=end
+=end

data/benchmarks/marshal_vs_dbm.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'benchmark'
 require 'dbm'
 
@@ -5,7 +6,7 @@ MARSHAL_FILE = "marshal_test.db"
 DBM_FILE = "dbm_test"
 WRITE_TIMES = 1
 READ_TIMES = 100
-NUM_INDICES = 10000
+NUM_INDICES = 10_000
 INDICES = ['33', '857', '5022', '8555']
 
 def generate_index

data/benchmarks/parsing.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require "benchmark"
 require 'yard'
 require 'logger'
@@ -43,4 +44,3 @@ parse            6.380000   0.050000   6.430000 (  6.446954)
 parse in order   6.320000   0.040000   6.360000 (  6.394460)
 parse            6.040000   0.040000   6.080000 (  6.099738)
 =end
-

data/benchmarks/pathname_vs_string.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'pathname'
 require "benchmark"
 require File.dirname(__FILE__) + '/../lib/yard'