yard 0.9.16 → 0.9.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 60bd85d004be2eaeed43646cc7211142cea13298
-  data.tar.gz: aa523a2062c7d8929699dc08466fec4d76183628
+SHA256:
+  metadata.gz: d7949e77d4f4c14b0bbc3991d7163ea80c5c2d9ab76a89050aaa0552ad0b8e83
+  data.tar.gz: b171a72e40b0eb28fa6271cf27f9c1683779c4f106568e892966110b8c07d451
 SHA512:
-  metadata.gz: 9dfcc5ebef57766151261684c04838f2fa59f5711033dd71d0f163aefee347df3ae6af07f3c0f749f9baa09a880859373576a1b6c328cbd7b9143cf8c366b1ba
-  data.tar.gz: fb836be48722eba0098e3dabad576cd64eb061aaa74477a1051bdb9ba85711092f649246f96871802ed679bd10a09e0a5cd3119e72b96da5291794b753ea7fde
+  metadata.gz: c2db6fc8d24102bcada8b33f8a8ced0a4e56ceede8e9d6a80a090e15a21009e0edb12af3204ed1b57238b9f1ab3bbabf9fc14ecf5ebad63c55380bad01938fc1
+  data.tar.gz: 9540bfe07bf2c9efc2c3318d6e24101888690bb38c76d561527839413b0ade25df36c4503d5cf86f69e48e1073de9b0fd02906c37883aba3fd8332b2087a9b9b

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # master
 
+# 0.9.19 - April 2nd, 2019
+
+[0.9.19]: https://github.com/lsegal/yard/compare/v0.9.16...v0.9.19
+
+- Fixed bug in browser back button (#1071, #1228)
+- Fixed handling of ArgumentError in ExtraFileObject (#1198)
+- Fixed double return tag displaying on boolean methods (#1226)
+- Removed unused `Module#namespace_name` function (#1229)
+- Fixed parsing order of README files. YARD will now prefer README over
+  README.md over README.x.md or README-x.md (and the like). READMEs will now
+  also be ordered by filename; the first README is still chosen unless
+  `--readme` is provided.
+- Updated AsciiDoc markup support to use non-deprecated calls.
+
 # [0.9.16] - August 11th, 2018
 
 [0.9.16]: https://github.com/lsegal/yard/compare/v0.9.15...v0.9.16
@@ -193,7 +207,7 @@ contributions to this version.
   to `default/fulldoc/html`, specifically the index or navigation lists.
 - Added support for Ruby 2.1+ decorator style method declaration syntax. YARD now
   supports:
-    private def foo(x, y) end
+  private def foo(x, y) end
 - Metadata headers in extra files can now be escaped from rendering by enclosing them
   in HTML comment blocks (`<!--\n @metadata here... \n-->`). Ensure that the opening
   comment tag is alone on the first line of the file to use this functionality.

data/README.md

@@ -45,7 +45,7 @@ following method documented with YARD formatting:
 ```ruby
 # Reverses the contents of a String or IO object.
 #
-# @param [String, #read] contents the contents to reverse
+# @param contents [String, #read] the contents to reverse
 # @return [String] the contents reversed lexically
 def reverse(contents)
   contents = contents.read if contents.respond_to? :read

data/Rakefile

@@ -2,23 +2,10 @@
 require File.dirname(__FILE__) + '/lib/yard'
 require File.dirname(__FILE__) + '/lib/yard/rubygems/specification'
 require 'rbconfig'
+require 'samus'
 
 YARD::VERSION.replace(ENV['YARD_VERSION']) if ENV['YARD_VERSION']
 
-desc "Publish gem"
-task :publish do
-  ver = ENV['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"
-  cmd = "bundle exec samus"
-  sh "#{cmd} build #{ver} && #{cmd} publish #{file} && rm #{file}"
-end
-
 desc "Builds the gem"
 task :gem do
   sh "gem build yard.gemspec"
@@ -36,12 +23,20 @@ rescue LoadError
   nil # noop
 end
 
+desc "Check code style with Rubocop"
 task :rubocop do
   sh "rubocop"
 end
 
-task :default => [:rubocop, :spec]
+desc "Generate documentation for Yard, and fail if there are any warnings"
+task :test_doc do
+  sh "ruby bin/yard --fail-on-warning #{"--no-progress" if ENV["CI"]}"
+end
+
+task :default => [:rubocop, :spec, :test_doc]
 
 YARD::Rake::YardocTask.new do |t|
   t.options += ['--title', "YARD #{YARD::VERSION} Documentation"]
 end
+
+Samus::Rake::DockerReleaseTask.new

data/docs/GettingStarted.md

@@ -525,7 +525,7 @@ which is automatically detected by YARD if found in the root of your project
 (any file starting with `README*`). You can specify extra files on the command
 line (or in the `.yardopts` file) by listing them after the '-' separator:
 
-    yardoc lib/**/*.rb ext/**/*.c - LICENSE.txt
+    yardoc lib/**/*.rb ext/**/*.{c,rb} - LICENSE.txt
 
 Note that the README will automatically be picked up, so you do not need to
 specify it. If you don't want to modify the default file globs, you can ignore

data/lib/yard/autoload.rb

@@ -64,6 +64,11 @@ module YARD
   # parsing phase. This allows YARD as well as any custom extension to
   # analyze source and generate {CodeObjects} to be stored for later use.
   module Handlers
+    # Shared logic between C and Ruby handlers.
+    module Common
+      autoload :MethodHandler,            __p('handlers/common/method_handler')
+    end
+
     # CRuby Handlers
     # @since 0.8.0
     module C

data/lib/yard/cli/i18n.rb

@@ -45,7 +45,7 @@ module YARD
         opts.banner = "Usage: yard i18n [options] [source_files [- extra_files]]"
         opts.top.list.clear
         opts.separator "(if a list of source files is omitted, "
-        opts.separator "  {lib,app}/**/*.rb ext/**/*.c is used.)"
+        opts.separator "  {lib,app}/**/*.rb ext/**/*.{c,rb} is used.)"
         opts.separator ""
         opts.separator "Example: yard i18n -o yard.pot - FAQ LICENSE"
         opts.separator "  The above example outputs .pot file for files in"

data/lib/yard/cli/stats.rb

@@ -184,7 +184,7 @@ module YARD
         opts = OptionParser.new
         opts.banner = "Usage: yard stats [options] [source_files]"
 
-        opts.separator "(if a list of source files is omitted, lib/**/*.rb ext/**/*.c is used.)"
+        opts.separator "(if a list of source files is omitted, lib/**/*.rb ext/**/*.{c,rb} is used.)"
 
         general_options(opts)
         output_options(opts)

data/lib/yard/cli/yardoc.rb

@@ -294,8 +294,9 @@ module YARD
         # Last minute modifications
         self.files = Parser::SourceParser::DEFAULT_PATH_GLOB if files.empty?
         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
+        readme = Dir.glob('README{,*[^~]}').
+          sort_by {|r| [r.count('.'), r.index('.'), r] }.first
+        readme ||= Dir.glob(files.first).first if options.onefile && !files.empty?
         options.readme ||= CodeObjects::ExtraFileObject.new(readme) if readme
         options.files.unshift(options.readme).uniq! if options.readme
 
@@ -516,7 +517,7 @@ module YARD
         opts.banner = "Usage: yard doc [options] [source_files [- extra_files]]"
 
         opts.separator "(if a list of source files is omitted, "
-        opts.separator "  {lib,app}/**/*.rb ext/**/*.c is used.)"
+        opts.separator "  {lib,app}/**/*.rb ext/**/*.{c,rb} is used.)"
         opts.separator ""
         opts.separator "Example: yardoc -o documentation/ - FAQ LICENSE"
         opts.separator "  The above example outputs documentation for files in"

data/lib/yard/code_objects/base.rb

@@ -519,7 +519,12 @@ module YARD
         if @namespace
           reg_obj = Registry.at(path)
           return if reg_obj && reg_obj.class == self.class
-          @namespace.children << self unless @namespace.is_a?(Proxy)
+
+          unless @namespace.is_a?(Proxy)
+            # remove prior objects from obj's children that match this one
+            @namespace.children.delete_if {|o| o.path == path }
+            @namespace.children << self
+          end
           Registry.register(self)
         end
       end

data/lib/yard/code_objects/extra_file_object.rb

@@ -113,14 +113,17 @@ module YARD::CodeObjects
       end
       contents
     rescue ArgumentError => e
-      if retried && e.message =~ /invalid byte sequence/
+      raise unless e.message =~ /invalid byte sequence/
+
+      if retried
         # This should never happen.
         log.warn "Could not read #{filename}, #{e.message}. You probably want to set `--charset`."
         return ''
+      else
+        data.force_encoding('binary') if data.respond_to?(:force_encoding)
+        retried = true
+        retry
       end
-      data.force_encoding('binary') if data.respond_to?(:force_encoding)
-      retried = true
-      retry
     end
 
     def translate(data)

data/lib/yard/core_ext/module.rb

@@ -8,13 +8,4 @@ class Module
   def class_name
     name.split("::").last
   end
-
-  # Returns the module namespace path minus the class/module name
-  #
-  # @example
-  #   module A::B::C; namespace_name end # => "A::B"
-  # @return [String] the namespace minus the class/module name
-  def namespace_name
-    name.split("::")[0..-2].join("::")
-  end
 end

data/lib/yard/docstring.rb

@@ -205,7 +205,7 @@ module YARD
     # @since 0.7.0
     # @todo Add Tags::Tag#to_raw and refactor
     def to_raw
-      tag_data = tags.sort_by(&:tag_name).map do |tag|
+      tag_data = tags.map do |tag|
         case tag
         when Tags::OverloadTag
           tag_text = "@#{tag.tag_name} #{tag.signature}\n"
@@ -271,7 +271,7 @@ module YARD
     # @param [#to_s] name the tag name to return data for, or nil for all tags
     # @return [Array<Tags::Tag>] the list of tags by the specified tag name
     def tags(name = nil)
-      list = @tags + convert_ref_tags
+      list = stable_sort_by(@tags + convert_ref_tags, &:tag_name)
       return list unless name
       list.select {|tag| tag.tag_name.to_s == name.to_s }
     end
@@ -374,5 +374,13 @@ module YARD
       add_tag(*parser.tags)
       parser.text
     end
+
+    # A stable sort_by method.
+    #
+    # @param list [Enumerable] the list to sort.
+    # @return [Array] a stable sorted list.
+    def stable_sort_by(list)
+      list.each_with_index.sort_by {|tag, i| [yield(tag), i] }.map(&:first)
+    end
   end
 end

data/lib/yard/handlers/c/handler_methods.rb

@@ -5,6 +5,7 @@ module YARD
       module HandlerMethods
         include Parser::C
         include CodeObjects
+        include Common::MethodHandler
 
         def handle_class(var_name, class_name, parent, in_module = nil)
           parent = nil if parent == "0"
@@ -67,7 +68,7 @@ module YARD
             register_visibility(obj, visibility)
             find_method_body(obj, func_name)
             obj.explicit = true
-            obj.add_tag(Tags::Tag.new(:return, '', 'Boolean')) if name =~ /\?$/
+            add_predicate_return_tag(obj) if name =~ /\?$/
           end
         end
 

data/lib/yard/handlers/c/method_handler.rb

@@ -15,8 +15,13 @@ class YARD::Handlers::C::MethodHandler < YARD::Handlers::C::Base
                 \s*"([^"]+)",
                 \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\(|\(\w+\))?(\w+)\)?,
                 \s*(-?\w+)\s*\)/xm
+  MATCH3 = /define_filetest_function\s*\(
+                \s*"([^"]+)",
+                \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\(|\(\w+\))?(\w+)\)?,
+                \s*(-?\w+)\s*\)/xm
   handles MATCH1
   handles MATCH2
+  handles MATCH3
   statement_class BodyStatement
 
   process do
@@ -32,5 +37,9 @@ class YARD::Handlers::C::MethodHandler < YARD::Handlers::C::Base
     statement.source.scan(MATCH2) do |name, func_name, _param_count|
       handle_method("method", "rb_mKernel", name, func_name)
     end
+
+    statement.source.scan(MATCH3) do |name, func_name, _param_count|
+      handle_method("singleton_method", "rb_cFile", name, func_name)
+    end
   end
 end

data/lib/yard/handlers/common/method_handler.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module YARD::Handlers
+  module Common
+    # Shared functionality between Ruby and C method handlers.
+    module MethodHandler
+      # @param [MethodObject] obj
+      def add_predicate_return_tag(obj)
+        if obj.tag(:return) && (obj.tag(:return).types || []).empty?
+          obj.tag(:return).types = ['Boolean']
+        elsif obj.tag(:return).nil?
+          unless obj.tags(:overload).any? {|overload| overload.tag(:return) }
+            obj.add_tag(YARD::Tags::Tag.new(:return, "", "Boolean"))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/handlers/ruby/dsl_handler_methods.rb

@@ -7,8 +7,9 @@ module YARD
         include Parser
 
         IGNORE_METHODS = Hash[*%w(alias alias_method autoload attr attr_accessor
-          attr_reader attr_writer extend include public private protected
-          private_constant).map {|n| [n, true] }.flatten]
+          attr_reader attr_writer extend include module_function public private
+          protected private_constant private_class_method public_class_method).
+          map {|n| [n, true] }.flatten]
 
         def handle_comments
           return if IGNORE_METHODS[caller_method]

data/lib/yard/handlers/ruby/method_handler.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 # Handles a method definition
 class YARD::Handlers::Ruby::MethodHandler < YARD::Handlers::Ruby::Base
+  include YARD::Handlers::Common::MethodHandler
+
   handles :def, :defs
 
   process do
@@ -39,13 +41,7 @@ class YARD::Handlers::Ruby::MethodHandler < YARD::Handlers::Ruby::Base
         extended method_added method_removed method_undefined).include?(meth)
       obj.add_tag(YARD::Tags::Tag.new(:private, nil))
     elsif meth.to_s =~ /\?$/
-      if obj.tag(:return) && (obj.tag(:return).types || []).empty?
-        obj.tag(:return).types = ['Boolean']
-      elsif obj.tag(:return).nil?
-        unless obj.tags(:overload).any? {|overload| overload.tag(:return) }
-          obj.add_tag(YARD::Tags::Tag.new(:return, "", "Boolean"))
-        end
-      end
+      add_predicate_return_tag(obj)
     end
 
     if obj.has_tag?(:option)

data/lib/yard/parser/source_parser.rb

@@ -68,7 +68,7 @@ module YARD
 
       # The default glob of files to be parsed.
       # @since 0.9.0
-      DEFAULT_PATH_GLOB = ["{lib,app}/**/*.rb", "ext/**/*.{c,cc,cxx,cpp}"]
+      DEFAULT_PATH_GLOB = ["{lib,app}/**/*.rb", "ext/**/*.{c,cc,cxx,cpp,rb}"]
 
       # Byte order marks for various encodings
       # @since 0.7.0

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

@@ -11,7 +11,7 @@ module YARD
         def run
           filename = File.cleanpath(File.join(library.source_path, path))
           raise NotFoundError unless File.file?(filename)
-          if filename =~ /\.(jpe?g|gif|png|bmp)$/i
+          if filename =~ /\.(jpe?g|gif|png|bmp|svg)$/i
             headers['Content-Type'] = StaticFileCommand::DefaultMimeTypes[$1.downcase] || 'text/html'
             render File.read_binary(filename)
           else

data/lib/yard/templates/helpers/html_helper.rb

@@ -11,6 +11,9 @@ module YARD
       # @private
       URLMATCH = /[^\w\s~!\*'\(\):;@&=\$,\[\]<>-]/
 
+      # @private
+      ASCIIDOC_ATTRIBUTES = {"env" => "yard", "env-yard" => ""}.freeze
+
       # @group Escaping Template Data
 
       # Escapes HTML entities
@@ -97,7 +100,8 @@ module YARD
       # @param [String] text input Asciidoc text
       # @return [String] output HTML
       def html_markup_asciidoc(text)
-        markup_class(:asciidoc).render(text)
+        options = {:attributes => ASCIIDOC_ATTRIBUTES}
+        markup_class(:asciidoc).convert(text, options)
       end
 
       # Converts Textile to HTML

data/lib/yard/version.rb

@@ -1,4 +1,6 @@
-# frozen_string_literal: true
-module YARD
-  VERSION = '0.9.16'
-end
+
+# frozen_string_literal: true
+
+module YARD
+  VERSION = '0.9.19'
+end

data/spec/cli/yardoc_spec.rb

@@ -184,9 +184,22 @@ RSpec.describe YARD::CLI::Yardoc do
       @yardoc.run(arg)
     end
 
+    # This example relies on processing Yard's own documentation, and with
+    # --fail-on-warning option on, will raise a SystemExit error if building
+    # that documentation produces any one warning.
+    #
+    # Unless handled, it will cause immediate and abnormal process exit,
+    # without running remaining tests, and with non-successful exit status.
+    #
+    # While suppressing exceptions is generally a bad practice and against this
+    # project's style guide, here it is well advocated,
+    # hence Lint/HandleExceptions cop is disabled.
     should_accept('--fail-on-warning') do |arg|
       expect(YARD).to receive(:parse)
-      @yardoc.run(arg)
+      begin
+        @yardoc.run(arg)
+      rescue SystemExit # rubocop:disable Lint/HandleExceptions
+      end
     end
   end
 
@@ -634,6 +647,12 @@ RSpec.describe YARD::CLI::Yardoc do
       expect(@yardoc.options.readme).to eq CodeObjects::ExtraFileObject.new('lib/foo.rb', '')
     end
 
+    it "uses no readme if files is empty and no readme is specified when using --one-file" do
+      expect(Dir).to receive(:glob).with('README{,*[^~]}').and_return []
+      @yardoc.parse_arguments '--one-file', ''
+      expect(@yardoc.options.readme).to be_nil
+    end
+
     it "uses readme it exists when using --one-file" do
       expect(Dir).to receive(:glob).with('README{,*[^~]}').and_return ['README']
       expect(File).to receive(:read).with('README').and_return('')
@@ -641,6 +660,34 @@ RSpec.describe YARD::CLI::Yardoc do
       expect(@yardoc.options.readme).to eq CodeObjects::ExtraFileObject.new('README', '')
     end
 
+    it "selects readme with no file extension over readme with file extension" do
+      expect(Dir).to receive(:glob).with('README{,*[^~]}').and_return ['README.md', 'README-DEV', 'README']
+      expect(File).to receive(:read).with('README').and_return('')
+      @yardoc.parse_arguments
+      expect(@yardoc.options.readme).to eq CodeObjects::ExtraFileObject.new('README', '')
+    end
+
+    it "selects readme with no suffix over readme with hyphenated suffix" do
+      expect(Dir).to receive(:glob).with('README{,*[^~]}').and_return ['README-fr.md', 'README.long-extension', 'README-de.md']
+      expect(File).to receive(:read).with('README.long-extension').and_return('')
+      @yardoc.parse_arguments
+      expect(@yardoc.options.readme).to eq CodeObjects::ExtraFileObject.new('README.long-extension', '')
+    end
+
+    it "selects readme with no suffix over readme with dotted suffix" do
+      expect(Dir).to receive(:glob).with('README{,*[^~]}').and_return ['README.fr.md', 'README.md', 'README.de.md']
+      expect(File).to receive(:read).with('README.md').and_return('')
+      @yardoc.parse_arguments
+      expect(@yardoc.options.readme).to eq CodeObjects::ExtraFileObject.new('README.md', '')
+    end
+
+    it "selects first readme from lexically sorted list" do
+      expect(Dir).to receive(:glob).with('README{,*[^~]}').and_return ['README-fr.md', 'README-de.md']
+      expect(File).to receive(:read).with('README-de.md').and_return('')
+      @yardoc.parse_arguments
+      expect(@yardoc.options.readme).to eq CodeObjects::ExtraFileObject.new('README-de.md', '')
+    end
+
     it "does not allow US-ASCII charset when using --one-file" do
       ienc = Encoding.default_internal
       eenc = Encoding.default_external

data/spec/code_objects/base_spec.rb

@@ -121,6 +121,16 @@ RSpec.describe YARD::CodeObjects::Base do
     expect(obj.children).to include(obj2)
   end
 
+  # @bug gh-1209
+  it "removes prior defined objects at the same path from namespace's children" do
+    Registry.clear
+    obj = ModuleObject.new(:root, :YARD)
+    ConstantObject.new(obj, :Testing)
+    ClassObject.new(obj, :Testing)
+    expect(obj.children.map {|o| o.type.to_sym }).to eq [:class]
+    expect(Registry.at('YARD::Testing').type).to eq :class
+  end
+
   it "properly re-indents source starting from 0 indentation" do
     obj = CodeObjects::Base.new(nil, :test)
     obj.source = <<-eof

data/spec/core_ext/module_spec.rb

@@ -6,10 +6,4 @@ RSpec.describe Module do
       expect(YARD::CodeObjects::Base.class_name).to eq "Base"
     end
   end
-
-  describe "#namespace" do
-    it "returns everything before the class name" do
-      expect(YARD::CodeObjects::Base.namespace_name).to eq "YARD::CodeObjects"
-    end
-  end
 end

data/spec/docstring_parser_spec.rb

@@ -241,6 +241,24 @@ eof
         alias bar foo
       eof
     end
+
+    it "does not warn on matching param with inline method modifier" do
+      expect(log).to_not receive(:warn)
+      YARD.parse_string <<-eof
+        # @param [Numeric] a
+        # @return [Numeric]
+        private_class_method def self.foo(a); a + 1; end
+      eof
+    end
+
+    it "warns on mismatching param with inline method modifier" do
+      expect(log).to receive(:warn).with(/@param tag has unknown parameter name: notaparam/)
+      YARD.parse_string <<-eof
+        # @param [Numeric] notaparam
+        # @return [Numeric]
+        private_class_method def self.foo(a); a + 1; end
+      eof
+    end
   end
 
   describe "after_parse (see)" do

data/spec/docstring_spec.rb

@@ -296,6 +296,15 @@ RSpec.describe YARD::Docstring do
       expect(doc.to_raw).to eq doc.all
     end
 
+    it "is stable sorting tags" do
+      expected = Docstring.new("123\n@param x\n@param y\n@version A")
+      doc = Docstring.new("123")
+      doc.add_tag(Tags::Tag.new('version', 'A'))
+      doc.add_tag(Tags::Tag.new('param', 'x'))
+      doc.add_tag(Tags::Tag.new('param', 'y'))
+      expect(doc.to_raw).to eq expected.all
+    end
+
     # @bug gh-563
     it "handles full @option tags" do
       doc = Docstring.new("@option foo [String] bar (nil) baz")