yard 0.7.5 → 0.8.0

data/spec/handlers/class_variable_handler_spec.rb

@@ -2,7 +2,7 @@ require File.dirname(__FILE__) + '/spec_helper'
 
 describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}ClassVariableHandler" do
   before(:all) { parse_file :class_variable_handler_001, __FILE__ }
-  
+
   it "should not parse class variables inside methods" do
     obj = Registry.at("A::B::@@somevar")
     obj.source.should == "@@somevar = \"hello\""

data/spec/handlers/constant_handler_spec.rb

@@ -2,19 +2,19 @@ require File.dirname(__FILE__) + '/spec_helper'
 
 describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}ConstantHandler" do
   before(:all) { parse_file :constant_handler_001, __FILE__ }
-  
+
   it "should not parse constants inside methods" do
     Registry.at("A::B::SOMECONSTANT").source.should == "SOMECONSTANT= \"hello\""
   end
-  
+
   it "should only parse valid constants" do
     Registry.at("A::B::notaconstant").should be_nil
   end
-  
+
   it "should maintain newlines" do
     Registry.at("A::B::MYCONSTANT").value.gsub("\r", "").should == "A +\nB +\nC +\nD"
   end
-  
+
   it "should turn Const = Struct.new(:sym) into class Const with attr :sym" do
     obj = Registry.at("MyClass")
     obj.should be_kind_of(CodeObjects::ClassObject)
@@ -38,13 +38,13 @@ describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}ConstantHandle
 
     Registry.at("NotMyClass2").should be_nil
   end
-  
+
   it "should turn Const = Struct.new into empty struct" do
     obj = Registry.at("MyEmptyStruct")
     obj.should_not be_nil
     obj.attributes[:instance].should be_empty
   end
-  
+
   it "should maintain docstrings on structs defined via constants" do
     obj = Registry.at("DocstringStruct")
     obj.should_not be_nil
@@ -57,7 +57,7 @@ describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}ConstantHandle
     a2.docstring.should == "Another attr"
     a2.tag(:return).types.should == ["Number"]
   end
-  
+
   it "should raise undocumentable error in 1.9 parser for Struct.new assignment to non-const" do
     undoc_error "nonconst = Struct.new"
   end unless LEGACY_PARSER

data/spec/handlers/{macro_handler_spec.rb → dsl_handler_spec.rb}

@@ -1,10 +1,10 @@
 require File.dirname(__FILE__) + '/spec_helper'
 require 'ostruct'
 
-describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}MacroHandler" do
-  before(:all) { parse_file :macro_handler_001, __FILE__ }
-  
-  it "should create a readable attribute when @attribute r is found" do
+describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}DSLHandler" do
+  before(:all) { parse_file :dsl_handler_001, __FILE__ }
+
+  it "should create a readable attribute when @!attribute r is found" do
     obj = Registry.at('Foo#attr1')
     obj.should_not be_nil
     obj.should be_reader
@@ -12,14 +12,14 @@ describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}MacroHandler"
     Registry.at('Foo#attr1=').should be_nil
   end
 
-  it "should create a writable attribute when @attribute w is found" do
+  it "should create a writable attribute when @!attribute w is found" do
     obj = Registry.at('Foo#attr2=')
     obj.should_not be_nil
     obj.should be_writer
     Registry.at('Foo#attr2').should be_nil
   end
-  
-  it "should default to readwrite @attribute" do
+
+  it "should default to readwrite @!attribute" do
     obj = Registry.at('Foo#attr3')
     obj.should_not be_nil
     obj.should be_reader
@@ -27,59 +27,59 @@ describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}MacroHandler"
     obj.should_not be_nil
     obj.should be_writer
   end
-  
-  it "should allow @attribute to define alternate method name" do
+
+  it "should allow @!attribute to define alternate method name" do
     Registry.at('Foo#attr4').should be_nil
     Registry.at('Foo#custom').should_not be_nil
   end
 
-  it "should default to creating an instance method for any DSL method with tags" do
+  it "should default to creating an instance method for any DSL method with special tags" do
     obj = Registry.at('Foo#implicit0')
     obj.should_not be_nil
     obj.docstring.should == "IMPLICIT METHOD!"
     obj.tag(:return).types.should == ['String']
   end
-  
-  it "should set the method name when using @method" do
-    obj = Registry.at('Foo.xyz')
+
+  it "should recognize implicit docstring when it has scope tag" do
+    obj = Registry.at("Foo.implicit1")
     obj.should_not be_nil
-    obj.signature.should == 'def xyz(a, b, c)'
-    obj.source.should == 'foo_bar'
-    obj.docstring.should == 'The foo method'
-  end
-  
-  it "should create hidden overlaod tag when @method has signature" do
-    obj = Registry.at('Foo.xyz')
-    obj.docstring.tag(:overload).signature.should == 'xyz(a, b, c)'
-    obj.docstring.tag(:overload).object.should == obj
+    obj.scope.should == :class
   end
-  
-  it "should set the method name when using @overload" do
-    obj = Registry.at('Foo#qux2')
+
+  it "should recognize implicit docstring when it has visibility tag" do
+    obj = Registry.at("Foo#implicit2")
     obj.should_not be_nil
-    obj.signature.should == 'def qux2(a, b, c)'
-    obj.source.should == 'something'
-    obj.docstring.tag(:overload).name.should == :qux2
-    obj.docstring.tag(:overload).object.should == obj
+    obj.visibility.should == :protected
+  end
+
+  it "should not recognize implicit docstring with any other normal tag" do
+    obj = Registry.at('Foo#implicit_invalid3')
+    obj.should be_nil
   end
 
-  it "should set the method object when using @overload" do
-    obj = Registry.at('Foo#qux')
+  it "should set the method name when using @!method" do
+    obj = Registry.at('Foo.xyz')
     obj.should_not be_nil
-    obj.signature.should == 'def qux(a, b, c)'
-    obj.source.should == 'something :qux'
-    obj.docstring.tag(:overload).name.should == :qux
-    obj.docstring.tag(:overload).object.should == obj
+    obj.signature.should == 'def xyz(a, b, c)'
+    obj.source.should == 'foo_bar'
+    obj.docstring.should == 'The foo method'
   end
-  
-  it "should allow setting of @scope" do
+
+  it "should allow setting of @!scope" do
     Registry.at('Foo.xyz').scope.should == :class
   end
-  
-  it "should allow setting of @visibility" do
+
+  it "should create module function if @!scope is module" do
+    mod_c = Registry.at('Foo.modfunc1')
+    mod_i = Registry.at('Foo#modfunc1')
+    mod_c.scope.should == :class
+    mod_i.visibility.should == :private
+  end
+
+  it "should allow setting of @!visibility" do
     Registry.at('Foo.xyz').visibility.should == :protected
   end
-  
+
   it "should ignore DSL methods without tags" do
     Registry.at('Foo#implicit_invalid').should be_nil
   end
@@ -88,19 +88,23 @@ describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}MacroHandler"
     Registry.at('Foo#implicit_valid').should_not be_nil
     Registry.at('Foo#implicit_invalid2').should be_nil
   end
- 
+
   it "should allow creation of macros" do
     macro = CodeObjects::MacroObject.find('property')
     macro.should_not be_nil
     macro.should_not be_attached
     macro.method_object.should be_nil
   end
-  
+
   it "should handle macros with no parameters to expand" do
     Registry.at('Foo#none').should_not be_nil
     Registry.at('Baz#none').signature.should == 'def none(foo, bar)'
   end
-  
+
+  it "should expand $N on method definitions" do
+    Registry.at('Foo#regular_meth').docstring.should == 'a b c'
+  end
+
   it "should apply new macro docstrings on new objects" do
     obj = Registry.at('Foo#name')
     obj.should_not be_nil
@@ -112,7 +116,7 @@ describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}MacroHandler"
     obj.tag(:return).types.should == ['String']
     obj.tag(:return).text.should == 'the property name'
   end
-  
+
   it "should allow reuse of named macros" do
     obj = Registry.at('Foo#age')
     obj.should_not be_nil
@@ -124,10 +128,17 @@ describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}MacroHandler"
     obj.tag(:return).types.should == ['Fixnum']
     obj.tag(:return).text.should == 'the property age'
   end
-  
-  it "should use implicitly named macros" do
+
+  it "should know about method information on DSL with macro expansion" do
+    Registry.at('Foo#right_name').should_not be_nil
+    Registry.at('Foo#right_name').source.should ==
+      'implicit_with_different_method_name :wrong, :right'
+    Registry.at('Foo#wrong_name').should be_nil
+  end
+
+  it "should use attached macros" do
     macro = CodeObjects::MacroObject.find('parser')
-    macro.macro_data.should == "@method $1(opts = {})\n@return NOTHING!"
+    macro.macro_data.should == "@!method $1(opts = {})\n@return NOTHING!"
     macro.should_not be_nil
     macro.should be_attached
     macro.method_object.should == P('Foo.parser')
@@ -137,28 +148,36 @@ describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}MacroHandler"
     obj.signature.should == "def c_parser(opts = {})"
     obj.docstring.tag(:return).text.should == "NOTHING!"
   end
-  
-  it "should only use implicit macros on methods defined in inherited hierarchy" do
+
+  it "should append docstring on DSL method to attached macro" do
+    obj = Registry.at('Foo#d_parser')
+    obj.should_not be_nil
+    obj.docstring.should == "Another docstring"
+    obj.signature.should == "def d_parser(opts = {})"
+    obj.docstring.tag(:return).text.should == "NOTHING!"
+  end
+
+  it "should only use attached macros on methods defined in inherited hierarchy" do
     Registry.at('Bar#x_parser').should be_nil
     Registry.at('Baz#y_parser').should_not be_nil
   end
-  
+
   it "should handle top-level DSL methods" do
     obj = Registry.at('#my_other_method')
     obj.should_not be_nil
     obj.docstring.should == "Docstring for method"
   end
-  
+
   it "should handle Constant.foo syntax" do
     obj = Registry.at('#beep')
     obj.should_not be_nil
     obj.signature.should == 'def beep(a, b, c)'
   end
-  
+
   it "should not detect implicit macros with invalid method names" do
     undoc_error <<-eof
       ##
-      # IMPLICIT METHOD THAT SHOULD 
+      # IMPLICIT METHOD THAT SHOULD
       # NOT BE DETECTED
       dsl_method '/foo/bar'
     eof

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

@@ -1,7 +1,7 @@
 module A
   def a; end
   alias_method :b, :a
-  
+
   # Handle keyword syntax too
   alias :c :a
   alias d? a
@@ -12,7 +12,7 @@ module A
   alias * a
   alias for a
   alias ConstantName a
-  
+
   # Handle quoted symbols
   alias :'foo' :'a'
 end
@@ -24,7 +24,7 @@ end
 class B < C
   alias_method(:q, :x)
   alias_method :r?, :x
-  alias_method :s, :to_s 
+  alias_method :s, :to_s
   alias_method :t, :inspect if 500 == 3 * CONSTANT
   alias_method :<<, :a
   alias_method :for, :a
@@ -35,10 +35,10 @@ end
 class D
   # Foo bar
   def a; "FOO" end
-  
+
   # @return [String]
   alias b a
-  
+
   # @return [Numeric]
   def a; 0 end
 end

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

@@ -6,15 +6,15 @@ class A
   else
     def c; end
   end
-  
+
   def d; end if 50 * 2 == 101
-  
+
   unless false
     def e; end
   else
     def enot; end
   end
-  
+
   def g; end unless 5 * 2 == 101
 
   def h
@@ -22,37 +22,37 @@ class A
       def hnot; end
     end
   end
-  
+
   if defined? A
     def j; end
   else
     def jnot; end
   end
-  
+
   if defined? RUBY_VERSION
     def k; end
   else
     def knot; end
   end
-  
+
   if 0
     def nnot; end
   else
     def n; end
   end
-  
+
   if 256
     def o; end
   else
     def onot; end
   end
-  
+
   if true
     def p; end
   else
     def pnot; end
   end
-  
+
   if false
     def qnot; end
   else

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

@@ -2,7 +2,7 @@
 class A
   module B; end
   private
-  class B::C < String; 
+  class B::C < String;
     def method1; end
     def method2; end
   end

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

@@ -0,0 +1,110 @@
+class Foo
+  attr_accessor :ignoreme
+
+  # IMPLICIT METHOD!
+  # @return [String]
+  just_a_method_for :implicit0
+
+  # IMPLICIT METHOD2!
+  # @!scope class
+  just_a_method_for :implicit1
+
+  # IMPLICIT METHOD3!
+  # @!visibility protected
+  just_a_method_for :implicit2
+
+  # Not recognized
+  just_a_method_for :implicit_invalid
+
+  #
+  ## IS NOT RECOGNIZED!
+  just_a_method_for :implicit_invalid2
+
+  # @deprecated don't use this
+  just_a_method_for :implicit_invalid3
+
+  ##
+  # IS RECOGNIZED!
+  just_a_method_for 'implicit_valid'
+
+  # @!attribute [r]
+  # @return [Numeric] a number
+  a_readable_attribute :attr1
+
+  # @!attribute [w]
+  a_writable_attribute :attr2, 'bar'
+
+  # @!attribute
+  default_attribute :attr3
+
+  # @!attribute custom
+  default_attribute :attr4
+
+  # @!method xyz(a, b, c)
+  # The foo method
+  # @param [String] a
+  # @!visibility protected
+  # @!scope class
+  foo_bar
+
+  # @!macro property
+  #   @!method $1(${3-})
+  #   A $0 that is awesome.
+  #   @param $3 first parameter
+  #   @return [$2] the property $1
+  property :name, String, :a, :b, :c
+
+  # @!macro property
+  property :age, Fixnum, :value
+
+  # This is just for x
+  # @!macro [attach] parser
+  #   @!method $1(opts = {})
+  #   @return NOTHING!
+  parser :x
+
+  parser :c_parser
+
+  # Another docstring
+  parser :d_parser
+
+  # @!macro [attach] none
+  #   @!method none(foo, bar)
+  none
+
+  # @!macro something
+  #   @!method $1(a, b, c)
+  something :qux
+
+  # @!method qux2(a, b, c)
+  something
+
+  # @!macro
+  #   $1 $2 $3
+  def regular_meth(a, b, c) end
+
+  # @!macro [new] different
+  #   @!method $2_name(a = 1)
+
+  # @!macro different
+  implicit_with_different_method_name :wrong, :right
+
+  # @!scope module
+  a_module_function :modfunc1
+end
+
+class Bar
+  parser :x_parser
+end
+
+class Baz < Foo
+  parser :y_parser
+  none { }
+end
+
+# @!method my_other_method
+# Docstring for method
+method_that_makes_a_method
+
+# @!macro something
+foobarbaz :beep