yard 0.9.16 → 0.9.21

data/Dockerfile.samus

@@ -0,0 +1,28 @@
+FROM lsegal/samus:latest as samus
+
+FROM ruby:2
+ARG VERSION
+ENV VERSION=${VERSION}
+WORKDIR /github/lsegal/yard
+ENTRYPOINT samus publish release-v${VERSION}.tar.gz
+
+# Prepare credential config
+RUN mkdir -p ~/.ssh
+RUN echo "Host *" > ~/.ssh/config
+RUN echo "    StrictHostKeyChecking no" >> ~/.ssh/config
+RUN chmod 400 ~/.ssh/config
+COPY ./.samusprep/.samus /root/.samus
+COPY ./.samusprep/.gitconfig /root/.gitconfig
+
+# Setup Samus
+ENV PATH=$PATH:/samus/bin
+COPY --from=samus /samus /samus
+
+# Install gems
+ENV BUNDLE_PATH=/var/gems
+COPY Gemfile /github/lsegal/yard
+RUN bundle
+
+# Run build
+COPY . /github/lsegal/yard
+RUN samus build --skip-restore ${VERSION}

data/Gemfile

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+source 'https://rubygems.org'
+
+group :development do
+  gem 'rspec'
+  gem 'rake'
+  gem 'rdoc'
+  gem 'json'
+  gem 'simplecov'
+  gem 'samus', '~> 3.0.8', :require => false
+  gem 'coveralls', :require => false
+end
+
+group :asciidoc do
+  gem 'asciidoctor'
+end
+
+group :markdown do
+  gem 'redcarpet', :platforms => [:ruby]
+end
+
+group :textile do
+  gem 'RedCloth', :platforms => [:ruby]
+end
+
+group :server do
+  gem 'rack'
+end
+
+group :i18n do
+  gem 'gettext'
+end

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
@@ -226,6 +226,8 @@ The second most obvious is to generate docs via a Rake task. You can do this by
 adding the following to your `Rakefile`:
 
 ```ruby
+require 'yard'
+
 YARD::Rake::YardocTask.new do |t|
  t.files   = ['lib/**/*.rb', OTHER_PATHS]   # optional
  t.options = ['--any', '--extra', '--opts'] # optional

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,15 @@ rescue LoadError
   nil # noop
 end
 
-task :rubocop do
-  sh "rubocop"
+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]
+task :default => [:spec, :test_doc]
 
 YARD::Rake::YardocTask.new do |t|
   t.options += ['--title', "YARD #{YARD::VERSION} Documentation"]
 end
+
+Samus::Rake::DockerReleaseTask.new

data/SECURITY.md

@@ -0,0 +1,26 @@
+# Security Policy
+
+## Supported Versions
+
+The following versions are supported with security patches for
+any reported vulnerabilities in YARD or dependent software.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.9.x   | :white_check_mark: |
+| < 0.9   | :x:                |
+
+## Reporting a Vulnerability
+
+If you've discovered a vulnerability in YARD source code, please email
+lsegal@soen.ca with as much information as possible. You should typically
+receive a response within 24-48 hours, though depending on scheduling
+it may take up to a week to respond. If you do not get a response on
+your initial email within a few days, please re-send your email or
+reach out on other channels (such as yardoc@googlegroups.com) to
+try to get a hold of a maintainer. Please do not include sensitive
+material if you are reaching out through secondary channels unless
+you first receive confirmation that it is okay.
+
+Thank you for your help and cooperation in making YARD a stable and
+safe piece of software.

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

@@ -189,6 +189,10 @@ module YARD
         def new(namespace, name, *args, &block)
           raise ArgumentError, "invalid empty object name" if name.to_s.empty?
           if namespace.is_a?(ConstantObject)
+            unless namespace.value =~ /\A#{NAMESPACEMATCH}\Z/
+              raise Parser::UndocumentableError, "constant mapping"
+            end
+
             namespace = Proxy.new(namespace.namespace, namespace.value)
           end
 
@@ -382,11 +386,14 @@ module YARD
       #   as a +String+ for the definition of the code object only (not the block)
       def source=(statement)
         if statement.respond_to?(:source)
-          self.signature = statement.first_line
           @source = format_source(statement.source.strip)
         else
           @source = format_source(statement.to_s)
         end
+
+        if statement.respond_to?(:signature)
+          self.signature = statement.signature
+        end
       end
 
       # The documentation string associated with the object
@@ -519,7 +526,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/code_objects/proxy.rb

@@ -58,6 +58,10 @@ module YARD
         self.type = type
 
         if @namespace.is_a?(ConstantObject)
+          unless @namespace.value =~ /\A#{NAMESPACEMATCH}\Z/
+            raise Parser::UndocumentableError, "constant mapping"
+          end
+
           @origname = nil # forget these for a constant
           @orignamespace = nil
           @namespace = Proxy.new(@namespace.namespace, @namespace.value)

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/alias_handler.rb

@@ -7,14 +7,15 @@ class YARD::Handlers::Ruby::AliasHandler < YARD::Handlers::Ruby::Base
   process do
     names = []
     if statement.type == :alias
-      names = statement.map {|o| o.jump(:ident, :op, :kw, :const).source }
+      nodes = [:ident, :op, :kw, :const, :tstring_content, :string_content]
+      names = statement.map {|o| o.jump(*nodes).source }
     elsif statement.call?
       statement.parameters(false).each do |obj|
         case obj.type
-        when :symbol_literal, :dyna_symbol
+        when :symbol_literal
           names << obj.jump(:ident, :op, :kw, :const).source
-        when :string_literal
-          names << obj.jump(:string_content).source
+        when :string_literal, :dyna_symbol
+          names << obj.jump(:string_content, :tstring_content).source
         end
       end
     end

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

@@ -45,7 +45,7 @@ class YARD::Handlers::Ruby::AttributeHandler < YARD::Handlers::Ruby::Base
           else
             src = "def #{meth}"
             full_src = "#{src}\n  @#{name}\nend"
-            doc = "Returns the value of attribute #{name}"
+            doc = "Returns the value of attribute #{name}."
           end
           o.source ||= full_src
           o.signature ||= src

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

@@ -20,11 +20,7 @@ class YARD::Handlers::Ruby::ConstantHandler < YARD::Handlers::Ruby::Base
 
   def process_constant(statement)
     name = statement[0].source
-    value = if statement[1].type == :dyna_symbol
-              statement[1].first.source.intern.inspect
-            else
-              statement[1].source
-            end
+    value = statement[1].source
     obj = P(namespace, name)
     if obj.is_a?(NamespaceObject) && obj.namespace == namespace
       raise YARD::Parser::UndocumentableError, "constant for existing #{obj.type} #{obj}"