deg-yard 0.8.7.1

data/spec/handlers/dsl_handler_spec.rb

@@ -0,0 +1,197 @@
+require File.dirname(__FILE__) + '/spec_helper'
+require 'ostruct'
+
+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
+    obj.tag(:return).types.should == ['Numeric']
+    Registry.at('Foo#attr1=').should be_nil
+  end
+
+  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
+    obj = Registry.at('Foo#attr3')
+    obj.should_not be_nil
+    obj.should be_reader
+    obj = Registry.at('Foo#attr3=')
+    obj.should_not be_nil
+    obj.should be_writer
+  end
+
+  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 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 recognize implicit docstring when it has scope tag" do
+    obj = Registry.at("Foo.implicit1")
+    obj.should_not be_nil
+    obj.scope.should == :class
+  end
+
+  it "should recognize implicit docstring when it has visibility tag" do
+    obj = Registry.at("Foo#implicit2")
+    obj.should_not be_nil
+    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 name when using @!method" do
+    obj = Registry.at('Foo.xyz')
+    obj.should_not be_nil
+    obj.signature.should == 'def xyz(a, b, c)'
+    obj.parameters.should == [['a', nil], ['b', nil], ['c', nil]]
+    obj.source.should == 'foo_bar'
+    obj.docstring.should == 'The foo method'
+  end
+
+  it "should allow setting of @!scope" do
+    Registry.at('Foo.xyz').scope.should == :class
+  end
+
+  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
+
+  it "should accept a DSL method without tags if it has hash_flag (##)" do
+    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
+    obj.source.should == 'property :name, String, :a, :b, :c'
+    obj.signature.should == 'def name(a, b, c)'
+    obj.docstring.should == 'A property that is awesome.'
+    obj.tag(:param).name.should == 'a'
+    obj.tag(:param).text.should == 'first parameter'
+    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
+    obj.source.should == 'property :age, Fixnum, :value'
+    obj.signature.should == 'def age(value)'
+    obj.docstring.should == 'A property that is awesome.'
+    obj.tag(:param).name.should == 'value'
+    obj.tag(:param).text.should == 'first parameter'
+    obj.tag(:return).types.should == ['Fixnum']
+    obj.tag(:return).text.should == 'the property age'
+  end
+
+  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.should_not be_nil
+    macro.should be_attached
+    macro.method_object.should == P('Foo.parser')
+    obj = Registry.at('Foo#c_parser')
+    obj.should_not be_nil
+    obj.docstring.should == ""
+    obj.signature.should == "def c_parser(opts = {})"
+    obj.docstring.tag(:return).text.should == "NOTHING!"
+  end
+
+  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 look through mixins for attached macros" do
+    meth = Registry.at('Baz#mixin_method')
+    meth.should_not be_nil
+    meth.docstring.should == 'DSL method mixin_method'
+  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 expand attached macros in first DSL method" do
+    Registry.at('DSLMethods#foo').docstring.should == "Returns String for foo"
+    Registry.at('DSLMethods#bar').docstring.should == "Returns Integer for bar"
+  end
+
+  it "should not detect implicit macros with invalid method names" do
+    undoc_error <<-eof
+      ##
+      # IMPLICIT METHOD THAT SHOULD
+      # NOT BE DETECTED
+      dsl_method '/foo/bar'
+    eof
+  end
+end

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

@@ -0,0 +1,44 @@
+module A
+  def a; end
+  alias_method :b, :a
+
+  # Handle keyword syntax too
+  alias :c :a
+  alias d? a
+  alias [] a
+  alias []= a
+  alias -@ a
+  alias % a
+  alias * a
+  alias for a
+  alias ConstantName a
+
+  # Handle quoted symbols
+  alias :'foo' :'a'
+end
+
+class C
+  def x; end
+end
+
+class B < C
+  alias_method(:q, :x)
+  alias_method :r?, :x
+  alias_method :s, :to_s
+  alias_method :t, :inspect if 500 == 3 * CONSTANT
+  alias_method :<<, :a
+  alias_method :for, :a
+  alias do x
+  alias x2 do
+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/attribute_handler_001.rb.txt

@@ -0,0 +1,32 @@
+module A
+  attr_writer :x
+end
+
+class B
+  class << self
+    attr_accessor :z
+  end
+
+  attr :a, true
+  attr :a2, false
+  attr :a3
+  # Docstring
+  attr_reader :b, :c, :d
+  attr_writer :e
+  attr_accessor 'f'
+
+  attr_accessor :z
+end
+
+class C
+  def foo; end
+  attr_writer :foo
+
+  def bar=(value); end
+  attr_reader :bar
+end
+
+class D
+protected
+attr_reader :parser
+end

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

@@ -0,0 +1,69 @@
+class A
+  if some_condition
+    def a; end
+  elsif 1 == 1
+    def b; end
+  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
+    if 1
+      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
+    def q; end
+  end
+
+  private
+
+  if a == 1
+    def m; end
+  else
+    def mnot; end
+  end
+end

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

@@ -0,0 +1,120 @@
+# Docstring
+class A
+  module B; end
+  private
+  class B::C < String;
+    def method1; end
+    def method2; end
+  end
+  class X<B::C
+  end
+  class<<self
+    def classmethod1; end
+  end
+
+  class << A::B::C; def Hello; end end
+end
+
+module B
+  class A < A
+  end
+end
+
+class RT < XX::RT; end
+
+class Test1 < R "something"
+end
+
+class Test2 < R(/something/)
+end
+
+class Test3 < Struct.new(:foo, :bar)
+end
+
+class Test4 < OStruct.new
+end
+
+class Test5 < DelegateClass(Array)
+end
+
+class Test6 < NotDelegateClass(Array)
+end
+
+class ::MyRootClass
+end
+
+module Holder
+  module SomeMod
+    class Importer
+      def parse; end
+    end
+  end
+end
+
+module Holder
+  class Importer < Holder::SomeMod::Importer
+    def a; end
+  end
+end
+
+class String; end
+CONST = String
+class << CONST
+  def classmethod; end
+end
+
+module Q
+  class Logger < ::Logger; end
+  class Foo < ::Logger; end
+end
+
+class << Symbol
+  alias toString to_s
+end
+
+# Docstring
+class Zebra
+end
+
+# Docstring 2
+
+class Zebra
+end
+
+class Zebra
+end
+
+# A simple struct
+class RegularStruct < Struct; end
+class RegularStruct2 < ::Struct; end
+
+class Point < Struct.new(:x, :y, :z)
+end
+
+class AnotherPoint < Struct.new('XPoint', :a, :b, :c, :description)
+end
+
+# @attr [IO] input the input stream
+# @attr mode the mode to read
+# @attr [Proc, #call] someproc the proc to run
+class DoccedStruct < Struct.new(:input, :mode, :someproc)
+end
+
+# @attr [String] first the first entry
+# @attr_reader [Fixnum] second this only has a reader
+# @attr_writer [Array] third this only has a writer
+# @attr_reader [#read] fourth returns a proc that reads
+# @attr_writer [IO] fourth sets the proc that writes stuff
+class SemiDoccedStruct < Struct.new(:first, :second, :third, :fourth)
+end
+
+# @attr [String] first the first entry
+# @attr_reader [Fixnum] second this only has a reader
+# @attr_writer [Array] third this only has a writer
+# @attr_reader [#read] fourth returns a proc that reads
+# @attr_writer [IO] fourth sets the proc that writes stuff
+class NotAStruct; end
+
+class Outer1
+  class Inner1 < self; end
+end

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

@@ -0,0 +1,10 @@
+module A
+  class B
+    @@somevar = "hello"
+	@@somevar.value = "H"
+
+    def method
+      @@somevar = "don't document this"
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+module A
+  class B
+	notaconstant = 2
+    SOMECONSTANT= "hello"
+
+    def method
+      SOMECONSTANT = "don't document this"
+    end
+
+    MYCONSTANT = A +
+      B +
+      C +
+      D
+  end
+end
+
+MyClass = Struct.new(:a, :b, :c)
+NotMyClass = Struct.new("NotMyClass2", :b, :c)
+MyEmptyStruct = Struct.new
+
+# A crazy struct.
+#
+# @attr [String] bar An attr
+# @attr [Number] baz Another attr
+DocstringStruct = Struct.new(:bar, :baz)

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

@@ -0,0 +1,125 @@
+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
+
+module MyMixin
+  # @!macro [attach] special
+  #   DSL method $1
+  def defined_by_mixin; end
+end
+
+class Bar
+  parser :x_parser
+end
+
+class Baz < Foo
+  extend MyMixin
+  parser :y_parser
+  none { }
+  defined_by_mixin :mixin_method
+end
+
+# @!method my_other_method
+# Docstring for method
+method_that_makes_a_method
+
+# @!macro something
+foobarbaz :beep
+
+module DSLMethods
+  # @macro [attach] dsl_method
+  #   Returns $2 for $1
+  dsl_method :foo, String
+  dsl_method :bar, Integer
+end

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

@@ -0,0 +1,59 @@
+class Testing
+  # Ignore yields outside methods
+  raise NoMethodError, "reason"
+
+  # Should document this
+  def mymethod
+    raise ArgumentError, "Argument is missing"
+  end
+
+  # Don't document this
+  def mymethod2
+    raise(a)
+  end
+
+  # Don't document this (docstring takes precedence)
+  # @raise [A]
+  def mymethod3
+    raise SomethingElse
+  end
+
+  # Only document the first one (limitation of exc handler)
+  def mymethod4
+    raise(A)
+    raise B, "Argument", somethingelse
+  end
+
+  def mymethod5
+    raise YARD::Parser::UndocumentableError
+  end
+
+  def mymethod6
+    raise YARD::Handlers.constants("test")
+  end
+
+  def mymethod7
+    raise MethodCall('argument')
+  end
+
+  def mymethod8
+    raise ExceptionClass.new('blah')
+  end
+
+  def mymethod9
+    obj.raise IgnoreMe
+	obj.raise(IgnoreMe)
+  end
+
+  def mymethod10
+    raise ArgumentError 'Message' # actually a method call
+  end
+
+  def mymethod11
+    raise foo('bar')
+  end
+
+  def mymethod12
+    raise
+  end
+end

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

@@ -0,0 +1,16 @@
+module A; end
+module B
+  extend A
+end
+
+module C
+  extend self
+end
+
+module Q
+  module R
+    module S
+      extend A
+    end
+  end
+end

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

@@ -0,0 +1,10 @@
+def a
+  if 1
+    # ignore this
+    def b; end
+  end
+
+  # don't ignore these even though we know they're not executed
+  def c; end if false
+  def d; end unless true
+end