yard 0.9.0 → 0.9.1

data/lib/yard/version.rb

@@ -1,3 +1,3 @@
 module YARD
-  VERSION = '0.9.0'
+  VERSION = '0.9.1'
 end

data/spec/cli/stats_spec.rb

@@ -10,6 +10,8 @@ describe YARD::CLI::Stats do
 
         def foo; end
 
+        attr_reader :fooattr
+
         # Documented
         def bar; end
       end
@@ -21,8 +23,9 @@ describe YARD::CLI::Stats do
       "Modules:         1 (    1 undocumented)\n" +
       "Classes:         1 (    1 undocumented)\n" +
       "Constants:       1 (    1 undocumented)\n" +
+      "Attributes:      1 (    0 undocumented)\n" +
       "Methods:         2 (    1 undocumented)\n" +
-      " 20.00% documented\n"
+      " 33.33% documented\n"
 
     @output = StringIO.new
     @stats = CLI::Stats.new(false)
@@ -56,6 +59,7 @@ eof
                               "Modules:         0 (    0 undocumented)\n" +
                               "Classes:         0 (    0 undocumented)\n" +
                               "Constants:       0 (    0 undocumented)\n" +
+                              "Attributes:      0 (    0 undocumented)\n" +
                               "Methods:         1 (    0 undocumented)\n" +
                               " 100.00% documented\n"
   end
@@ -65,7 +69,7 @@ eof
     expect(@output.string).to eq <<-eof
 #{@main_stats}
 Undocumented Objects:
-B            ((stdin):9)
+B            ((stdin):11)
 A            ((stdin):1)
 A::CONST     ((stdin):2)
 A#foo        ((stdin):4)
@@ -84,7 +88,8 @@ eof
       "Modules:         0 (    0 undocumented)\n" +
       "Classes:         0 (    0 undocumented)\n" +
       "Constants:       0 (    0 undocumented)\n" +
+      "Attributes:      0 (    0 undocumented)\n" +
       "Methods:         0 (    0 undocumented)\n" +
       " 100.00% documented\n")
   end
-end
+end

data/spec/code_objects/base_spec.rb

@@ -223,9 +223,17 @@ describe YARD::CodeObjects::Base do
   describe "#format" do
     it "sends object to Templates.render" do
       object = MethodObject.new(:root, :method)
-      expect(Templates::Engine).to receive(:render).with(:x => 1, :object => object)
+      expect(Templates::Engine).to receive(:render).with(:x => 1, :object => object, :type => object.type)
       object.format :x => 1
     end
+
+    it "does not change options object class" do
+      opts = YARD::Templates::TemplateOptions.new
+      opts.type = "test"
+      object = MethodObject.new(:root, :method)
+      expect(Templates::Engine).to receive(:render).with kind_of(YARD::Templates::TemplateOptions)
+      object.format(opts)
+    end
   end
 
   describe "#source_type" do

data/spec/docstring_parser_spec.rb

@@ -199,7 +199,7 @@ eof
     end
   end
 
-  describe "after_parse" do
+  describe "after_parse (param)" do
     it "allows specifying of callbacks" do
       parser = DocstringParser.new
       the_yielded_obj = nil
@@ -216,6 +216,15 @@ eof
       eof
     end
 
+    it "warns about invalid named parameters on @!method directives" do
+      expect(log).to receive(:warn).with(/@param tag has unknown parameter name: notaparam/)
+      YARD.parse_string <<-eof
+        # @!method foo(a)
+        #   @param notaparam foo
+        test
+      eof
+    end
+
     it "warns about duplicate named parameters" do
       expect(log).to receive(:warn).with(/@param tag has duplicate parameter name: a/)
       YARD.parse_string <<-eof
@@ -224,5 +233,31 @@ eof
         def foo(a) end
       eof
     end
+
+    it "does not warn on aliases" do
+      expect(log).to_not receive(:warn)
+      YARD.parse_string <<-eof
+        # @param a foo
+        def foo(a) end
+        alias bar foo
+      eof
+    end
+  end
+
+  describe "after_parse (see)" do
+    it "does not warn on valid see tag" do
+      expect(log).to_not receive(:warn)
+      YARD.parse_string "# @see valid\nclass Foo;end"
+    end
+
+    it "warns if {} wraps single name" do
+      expect(log).to receive(:warn).with(/@see tag \(#1\) should not be wrapped in \{\}/)
+      YARD.parse_string "# @see {invalid}\nclass Foo;end"
+    end
+
+    it "warns if {} wraps across name and text" do
+      expect(log).to receive(:warn).with(/@see tag \(#1\) should not be wrapped in \{\}/)
+      YARD.parse_string "# @see {invalid tag}\nclass Foo;end"
+    end
   end
 end

data/spec/docstring_spec.rb

@@ -52,14 +52,9 @@ describe YARD::Docstring do
       5.times { expect(o1.summary).to eq "Hello." }
     end
 
-    it "strips HTML before summarizing" do
-      doc = Docstring.new("<p>Hello <b>world</b></p>.")
-      expect(doc.summary).to eq 'Hello world.'
-    end
-
     it "strips newlines in first paragraph before summarizing" do
       doc = Docstring.new("Foo\n<code>==</code> bar.")
-      expect(doc.summary).to eq 'Foo == bar.'
+      expect(doc.summary).to eq 'Foo <code>==</code> bar.'
     end
 
     it "returns the first sentence" do

data/spec/handlers/c/mixin_handler_spec.rb

@@ -24,4 +24,20 @@ describe YARD::Handlers::C::MixinHandler do
     foo = Registry.at('Foo')
     expect(foo.mixins(:instance)).to eq [P('XYZ')]
   end
+
+  it "fails if mixin variable cannot be detected" do
+    with_parser(:c) do
+      undoc_error <<-eof
+        void Init_Foo() {
+          VALUE noprefix;
+
+          mFoo = rb_define_module("Foo");
+          // YARD doesn't understand this
+          noprefix = rb_const_get(rb_cObject, rb_intern("Observable"));
+
+          rb_include_module(mFoo, noprefix);
+        }
+      eof
+    end
+  end
 end

data/spec/handlers/constant_handler_spec.rb

@@ -64,4 +64,13 @@ describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}ConstantHandle
   it "raises undocumentable error in 1.9 parser for Struct.new assignment to non-const" do
     undoc_error "nonconst = Struct.new"
   end unless LEGACY_PARSER
+
+  %w(module class).each do |type|
+    it "does not allow #{type} to be redefined as constant" do
+      undoc_error <<-eof
+        #{type} Foo; end
+        Foo = "value"
+      eof
+    end
+  end unless LEGACY_PARSER
 end

data/spec/handlers/dsl_handler_spec.rb

@@ -193,4 +193,22 @@ describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}DSLHandler" do
       dsl_method '/foo/bar'
     eof
   end
+
+  # @note Currently unsupported behavior. Overriding a macro on an alias will
+  #   not work until macro lookups can be done by caller_method directly.
+  # @todo optimize MacroObject lookup to work by caller name, not macro name.
+  it "cannot attach a macro on alias of attached macro" do
+    expect(Registry.at('AliasTest#main_foo1')).not_to be nil
+    expect(Registry.at('AliasTest#alt_foo1')).to be nil
+  end if HAVE_RIPPER
+
+  it "searches attached macro's aliases for caller method match" do
+    expect(Registry.at('AliasTest#main_foo2')).not_to be nil
+    expect(Registry.at('AliasTest#alt_foo2')).to be nil
+  end if HAVE_RIPPER
+
+  it "does not create method object if directive data detected in expanded macro" do
+    expect(Registry.at('DirectiveMethods#Bar')).to be nil
+    expect(Registry.at('DirectiveMethods').mixins).to include P(:Bar)
+  end
 end

data/spec/handlers/examples/dsl_handler_001.rb.txt

@@ -123,3 +123,32 @@ module DSLMethods
   dsl_method :foo, String
   dsl_method :bar, Integer
 end
+
+class AliasTest
+  class << self
+    # @!macro alias_main
+    #   @!method main_$1
+    #     Success main_$1
+    def main; end
+
+    # TODO: currently unsupported behavior
+    # @!macro alias_alt
+    #   @!method alias_$1
+    #     Success alias_$1
+    alias alt main
+
+    alias alt2 main
+  end
+
+  alt  :foo1
+  alt2 :foo2
+end
+
+class DirectiveMethods
+  # @!macro with_directive
+  #   @!parse
+  #     include $1
+  def self.attach(x) end
+
+  attach Bar
+end

data/spec/parser/ruby/ruby_parser_spec.rb

@@ -381,5 +381,47 @@ eof
       expect(Registry.at("Foo::CONST1").docstring).to eq "Comment here"
       expect(Registry.at("Foo::CONST2").docstring).to eq "Another comment here"
     end
+
+    %w(if unless).each do |type|
+      it "does not get confused by modifier '#{type}' statements" do
+        Registry.clear
+        ast = YARD.parse_string(<<-eof).enumerator
+          module Foo
+            #{type} test?
+              # Docstring
+              class Bar
+                # Docstring2
+                def foo
+                  x #{type} true
+                end
+              end
+            end
+          end
+        eof
+
+        expect(Registry.at("Foo::Bar").docstring).to eq "Docstring"
+        expect(Registry.at("Foo::Bar#foo").docstring).to eq "Docstring2"
+      end
+
+      it "does not add comment blocks to #{type}_mod nodes" do
+        Registry.clear
+        ast = YARD.parse_string(<<-eof).enumerator
+          class Foo
+            # Docstring
+            def bar; end if true
+          end
+        eof
+
+        expect(Registry.at("Foo#bar").docstring).to eq "Docstring"
+      end
+    end
+
+    it "removes frozen string line from initial file comments" do
+      YARD.parse_string "# frozen_string_literal: true\n# this is a comment\nclass Foo; end"
+      YARD.parse_string "# Frozen-string-literal: true\n# this is a comment\nclass Bar; end"
+
+      expect(Registry.at(:Foo).docstring).to eq "this is a comment"
+      expect(Registry.at(:Bar).docstring).to eq "this is a comment"
+    end
   end
 end if HAVE_RIPPER

data/spec/registry_spec.rb

@@ -12,6 +12,8 @@ describe YARD::Registry do
       allow(@gem).to receive(:name).and_return('foo')
       allow(@gem).to receive(:full_name).and_return('foo-1.0')
       allow(@gem).to receive(:full_gem_path).and_return('/path/to/foo')
+      allow(@gem).to receive(:doc_dir).and_return('/path/to/foo/doc')
+      allow(@gem).to receive(:doc_dir).with('.yardoc').and_return('/path/to/foo/doc/.yardoc')
     end
 
     it "returns nil if gem isn't found" do
@@ -25,14 +27,21 @@ describe YARD::Registry do
     end
 
     it "returns existing .yardoc path for gem when for_writing=false" do
-      expect(File).to receive(:exist?).and_return(false)
+      expect(File).to receive(:exist?).twice.and_return(false)
       expect(File).to receive(:exist?).with('/path/to/foo/.yardoc').and_return(true)
       expect(Gem.source_index).to receive(:find_name).with('foo', '>= 0').and_return([@gem])
       expect(Registry.yardoc_file_for_gem('foo')).to eq '/path/to/foo/.yardoc'
     end
 
+    it "returns new existing .yardoc path for gem when for_writing=false" do
+      expect(File).to receive(:exist?).once.and_return(false)
+      expect(File).to receive(:exist?).with('/path/to/foo/doc/.yardoc').and_return(true)
+      expect(Gem.source_index).to receive(:find_name).with('foo', '>= 0').and_return([@gem])
+      expect(Registry.yardoc_file_for_gem('foo')).to eq '/path/to/foo/doc/.yardoc'
+    end
+
     it "returns nil if no .yardoc path exists in gem when for_writing=false" do
-      expect(File).to receive(:exist?).and_return(false)
+      expect(File).to receive(:exist?).twice.and_return(false)
       expect(File).to receive(:exist?).with('/path/to/foo/.yardoc').and_return(false)
       expect(Gem.source_index).to receive(:find_name).with('foo', '>= 0').and_return([@gem])
       expect(Registry.yardoc_file_for_gem('foo')).to eq nil
@@ -45,12 +54,20 @@ describe YARD::Registry do
     end
 
     it "returns global .yardoc path for gem if for_writing=true and dir is writable" do
+      expect(File).to receive(:writable?).with(@gem.doc_dir).and_return(false)
       expect(File).to receive(:writable?).with(@gem.full_gem_path).and_return(true)
       expect(Gem.source_index).to receive(:find_name).with('foo', '>= 0').and_return([@gem])
       expect(Registry.yardoc_file_for_gem('foo', '>= 0', true)).to eq '/path/to/foo/.yardoc'
     end
 
+    it "returns new global .yardoc path for gem if for_writing=true and dir is writable" do
+      expect(File).to receive(:writable?).with(@gem.doc_dir).and_return(true)
+      expect(Gem.source_index).to receive(:find_name).with('foo', '>= 0').and_return([@gem])
+      expect(Registry.yardoc_file_for_gem('foo', '>= 0', true)).to eq '/path/to/foo/doc/.yardoc'
+    end
+
     it "returns local .yardoc path for gem if for_writing=true and dir is not writable" do
+      expect(File).to receive(:writable?).with(@gem.doc_dir).and_return(false)
       expect(File).to receive(:writable?).with(@gem.full_gem_path).and_return(false)
       expect(Gem.source_index).to receive(:find_name).with('foo', '>= 0').and_return([@gem])
       expect(Registry.yardoc_file_for_gem('foo', '>= 0', true)).to match %r{/.yard/gem_index/foo-1.0.yardoc$}
@@ -123,6 +140,18 @@ describe YARD::Registry do
       expect(Registry.resolve(:root, 'methname')).to eq o
     end
 
+    it "does lexical lookup on the initial namespace" do
+      YARD.parse_string <<-eof
+        module A
+          module B; module C; end end
+          module D; module E; end end
+        end
+      eof
+
+      d = Registry.at('A::B::C')
+      expect(Registry.resolve(d, 'D::E')).to eq Registry.at('A::D::E')
+    end
+
     it "resolves superclass methods when inheritance = true" do
       superyard = ClassObject.new(:root, :SuperYard)
       yard = ClassObject.new(:root, :YARD)
@@ -178,6 +207,20 @@ describe YARD::Registry do
       expect(Registry.resolve(P('MyObject'), '#foo', true)).to be nil
     end
 
+    it "performs lookups on each individual namespace when inheritance = true" do
+      YARD.parse_string <<-eof
+        module A
+          module B; include A::D end
+          module C; extend A::D end
+          module D; def bar; end end
+        end
+      eof
+
+      r = Registry.root
+      expect(Registry.resolve(r, 'A::B#bar', true)).to eq Registry.at('A::D#bar')
+      expect(Registry.resolve(r, 'A::C.bar', true)).to eq Registry.at('A::D#bar')
+    end
+
     it "allows type=:typename to ensure resolved object is of a certain type" do
       YARD.parse_string "class Foo; end"
       expect(Registry.resolve(Registry.root, 'Foo')).to eq Registry.at('Foo')
@@ -191,7 +234,7 @@ describe YARD::Registry do
           def self.Bar; end
         end
       eof
-      expect(Registry.resolve(P('Foo'), 'Bar')).to eq Registry.at('Foo::Bar')
+      expect(Registry.resolve(P('Foo'), 'Bar', false, false, :class)).to eq Registry.at('Foo::Bar')
       expect(Registry.resolve(P('Foo'), 'Bar', false, false, :method)).to eq(
         Registry.at('Foo.Bar'))
     end

data/spec/server/router_spec.rb

@@ -116,7 +116,7 @@ describe YARD::Server::Router do
     end
 
     it "searches static files for non-existent library" do
-      route_to('/mydocs/foo/notproject', StaticFileCommand)
+      route_to('/mydocs/foo/notproject', RootRequestCommand)
     end
   end
 end

data/spec/server_spec.rb

@@ -6,5 +6,14 @@ describe YARD::Server do
       YARD::Server.register_static_path 'foo'
       expect(YARD::Server::Commands::StaticFileCommand::STATIC_PATHS.last).to eq "foo"
     end
+
+    it "does not duplicate paths" do
+      paths = YARD::Server::Commands::StaticFileCommand::STATIC_PATHS
+      count = paths.size
+      YARD::Server.register_static_path 'foo2'
+      YARD::Server.register_static_path 'foo2'
+      expect(paths.size).to eq(count + 1)
+      expect(paths.last).to eq 'foo2'
+    end
   end
 end

data/spec/tags/default_factory_spec.rb

@@ -41,6 +41,11 @@ describe YARD::Tags::DefaultFactory do
       expect(parse_types('b c <String> description (test)')).to eq [nil, nil, 'b c <String> description (test)']
     end
 
+    it "does not allow types to start after a newline" do
+      v = parse_types("   \n   [X]")
+      expect(v).to eq [nil, nil, "[X]"]
+    end
+
     it "handles a complex list of types" do
       v = parse_types(' [Test, Array<String, Hash, C>, String]')
       expect(v).to include(["Test", "Array<String, Hash, C>", "String"])

data/spec/templates/engine_spec.rb

@@ -1,11 +1,21 @@
 require File.dirname(__FILE__) + '/spec_helper'
 
 describe YARD::Templates::Engine do
+  before { @paths = Engine.template_paths }
+  after { Engine.template_paths = @paths }
+
   describe ".register_template_path" do
     it "registers a String path" do
       Engine.register_template_path('.')
       expect(Engine.template_paths.pop).to eq '.'
     end
+
+    it "does not duplicate paths" do
+      Engine.template_paths = []
+      Engine.register_template_path('foo')
+      Engine.register_template_path('foo')
+      expect(Engine.template_paths).to eq ['foo']
+    end
   end
 
   describe ".template!" do