yard 0.9.0 → 0.9.1

data/lib/yard/docstring_parser.rb

@@ -117,7 +117,7 @@ module YARD
       # Remove trailing/leading whitespace / newlines
       @text = text.gsub(/\A[\r\n\s]+|[\r\n\s]+\Z/, '')
       call_directives_after_parse
-      call_after_parse_callbacks
+      post_process
       self
     end
 
@@ -179,6 +179,17 @@ module YARD
       docstring
     end
 
+    # @!group Parser Callback Methods
+
+    # Call post processing callbacks on parser.
+    # This is called implicitly by parser. Use this when
+    # manually configuring a {Docstring} object.
+    #
+    # @return [void]
+    def post_process
+      call_after_parse_callbacks
+    end
+
     # @!group Tag Manipulation Methods
 
     # Creates a tag from the {Tags::DefaultFactory tag factory}.
@@ -296,6 +307,7 @@ module YARD
     after_parse do |parser|
       next unless parser.object
       next unless parser.object.is_a?(CodeObjects::MethodObject)
+      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}' " +
@@ -314,5 +326,20 @@ module YARD
         end
       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
+      end
+    end
   end
 end

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

@@ -75,6 +75,7 @@ module YARD
           {:read => name, :write => "#{name}="}.each do |type, meth_name|
             next unless values[type] > 0
             obj = handle_method(:instance, var_name, meth_name, nil)
+            register_file_info(obj, statement.file, statement.line)
             obj.namespace.attributes[:instance][name] ||= SymbolHash[:read => nil, :write => nil]
             obj.namespace.attributes[:instance][name][type] = obj
           end

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

@@ -7,7 +7,13 @@ class YARD::Handlers::C::MixinHandler < YARD::Handlers::C::Base
     statement.source.scan(MATCH) do |klass_var, mixin_var|
       namespace = namespace_for_variable(klass_var)
       ensure_loaded!(namespace)
-      namespace.mixins(:instance) << namespace_for_variable(mixin_var)
+
+      if var = namespace_for_variable(mixin_var)
+        namespace.mixins(:instance) << var
+      else
+        raise YARD::Parser::UndocumentableError,
+          "CRuby mixin for unrecognized variable '#{mixin_var}'"
+      end
     end
   end
 end

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

@@ -24,18 +24,19 @@ class YARD::Handlers::Ruby::AliasHandler < YARD::Handlers::Ruby::Base
     new_obj = register MethodObject.new(namespace, new_meth, scope) do |o|
       o.add_file(parser.file, statement.line)
     end
+    namespace.aliases[new_obj] = old_meth
 
     if old_obj
       new_obj.signature = old_obj.signature
       new_obj.source = old_obj.source
-      new_obj.docstring = old_obj.docstring + YARD::Docstring.new(statement.comments)
+      comments = [old_obj.docstring.to_raw, statement.comments].join("\n")
+      doc = YARD::Docstring.parser.parse(comments, new_obj, self)
+      new_obj.docstring = doc.to_docstring
       new_obj.docstring.line_range = statement.comments_range
       new_obj.docstring.hash_flag = statement.comments_hash_flag
       new_obj.docstring.object = new_obj
     else
       new_obj.signature = "def #{new_meth}" # this is all we know.
     end
-
-    namespace.aliases[new_obj] = old_meth
   end
 end

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

@@ -18,7 +18,12 @@ class YARD::Handlers::Ruby::ConstantHandler < YARD::Handlers::Ruby::Base
   def process_constant(statement)
     name = statement[0][0][0]
     value = statement[1].source
-    register ConstantObject.new(namespace, name) {|o| o.source = statement; o.value = value.strip }
+    obj = P(namespace, name)
+    if obj.is_a?(NamespaceObject)
+      raise YARD::Parser::UndocumentableError, "constant for existing #{obj.type} #{obj}"
+    else
+      register ConstantObject.new(namespace, name) {|o| o.source = statement; o.value = value.strip }
+    end
   end
 
   def process_structclass(statement)

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

@@ -15,14 +15,20 @@ module YARD
           @docstring = statement.comments || ""
           @docstring = @docstring.join("\n") if @docstring.is_a?(Array)
 
+          attaching = false
           if @docstring =~ /^@!?macro\s+\[[^\]]*attach/
             register_docstring(nil)
             @docstring = ""
+            attaching = true
           end
 
           if macro = find_attached_macro
-            @docstring += "\n" +
-              macro.expand([caller_method, *call_params], statement.source)
+            txt = macro.expand([caller_method, *call_params], statement.source)
+            @docstring += "\n" + txt
+
+            if !attaching && txt.match(/^\s*@!/) # macro has a directive
+              return register_docstring(nil)
+            end
           elsif !statement.comments_hash_flag && !implicit_docstring?
             return register_docstring(nil)
           end
@@ -64,13 +70,24 @@ module YARD
         def find_attached_macro
           Registry.all(:macro).each do |macro|
             next unless macro.method_object
-            next unless macro.method_object.name.to_s == caller_method.to_s
+            next unless macro_name_matches(macro)
             (namespace.inheritance_tree(true) + [P('Object')]).each do |obj|
               return macro if obj == macro.method_object.namespace
             end
           end
           nil
         end
+
+        # @return [Boolean] whether caller method matches a macro or
+        #   its alias names.
+        def macro_name_matches(macro)
+          objs = [macro.method_object]
+          if objs.first.type != :proxy && objs.first.respond_to?(:aliases)
+            objs.push(*objs.first.aliases)
+          end
+
+          objs.any? {|obj| obj.name.to_s == caller_method.to_s }
+        end
       end
     end
   end

data/lib/yard/parser/c/comment_parser.rb

@@ -28,7 +28,7 @@ module YARD
 
         def parse_overrides(comments)
           comments.map do |line|
-            type, name = *line.scan(/^\s*Document-(class|module|method|const):\s*(\S.*)\s*$/).first
+            type, name = *line.scan(/^\s*Document-(class|module|method|attr|const):\s*(\S.*)\s*$/).first
             if type
               @overrides << [type.to_sym, name]
               nil

data/lib/yard/parser/ruby/ruby_parser.rb

@@ -5,6 +5,7 @@ module YARD
     module Ruby
       # Ruby 1.9 parser
       # @!attribute [r] encoding_line
+      # @!attribute [r] frozen_string_line
       # @!attribute [r] shebang_line
       # @!attribute [r] enumerator
       class RubyParser < Parser::Base
@@ -17,13 +18,14 @@ module YARD
         def enumerator; @parser.enumerator end
         def shebang_line; @parser.shebang_line end
         def encoding_line; @parser.encoding_line end
+        def frozen_string_line; @parser.frozen_string_line end
       end
 
       # Internal parser class
       # @since 0.5.6
       class RipperParser < Ripper
         attr_reader :ast, :charno, :comments, :file, :tokens
-        attr_reader :shebang_line, :encoding_line
+        attr_reader :shebang_line, :encoding_line, :frozen_string_line
         alias root ast
 
         def initialize(source, filename, *args)
@@ -43,6 +45,7 @@ module YARD
           @charno = 0
           @shebang_line = nil
           @encoding_line = nil
+          @frozen_string_line = nil
           @file_encoding = nil
         end
 
@@ -194,7 +197,8 @@ module YARD
             begin; undef on_#{event}; rescue NameError; end
             def on_#{event}(tok)
               unless @last_ns_token == [:kw, "def"] ||
-                  (@tokens.last && @tokens.last[0] == :symbeg)
+                  (@tokens.last && @tokens.last[0] == :symbeg) ||
+                  (!@newline && %w(if while until unless).include?(tok))
                 (@map[tok] ||= []) << [lineno, charno]
               end
               visit_ns_token(:#{event}, tok, true)
@@ -202,16 +206,22 @@ module YARD
           eof
         end
 
-        [:sp, :nl, :ignored_nl].each do |event|
+        [:nl, :ignored_nl].each do |event|
           module_eval(<<-eof, __FILE__, __LINE__ + 1)
             begin; undef on_#{event}; rescue NameError; end
             def on_#{event}(tok)
               add_token(:#{event}, tok)
-              @charno += tok.length
+              @newline = true
+              @charno += tok ? tok.length : 1
             end
           eof
         end
 
+        def on_sp(tok)
+          add_token(:sp, tok)
+          @charno += tok.length
+        end
+
         def visit_event(node)
           map = @map[MAPPINGS[node.type]]
           lstart, sstart = *(map ? map.pop : [lineno, @ns_charno - 1])
@@ -239,6 +249,7 @@ module YARD
           @last_ns_token = [token, data]
           @charno += data.length
           @ns_charno = charno
+          @newline = [:semicolon, :comment, :kw, :op].include?(token)
           if ast_token
             AstNode.new(token, [data], :line => lineno..lineno, :char => ch..charno-1, :token => true)
           end
@@ -390,7 +401,7 @@ module YARD
           ReferenceNode.new(:const_path_ref, args, :listline => lineno..lineno, :listchar => charno..charno)
         end
 
-        [:if_mod, :unless_mod, :while_mod].each do |kw|
+        [:if_mod, :unless_mod, :while_mod, :until_mod].each do |kw|
           node_class = AstNode.node_class_for(kw)
           module_eval(<<-eof, __FILE__, __LINE__ + 1)
             begin; undef on_#{kw}; rescue NameError; end
@@ -489,6 +500,9 @@ module YARD
             elsif comment =~ SourceParser::ENCODING_LINE
               @encoding_line = comment
               not_comment = true
+            elsif comment =~ SourceParser::FROZEN_STRING_LINE
+              @frozen_string_line = comment
+              not_comment = true
             end
           end
 
@@ -557,6 +571,12 @@ module YARD
         def insert_comments
           root.traverse do |node|
             next if node.type == :comment || node.type == :list || node.parent.type != :list
+
+            # never attach comments to if/unless mod nodes
+            if node.type == :if_mod || node.type == :unless_mod
+              node = node.then_block
+            end
+
             # check upwards from line before node; check node's line at the end
             ((node.line-1).downto(node.line-2).to_a + [node.line]).each  do |line|
               comment = @comments[line]

data/lib/yard/parser/source_parser.rb

@@ -62,6 +62,7 @@ module YARD
     class SourceParser
       SHEBANG_LINE  = /\A\s*#!\S+/
       ENCODING_LINE = /\A(?:\s*#*!.*\r?\n)?\s*(?:#+|\/\*+|\/\/+).*coding\s*[:=]{1,2}\s*([a-z\d_\-]+)/i
+      FROZEN_STRING_LINE = /frozen(-|_)string(-|_)literal: true/i
 
       # The default glob of files to be parsed.
       # @since 0.9.0

data/lib/yard/registry.rb

@@ -30,7 +30,7 @@ module YARD
   #   Registry.resolve(P('YARD::CodeObjects::Base'), '#docstring', true)
   module Registry
     DEFAULT_YARDOC_FILE = ".yardoc"
-    LOCAL_YARDOC_INDEX = File.expand_path('~/.yard/gem_index')
+    LOCAL_YARDOC_INDEX = File.expand_path(File.join(Config::CONFIG_DIR, 'gem_index'))
     DEFAULT_PO_DIR = "po"
 
     extend Enumerable
@@ -61,10 +61,12 @@ module YARD
 
         if for_writing
           global_yardoc_file(spec, for_writing) ||
+            old_global_yardoc_file(spec, for_writing) ||
             local_yardoc_file(spec, for_writing)
         else
           local_yardoc_file(spec, for_writing) ||
-            global_yardoc_file(spec, for_writing)
+            global_yardoc_file(spec, for_writing) ||
+            old_global_yardoc_file(spec, for_writing)
         end
       end
 
@@ -276,47 +278,9 @@ module YARD
       # @return [nil] if +proxy_fallback+ is +false+ and no object was found.
       # @see P
       def resolve(namespace, name, inheritance = false, proxy_fallback = false, type = nil)
-        if namespace.is_a?(CodeObjects::Proxy)
-          return proxy_fallback ? CodeObjects::Proxy.new(namespace, name, type) : nil
-        end
-
-        if namespace == :root || !namespace
-          namespace = root
-        else
-          namespace = namespace.parent until namespace.is_a?(CodeObjects::NamespaceObject)
-        end
-        orignamespace = namespace
-
-        name = name.to_s
-        if name =~ /^#{CodeObjects::NSEPQ}/
-          [name, name[2..-1]].each do |n|
-            found = at(n)
-            return found if found && (type.nil? || found.type == type)
-          end
-        else
-          while namespace
-            if namespace.is_a?(CodeObjects::NamespaceObject)
-              if inheritance
-                nss = namespace.inheritance_tree(true)
-                if namespace.respond_to?(:superclass)
-                  if namespace.superclass != P('BasicObject')
-                    nss |= [P('Object')]
-                  end
-                  nss |= [P('BasicObject')]
-                end
-              else
-                nss = [namespace]
-              end
-              nss.each do |ns|
-                next if ns.is_a?(CodeObjects::Proxy)
-                found = partial_resolve(ns, name, type)
-                return found if found
-              end
-            end
-            namespace = namespace.parent
-          end
-        end
-        proxy_fallback ? CodeObjects::Proxy.new(orignamespace, name, type) : nil
+        thread_local_resolver.lookup_by_path name,
+          :namespace => namespace, :inheritance => inheritance,
+          :proxy_fallback => proxy_fallback, :type => type
       end
 
       # @group Managing Source File Checksums
@@ -402,6 +366,16 @@ module YARD
       # @group Retrieving yardoc File Locations
 
       def global_yardoc_file(spec, for_writing = false)
+        path = spec.doc_dir
+        yfile = spec.doc_dir(DEFAULT_YARDOC_FILE)
+        if for_writing && File.writable?(path)
+          return yfile
+        elsif !for_writing && File.exist?(yfile)
+          return yfile
+        end
+      end
+
+      def old_global_yardoc_file(spec, for_writing = false)
         path = spec.full_gem_path
         yfile = File.join(path, DEFAULT_YARDOC_FILE)
         if for_writing && File.writable?(path)
@@ -433,6 +407,11 @@ module YARD
       def thread_local_store=(value)
         Thread.current[:__yard_registry__] = value
       end
+
+      # @since 0.9.1
+      def thread_local_resolver
+        Thread.current[:__yard_resolver__] ||= RegistryResolver.new
+      end
     end
   end
 end

data/lib/yard/registry_resolver.rb

@@ -0,0 +1,171 @@
+module YARD
+  # Handles all logic for complex lexical and inherited object resolution.
+  # Used by {Registry.resolve}, so there is no need to use this class
+  # directly.
+  #
+  # @see Registry.resolve
+  class RegistryResolver
+    include CodeObjects::NamespaceMapper
+
+    # Creates a new resolver object for a registry.
+    #
+    # @param registry [Registry] only set this if customizing the registry
+    #   object
+    def initialize(registry = Registry)
+      @registry = Registry
+    end
+
+    # Performs a lookup on a given path in the registry. Resolution will occur
+    # in a similar way to standard Ruby identifier resolution, doing lexical
+    # lookup, as well as (optionally) through the inheritance chain. A proxy
+    # object can be returned if the lookup fails for future resolution. The
+    # proxy will be type hinted with the +type+ used in the original lookup.
+    #
+    # @option opts namespace [CodeObjects::Base, :root, nil] (nil) the namespace
+    #   object to start searching from. If root or nil is provided, {Registry.root}
+    #   is assumed.
+    # @option opts inheritance [Boolean] (false) whether to perform lookups through
+    #   the inheritance chain (includes mixins)
+    # @option opts proxy_fallback [Boolean] (false) when true, a proxy is returned
+    #   if no match is found
+    # @option opts type [Symbol] (nil) an optional type hint for the resolver
+    #   to consider when performing a lookup. If a type is provided and the
+    #   resolved object's type does not match the hint, the object is discarded.
+    # @return [CodeObjects::Base, CodeObjects::Proxy, nil] the first object
+    #   that matches the path lookup. If proxy_fallback is provided, a proxy
+    #   object will be returned in the event of no match, otherwise nil will
+    #   be returned.
+    # @example A lookup from root
+    #   resolver.lookup_by_path("A::B::C")
+    # @example A lookup from the A::B namespace
+    #   resolver.lookup_by_path("C", namespace: P("A::B"))
+    # @example A lookup on a method through the inheritance tree
+    #   resolver.lookup_by_math("A::B#foo", inheritance: true)
+    def lookup_by_path(path, opts = {})
+      path = path.to_s
+      namespace = opts[:namespace]
+      inheritance = opts[:inheritance] || false
+      proxy_fallback = opts[:proxy_fallback] || false
+      type = opts[:type]
+
+      if namespace.is_a?(CodeObjects::Proxy)
+        return proxy_fallback ? CodeObjects::Proxy.new(namespace, path, type) : nil
+      end
+
+      if namespace == :root || !namespace
+        namespace = @registry.root
+      else
+        namespace = namespace.parent until namespace.is_a?(CodeObjects::NamespaceObject)
+      end
+      orignamespace = namespace
+
+      if path =~ /\A#{default_separator}/
+        path, namespace = $', @registry.root
+      end
+
+      resolved = nil
+      while namespace && !resolved
+        resolved = lookup_path_direct(namespace, path, type)
+        resolved ||= lookup_path_inherited(namespace, path, type) if inheritance
+        namespace = namespace.parent
+      end
+
+      if proxy_fallback
+        resolved ||= CodeObjects::Proxy.new(orignamespace, path, type)
+      end
+
+      resolved
+    end
+
+    private
+
+    # return [Boolean] if the obj's type matches the provided type.
+    def validate(obj, type)
+      return !type || (obj && obj.type == type) ? obj : nil
+    end
+
+    # Performs a lexical lookup from a namespace for a path and a type hint.
+    def lookup_path_direct(namespace, path, type)
+      if namespace.root? && result = validate(@registry.at(path), type)
+        return result
+      end
+
+      if path =~ /\A(#{separators_match})/
+        return validate(@registry.at(namespace.path + path), type)
+      end
+
+      separators.each do |sep|
+        result = validate(@registry.at(namespace.path + sep + path), type)
+        return result if result
+      end
+
+      nil
+    end
+
+    # Performs a lookup through the inheritance chain on a path with a type hint.
+    def lookup_path_inherited(namespace, path, type)
+      resolved, last_obj, scopes, last_sep, pos = nil, namespace, [], nil, 0
+
+      if path =~ /\A(#{separators_match})/
+        last_sep, path = $1, $'
+      end
+
+      path.scan(/(.+?)(#{separators_match}|$)/).each do |part, sep|
+        cur_obj = nil
+        pos += "#{part}#{sep}".length
+        parsed_end = pos == path.length
+
+        if !last_obj || (!parsed_end && !last_obj.is_a?(CodeObjects::NamespaceObject))
+          break # can't continue
+        end
+
+        collect_namespaces(last_obj).each do |ns|
+          next if ns.is_a?(CodeObjects::Proxy)
+
+          found, search_seps = nil, []
+          scopes.each do |scope|
+            search_seps += separators_for_type(scope)
+          end
+
+          if search_seps.empty?
+            if ns.type == :root
+              search_seps = [""]
+            elsif last_sep.nil?
+              search_seps = separators
+            else
+              search_seps = [@default_sep]
+            end
+          end
+
+          ([last_sep] | search_seps).compact.each do |search_sep|
+            break if found = @registry.at(ns.path + search_sep.to_s + part) 
+          end
+
+          break cur_obj = found if found
+        end
+
+        last_sep = sep
+        scopes = types_for_separator(sep) || []
+        last_obj = cur_obj
+        resolved = cur_obj if parsed_end && cur_obj && (type.nil? || type == cur_obj.type)
+      end
+
+      resolved
+    end
+
+    # Collects and returns all inherited namespaces for a given object
+    def collect_namespaces(object)
+      return [] if !object
+
+      nss = object.inheritance_tree(true)
+      if object.respond_to?(:superclass)
+        if object.superclass != P('BasicObject')
+          nss |= [P('Object')]
+        end
+        nss |= [P('BasicObject')]
+      end
+
+      nss
+    end
+  end
+end