yard 0.9.5 → 0.9.6

data/lib/yard/core_ext/array.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 class Array
   # Places values before or after another object (by value) in
   # an array. This is used in tandem with the before and after

data/lib/yard/core_ext/file.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'fileutils'
 
 class File
@@ -36,7 +37,7 @@ class File
     path = path.split(SEPARATOR)
     path = path.inject([]) do |acc, comp|
       next acc if comp == RELATIVE_SAMEDIR
-      if comp == RELATIVE_PARENTDIR && acc.size > 0 && acc.last != RELATIVE_PARENTDIR
+      if comp == RELATIVE_PARENTDIR && !acc.empty? && acc.last != RELATIVE_PARENTDIR
         acc.pop
         next acc
       end
@@ -60,6 +61,6 @@ class File
   # @return [String] the ascii-8bit encoded data
   # @since 0.5.3
   def self.read_binary(file)
-    File.open(file, 'rb') {|f| f.read }
+    File.open(file, 'rb', &:read)
   end
-end
+end

data/lib/yard/core_ext/hash.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 class Hash
   class << self
     def create(*args)
@@ -9,7 +10,7 @@ class Hash
         create_186(*args)
       end
     end
-    alias :create_186 :[]
-    alias :[] :create
+    alias create_186 []
+    alias [] create
   end
 end if RUBY_VERSION < "1.8.7"

data/lib/yard/core_ext/insertion.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 # The Insertion class inserts a value before or after another
 # value in a list.
 #
@@ -10,7 +11,10 @@ class Insertion
   #
   # @param [Array] list the list to perform the insertion on
   # @param [Object] value the value to insert
-  def initialize(list, value) @list, @values = list, (Array === value ? value : [value]) end
+  def initialize(list, value)
+    @list = list
+    @values = (Array === value ? value : [value])
+  end
 
   # Inserts the value before +val+
   # @param [Object] val the object the value will be inserted before
@@ -52,9 +56,8 @@ class Insertion
       end
     end
 
-    if index = list.index(val)
-      list[index+rel,0] = @values
-    end
+    index = list.index(val)
+    list[index + rel, 0] = @values if index
     list
   end
 end

data/lib/yard/core_ext/module.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 class Module
   # Returns the class name of a full module namespace path
   #
@@ -16,4 +17,4 @@ class Module
   def namespace_name
     name.split("::")[0..-2].join("::")
   end
-end
+end

data/lib/yard/core_ext/string.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 class String
   # Splits text into tokens the way a shell would, handling quoted
   # text as a single token. Use '\"' and "\'" to escape quotes and
@@ -5,16 +6,16 @@ class String
   #
   # @return [Array] an array representing the tokens
   def shell_split
-    out = [""]
+    out = [String.new("")]
     state = :none
     escape_next = false
-    quote = ""
+    quote = String.new("")
     strip.split(//).each do |char|
       case state
       when :none, :space
         case char
         when /\s/
-          out << "" unless state == :space
+          out << String.new("") unless state == :space
           state = :space
           escape_next = false
         when "\\"
@@ -30,7 +31,7 @@ class String
             escape_next = false
           else
             state = char
-            quote = ""
+            quote = String.new("")
           end
         else
           state = :none

data/lib/yard/core_ext/symbol_hash.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 # A subclass of Hash where all keys are converted into Symbols, and
 # optionally, all String values are converted into Symbols.
 class SymbolHash < Hash
@@ -25,11 +26,11 @@ class SymbolHash < Hash
   #   @param [Array] list an even list of key followed by value
   #   @return [SymbolHash] a new SymbolHash object
   def self.[](*hsh)
-    obj = new;
+    obj = new
     if hsh.size == 1 && hsh.first.is_a?(Hash)
-      hsh.first.each {|k,v| obj[k] = v }
+      hsh.first.each {|k, v| obj[k] = v }
     else
-      0.step(hsh.size, 2) {|n| obj[hsh[n]] = hsh[n+1] }
+      0.step(hsh.size, 2) {|n| obj[hsh[n]] = hsh[n + 1] }
     end
     obj
   end
@@ -55,15 +56,16 @@ class SymbolHash < Hash
   # Tests if a symbolized key exists
   # @param [#to_sym] key the key to test
   # @return [Boolean] whether the key exists
-  def has_key?(key) super(key.to_sym) end
+  def key?(key) super(key.to_sym) end
+  alias has_key? key?
 
   # Updates the object with the contents of another Hash object.
   # This method modifies the original SymbolHash object
   #
   # @param [Hash] hash the hash object to copy the values from
   # @return [SymbolHash] self
-  def update(hash) hash.each {|k,v| self[k] = v }; self end
-  alias_method :merge!, :update
+  def update(hash) hash.each {|k, v| self[k] = v }; self end
+  alias merge! update
 
   # Merges the contents of another hash into a new SymbolHash object
   #

data/lib/yard/docstring.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module YARD
   # A documentation string, or "docstring" for short, encapsulates the
   # comments and metadata, or "tags", of an object. Meta-data is expressed
@@ -53,7 +54,7 @@ module YARD
 
     # @return [Boolean] whether the docstring was started with "##"
     attr_reader :hash_flag
-    def hash_flag=(v) @hash_flag = v == nil ? false : v end
+    def hash_flag=(v) @hash_flag = v.nil? ? false : v end
 
     # Matches a tag at the start of a comment line
     # @deprecated Use {DocstringParser::META_MATCH}
@@ -130,7 +131,8 @@ module YARD
     # @param [String] content the raw comments to be parsed
     def replace(content, parse = true)
       content = content.join("\n") if content.is_a?(Array)
-      @tags, @ref_tags = [], []
+      @tags = []
+      @ref_tags = []
       if parse
         super(parse_comments(content))
       else
@@ -152,7 +154,7 @@ module YARD
       resolve_reference
       obj = super
       %w(all summary tags ref_tags).each do |name|
-        val = instance_variable_get("@#{name}")
+        val = instance_variable_defined?("@#{name}") && instance_variable_get("@#{name}")
         obj.instance_variable_set("@#{name}", val ? val.dup : nil)
       end
       obj
@@ -170,8 +172,8 @@ module YARD
     # @return [String] The first line or paragraph of the docstring; always ends with a period.
     def summary
       resolve_reference
-      return @summary if @summary
-      stripped = self.gsub(/[\r\n](?![\r\n])/, ' ').strip
+      return @summary if defined?(@summary) && @summary
+      stripped = gsub(/[\r\n](?![\r\n])/, ' ').strip
       num_parens = 0
       idx = length.times do |index|
         case stripped[index, 1]
@@ -181,11 +183,7 @@ module YARD
         when "\r", "\n"
           next_char = stripped[index + 1, 1].to_s
           if next_char =~ /^\s*$/
-            if stripped[index - 1, 1] == '.'
-              break index - 2
-            else
-              break index - 1
-            end
+            break stripped[index - 1, 1] == '.' ? index - 2 : index - 1
           end
         when "{", "(", "["
           num_parens += 1
@@ -207,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 {|t| t.tag_name }.map do |tag|
+      tag_data = tags.sort_by(&:tag_name).map do |tag|
         case tag
         when Tags::OverloadTag
           tag_text = "@#{tag.tag_name} #{tag.signature}\n"
@@ -230,7 +228,7 @@ module YARD
         end
         tag_text
       end
-      [strip, tag_data.join("\n")].reject {|l| l.empty? }.compact.join("\n")
+      [strip, tag_data.join("\n")].reject(&:empty?).compact.join("\n")
     end
 
     # @group Creating and Accessing Meta-data
@@ -329,10 +327,11 @@ module YARD
     # @return [void]
     def resolve_reference
       loop do
-        return if @unresolved_reference.nil?
+        return if defined?(@unresolved_reference).nil? || @unresolved_reference.nil?
         return if CodeObjects::Proxy === @unresolved_reference
 
-        reference, @unresolved_reference = @unresolved_reference, nil
+        reference = @unresolved_reference
+        @unresolved_reference = nil
         self.all = [reference.docstring.all, @all].join("\n")
       end
     end
@@ -344,7 +343,19 @@ module YARD
     # @return [Array<Tags::RefTag>] the list of valid reference tags
     def convert_ref_tags
       list = @ref_tags.reject {|t| CodeObjects::Proxy === t.owner }
-      list.map {|t| t.tags }.flatten
+
+      @ref_tag_recurse_count ||= 0
+      @ref_tag_recurse_count += 1
+      if @ref_tag_recurse_count > 2
+        log.error "#{@object.file}:#{@object.line}: Detected circular reference tag in " \
+                  "`#{@object}', ignoring all reference tags for this object " \
+                  "(#{@ref_tags.map {|t| "@#{t.tag_name}" }.join(", ")})."
+        @ref_tags = []
+        return @ref_tags
+      end
+      list = list.map(&:tags).flatten
+      @ref_tag_recurse_count -= 1
+      list
     end
 
     # Parses out comments split by newlines into a new code object

data/lib/yard/docstring_parser.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'ostruct'
 
 module YARD
@@ -129,15 +130,17 @@ module YARD
     def parse_content(content)
       content = content.split(/\r?\n/) if content.is_a?(String)
       return '' if !content || content.empty?
-      docstring = ""
+      docstring = String.new("")
 
-      indent, last_indent = content.first[/^\s*/].length, 0
+      indent = content.first[/^\s*/].length
+      last_indent = 0
       orig_indent = 0
       directive = false
       last_line = ""
-      tag_name, tag_klass, tag_buf = nil, nil, []
+      tag_name = nil
+      tag_buf = []
 
-      (content+['']).each_with_index do |line, index|
+      (content + ['']).each_with_index do |line, index|
         indent = line[/^\s*/].length
         empty = (line =~ /^\s*$/ ? true : false)
         done = content.size == index
@@ -153,13 +156,17 @@ module YARD
           else
             create_tag(tag_name, buf)
           end
-          tag_name, tag_buf, directive = nil, [], false
+          tag_name = nil
+          tag_buf = []
+          directive = false
           orig_indent = 0
         end
 
         # Found a meta tag
         if line =~ META_MATCH
-          directive, tag_name, tag_buf = $1, $2, [($3 || '')]
+          directive = $1
+          tag_name = $2
+          tag_buf = [($3 || '')]
         elsif tag_name && indent >= orig_indent && !empty
           orig_indent = indent if orig_indent == 0
           # Extra data added to the tag on the next line
@@ -169,7 +176,8 @@ module YARD
           tag_buf << line.gsub(/^[ \t]{#{orig_indent}}/, '')
         elsif !tag_name
           # Regular docstring text
-          docstring << line << "\n"
+          docstring << line
+          docstring << "\n"
         end
 
         last_indent = indent
@@ -208,11 +216,11 @@ module YARD
         @tags += [library.tag_create(tag_name, tag_buf)].flatten
       else
         log.warn "Unknown tag @#{tag_name}" +
-          (object ? " in file `#{object.file}` near line #{object.line}" : "")
+                 (object ? " in file `#{object.file}` near line #{object.line}" : "")
       end
     rescue Tags::TagFormatError
       log.warn "Invalid tag format for @#{tag_name}" +
-        (object ? " in file `#{object.file}` near line #{object.line}" : "")
+               (object ? " in file `#{object.file}` near line #{object.line}" : "")
     end
 
     # Creates a {Tags::RefTag}
@@ -231,12 +239,12 @@ module YARD
         end
       else
         log.warn "Unknown directive @!#{tag_name}" +
-          (object ? " in file `#{object.file}` near line #{object.line}" : "")
+                 (object ? " in file `#{object.file}` near line #{object.line}" : "")
         nil
       end
     rescue Tags::TagFormatError
       log.warn "Invalid directive format for @!#{tag_name}" +
-        (object ? " in file `#{object.file}` near line #{object.line}" : "")
+               (object ? " in file `#{object.file}` near line #{object.line}" : "")
       nil
     end
 
@@ -247,44 +255,6 @@ module YARD
       list.include?(tag_name)
     end
 
-    private
-
-    def namespace
-      if object
-        object.namespace
-      else
-        nil
-      end
-    end
-
-    def detect_reference(content)
-      if content =~ /\A\s*\(see (\S+)\s*\)(?:\s|$)/
-        path, extra = $1, $'
-        [CodeObjects::Proxy.new(namespace, path), extra]
-      else
-        [nil, content]
-      end
-    end
-
-    # @!group Parser Callback Methods
-
-    # Calls the {Tags::Directive#after_parse} callback on all the
-    # created directives.
-    def call_directives_after_parse
-      directives.each do |dir|
-        dir.after_parse
-      end
-    end
-
-    # Calls all {after_parse} callbacks
-    def call_after_parse_callbacks
-      self.class.after_parse_callbacks.each do |cb|
-        cb.call(self)
-      end
-    end
-
-    public
-
     # Creates a callback that is called after a docstring is successfully
     # parsed. Use this method to perform sanity checks on a docstring's
     # tag data, or add any extra tags automatically to a docstring.
@@ -295,7 +265,7 @@ module YARD
     # @yieldreturn [void]
     # @return [void]
     def self.after_parse(&block)
-      self.after_parse_callbacks << block
+      after_parse_callbacks << block
     end
 
     # @return [Array<Proc>] the {after_parse} callback proc objects
@@ -310,35 +280,65 @@ module YARD
       next if parser.object.is_alias?
       names = parser.object.parameters.map {|l| l.first.gsub(/\W/, '') }
       seen_names = []
-      infile_info = "\n    in file `#{parser.object.file}' " +
+      infile_info = "\n    in file `#{parser.object.file}' " \
                     "near line #{parser.object.line}"
       parser.tags.each do |tag|
         next if tag.is_a?(Tags::RefTagList) # we don't handle this yet
         next unless tag.tag_name == "param"
         if seen_names.include?(tag.name)
-          log.warn "@param tag has duplicate parameter name: " +
-            "#{tag.name} #{infile_info}"
+          log.warn "@param tag has duplicate parameter name: " \
+                   "#{tag.name} #{infile_info}"
         elsif names.include?(tag.name)
           seen_names << tag.name
         else
-          log.warn "@param tag has unknown parameter name: " +
-            "#{tag.name} #{infile_info}"
+          log.warn "@param tag has unknown parameter name: " \
+                   "#{tag.name} #{infile_info}"
         end
       end
     end
 
+    private
+
+    def namespace
+      object && object.namespace
+    end
+
+    def detect_reference(content)
+      if content =~ /\A\s*\(see (\S+)\s*\)(?:\s|$)/
+        path = $1
+        extra = $'
+        [CodeObjects::Proxy.new(namespace, path), extra]
+      else
+        [nil, content]
+      end
+    end
+
+    # @!group Parser Callback Methods
+
+    # Calls the {Tags::Directive#after_parse} callback on all the
+    # created directives.
+    def call_directives_after_parse
+      directives.each(&:after_parse)
+    end
+
+    # Calls all {after_parse} callbacks
+    def call_after_parse_callbacks
+      self.class.after_parse_callbacks.each do |cb|
+        cb.call(self)
+      end
+    end
+
     # Define a callback to check that @see tags do not use {}.
     after_parse do |parser|
       next unless parser.object
 
       parser.tags.each_with_index do |tag, i|
         next unless tag.tag_name == "see"
-        if "#{tag.name}#{tag.text}" =~ /\A\{.*\}\Z/
-          infile_info = "\n    in file `#{parser.object.file}' " +
-                "near line #{parser.object.line}"
-          log.warn "@see tag (##{i+1}) should not be wrapped in {} " +
-            "(causes rendering issues): #{infile_info}"
-        end
+        next unless "#{tag.name}#{tag.text}" =~ /\A\{.*\}\Z/
+        infile_info = "\n    in file `#{parser.object.file}' " \
+                      "near line #{parser.object.line}"
+        log.warn "@see tag (##{i + 1}) should not be wrapped in {} " \
+                 "(causes rendering issues): #{infile_info}"
       end
     end
   end