deg-yard 0.8.7.1

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

@@ -0,0 +1,41 @@
+# Handles alias and alias_method calls
+class YARD::Handlers::Ruby::AliasHandler < YARD::Handlers::Ruby::Base
+  handles :alias, method_call(:alias_method)
+  namespace_only
+
+  process do
+    names = []
+    if statement.type == :alias
+      names = statement.map {|o| o.jump(:ident, :op, :kw, :const).source }
+    elsif statement.call?
+      statement.parameters(false).each do |obj|
+        case obj.type
+        when :symbol_literal
+          names << obj.jump(:ident, :op, :kw, :const).source
+        when :string_literal
+          names << obj.jump(:string_content).source
+        end
+      end
+    end
+    raise YARD::Parser::UndocumentableError, "alias/alias_method" if names.size != 2
+
+    new_meth, old_meth = names[0].to_sym, names[1].to_sym
+    old_obj = namespace.child(:name => old_meth, :scope => scope)
+    new_obj = register MethodObject.new(namespace, new_meth, scope) do |o|
+      o.add_file(parser.file, statement.line)
+    end
+
+    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)
+      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/attribute_handler.rb

@@ -0,0 +1,82 @@
+# Handles +attr_*+ statements in modules/classes
+class YARD::Handlers::Ruby::AttributeHandler < YARD::Handlers::Ruby::Base
+  handles method_call(:attr)
+  handles method_call(:attr_reader)
+  handles method_call(:attr_writer)
+  handles method_call(:attr_accessor)
+  namespace_only
+
+  process do
+    return if statement.type == :var_ref || statement.type == :vcall
+    read, write = true, false
+    params = statement.parameters(false).dup
+
+    # Change read/write based on attr_reader/writer/accessor
+    case statement.method_name(true)
+    when :attr
+      # In the case of 'attr', the second parameter (if given) isn't a symbol.
+      if params.size == 2
+        write = true if params.pop == s(:var_ref, s(:kw, "true"))
+      end
+    when :attr_accessor
+      write = true
+    when :attr_reader
+      # change nothing
+    when :attr_writer
+      read, write = false, true
+    end
+
+    # Add all attributes
+    validated_attribute_names(params).each do |name|
+      namespace.attributes[scope][name] ||= SymbolHash[:read => nil, :write => nil]
+
+      # Show their methods as well
+      {:read => name, :write => "#{name}="}.each do |type, meth|
+        if (type == :read ? read : write)
+          o = MethodObject.new(namespace, meth, scope)
+          if type == :write
+            o.parameters = [['value', nil]]
+            src = "def #{meth}(value)"
+            full_src = "#{src}\n  @#{name} = value\nend"
+            doc = "Sets the attribute #{name}\n@param value the value to set the attribute #{name} to."
+          else
+            src = "def #{meth}"
+            full_src = "#{src}\n  @#{name}\nend"
+            doc = "Returns the value of attribute #{name}"
+          end
+          o.source ||= full_src
+          o.signature ||= src
+          register(o)
+          o.docstring = doc if o.docstring.blank?(false)
+
+          # Regsiter the object explicitly
+          namespace.attributes[scope][name][type] = o
+        elsif obj = namespace.children.find {|o| o.name == meth.to_sym && o.scope == scope }
+          # register an existing method as attribute
+          namespace.attributes[scope][name][type] = obj
+        end
+      end
+    end
+  end
+
+  protected
+
+  # Strips out any non-essential arguments from the attr statement.
+  #
+  # @param [Array<Parser::Ruby::AstNode>] params a list of the parameters
+  #   in the attr call.
+  # @return [Array<String>] the validated attribute names
+  # @raise [Parser::UndocumentableError] if the arguments are not valid.
+  def validated_attribute_names(params)
+    params.map do |obj|
+      case obj.type
+      when :symbol_literal
+        obj.jump(:ident, :op, :kw, :const).source
+      when :string_literal
+        obj.jump(:string_content).source
+      else
+        raise YARD::Parser::UndocumentableError, obj.source
+      end
+    end
+  end
+end

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

@@ -0,0 +1,164 @@
+module YARD
+  module Handlers
+    module Ruby
+      # To implement a custom handler matcher, subclass this class and implement
+      # {#matches?} to return whether a node matches the handler.
+      #
+      # @example A Custom Handler Matcher Extension
+      #   # Implements a handler that checks for a specific string
+      #   # in the node's source.
+      #   class MyExtension < HandlesExtension
+      #     def matches?(node) node.source.include?(name) end
+      #   end
+      #
+      #   # This handler will handle any node where the source includes 'foo'
+      #   class MyHandler < Handlers::Ruby::Base
+      #     handles MyExtension.new('foo')
+      #   end
+      class HandlesExtension
+        # Creates a new extension with a specific matcher value +name+
+        # @param [Object] name the matcher value to check against {#matches?}
+        def initialize(name) @name = name end
+
+        # Tests if the node matches the handler
+        # @param [Parser::Ruby::AstNode] node a Ruby node
+        # @return [Boolean] whether the +node+ matches the handler
+        def matches?(node) raise NotImplementedError end
+
+        protected
+
+        # @return [String] the extension matcher value
+        attr_reader :name
+      end
+
+      class MethodCallWrapper < HandlesExtension
+        def matches?(node)
+          case node.type
+          when :var_ref
+            if !node.parent || node.parent.type == :list
+              return true if node[0].type == :ident && (name.nil? || node[0][0] == name)
+            end
+          when :fcall, :command, :vcall
+            return true if name.nil? || node[0][0] == name
+          when :call, :command_call
+            return true if name.nil? || node[2][0] == name
+          end
+          false
+        end
+      end
+
+      class TestNodeWrapper < HandlesExtension
+        def matches?(node) !node.send(name).is_a?(FalseClass) end
+      end
+
+      # This is the base handler class for the new-style (1.9) Ruby parser.
+      # All handlers that subclass this base class will be used when the
+      # new-style parser is used. For implementing legacy handlers, see
+      # {Legacy::Base}.
+      #
+      # @abstract See {Handlers::Base} for subclassing information.
+      # @see Handlers::Base
+      # @see Legacy::Base
+      class Base < Handlers::Base
+        class << self
+          include Parser::Ruby
+
+          # @group Statement Matcher Extensions
+
+          # Matcher for handling any type of method call. Method calls can
+          # be expressed by many {AstNode} types depending on the syntax
+          # with which it is called, so YARD allows you to use this matcher
+          # to simplify matching a method call.
+          #
+          # @example Match the "describe" method call
+          #   handles method_call(:describe)
+          #
+          #   # The following will be matched:
+          #   # describe(...)
+          #   # object.describe(...)
+          #   # describe "argument" do ... end
+          #
+          # @param [#to_s] name matches the method call of this name
+          # @return [void]
+          def method_call(name = nil)
+            MethodCallWrapper.new(name ? name.to_s : nil)
+          end
+
+          # Matcher for handling a node with a specific meta-type. An {AstNode}
+          # has a {AstNode#type} to define its type but can also be associated
+          # with a set of types. For instance, +:if+ and +:unless+ are both
+          # of the meta-type +:condition+.
+          #
+          # A meta-type is any method on the {AstNode} class ending in "?",
+          # though you should not include the "?" suffix in your declaration.
+          # Some examples are: "condition", "call", "literal", "kw", "token",
+          # "ref".
+          #
+          # @example Handling any conditional statement (if, unless)
+          #   handles meta_type(:condition)
+          # @param [Symbol] type the meta-type to match. A meta-type can be
+          #   any method name + "?" that {AstNode} responds to.
+          # @return [void]
+          def meta_type(type)
+            TestNodeWrapper.new(type.to_s + "?")
+          end
+
+          # @group Testing for a Handler
+
+          # @return [Boolean] whether or not an {AstNode} object should be
+          #   handled by this handler
+          def handles?(node)
+            handlers.any? do |a_handler|
+              case a_handler
+              when Symbol
+                a_handler == node.type
+              when String
+                node.source == a_handler
+              when Regexp
+                node.source =~ a_handler
+              when Parser::Ruby::AstNode
+                a_handler == node
+              when HandlesExtension
+                a_handler.matches?(node)
+              end
+            end
+          end
+        end
+
+        include Parser::Ruby
+
+        # @group Parsing an Inner Block
+
+        def parse_block(inner_node, opts = {})
+          push_state(opts) do
+            nodes = inner_node.type == :list ? inner_node.children : [inner_node]
+            parser.process(nodes)
+          end
+        end
+
+        # @group Macro Handling
+
+        def call_params
+          return [] unless statement.respond_to?(:parameters)
+          statement.parameters(false).compact.map do |param|
+            if param.type == :list
+              param.map {|n| n.jump(:ident, :kw, :tstring_content).source }
+            else
+              param.jump(:ident, :kw, :tstring_content).source
+            end
+          end.flatten
+        end
+
+        def caller_method
+          if statement.call? || statement.def?
+            statement.method_name(true).to_s
+          elsif statement.type == :var_ref || statement.type == :vcall
+            statement[0].jump(:ident, :kw).source
+          else
+            nil
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+# Matches if/unless conditions inside classes and attempts to process only
+# one branch (by evaluating the condition if possible).
+#
+# @example A simple class conditional
+#   class Foo
+#     if 0
+#       # This method is ignored
+#       def xyz; end
+#     end
+#   end
+class YARD::Handlers::Ruby::ClassConditionHandler < YARD::Handlers::Ruby::Base
+  handles meta_type(:condition)
+  namespace_only
+
+  process do
+    condition = parse_condition
+    if condition == nil
+      # Parse both blocks if we're unsure of the condition
+      parse_then_block
+      parse_else_block
+    elsif condition
+      parse_then_block
+    else
+      parse_else_block
+    end
+  end
+
+  protected
+
+  # Parses the condition part of the if/unless statement
+  #
+  # @return [true, false, nil] true if the condition can be definitely
+  #   parsed to true, false if not, and nil if the condition cannot be
+  #   parsed with certainty (it's dynamic)
+  def parse_condition
+    condition = nil
+
+    # Right now we can handle very simple unary conditions like:
+    #   if true
+    #   if false
+    #   if 0
+    #   if 100 (not 0)
+    #   if defined? SOME_CONSTANT
+    #
+    # The last case will do a lookup in the registry and then one
+    # in the Ruby world (using eval).
+    case statement.condition.type
+    when :int
+      condition = statement.condition[0] != "0"
+    when :defined
+      # defined? keyword used, let's see if we can look up the name
+      # in the registry, then we'll try using Ruby's powers. eval() is not
+      # *too* dangerous here since code is not actually executed.
+      name = statement.condition[0].source
+      obj = YARD::Registry.resolve(namespace, name, true)
+      begin
+        condition = true if obj || Object.instance_eval("defined? #{name}")
+      rescue SyntaxError, NameError
+        condition = false
+      end
+    when :var_ref
+      var = statement.condition[0]
+      if var == s(:kw, "true")
+        condition = true
+      elsif var == s(:kw, "false")
+        condition = false
+      end
+    end
+
+    # Invert an unless condition
+    if statement.type == :unless || statement.type == :unless_mod
+      condition = !condition if condition != nil
+    end
+    condition
+  end
+
+  def parse_then_block
+    parse_block(statement.then_block, :visibility => visibility)
+  end
+
+  def parse_else_block
+    if statement.else_block
+      parse_block(statement.else_block, :visibility => visibility)
+    end
+  end
+end

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

@@ -0,0 +1,121 @@
+# Handles class declarations
+class YARD::Handlers::Ruby::ClassHandler < YARD::Handlers::Ruby::Base
+  include YARD::Handlers::Ruby::StructHandlerMethods
+  handles :class, :sclass
+  namespace_only
+
+  process do
+    classname = statement[0].source.gsub(/\s/, '')
+    if statement.type == :class
+      superclass = parse_superclass(statement[1])
+      if superclass == "Struct"
+        is_a_struct = true
+        superclass = struct_superclass_name(statement[1]) # refine the superclass if possible
+        create_struct_superclass(superclass, statement[1])
+      end
+      undocsuper = statement[1] && superclass.nil?
+      klass = register ClassObject.new(namespace, classname) do |o|
+        o.superclass = superclass if superclass
+        o.superclass.type = :class if o.superclass.is_a?(Proxy)
+      end
+      if is_a_struct
+        parse_struct_superclass(klass, statement[1])
+      elsif klass
+        create_attributes(klass, members_from_tags(klass))
+      end
+      parse_block(statement[2], :namespace => klass)
+
+      if undocsuper
+        raise YARD::Parser::UndocumentableError, 'superclass (class was added without superclass)'
+      end
+    elsif statement.type == :sclass
+      if statement[0] == s(:var_ref, s(:kw, "self"))
+        parse_block(statement[1], :namespace => namespace, :scope => :class)
+      else
+        proxy = Proxy.new(namespace, classname)
+
+        # Allow constants to reference class names
+        if ConstantObject === proxy
+          if proxy.value =~ /\A#{NAMESPACEMATCH}\Z/
+            proxy = Proxy.new(namespace, proxy.value)
+          else
+            raise YARD::Parser::UndocumentableError, "constant class reference '#{classname}'"
+          end
+        end
+
+        if classname[0,1] =~ /[A-Z]/
+          register ClassObject.new(namespace, classname) if Proxy === proxy
+          parse_block(statement[1], :namespace => proxy, :scope => :class)
+        else
+          raise YARD::Parser::UndocumentableError, "class '#{classname}'"
+        end
+      end
+    else
+      sig_end = (statement[1] ? statement[1].source_end : statement[0].source_end) - statement.source_start
+      raise YARD::Parser::UndocumentableError, "class: #{statement.source[0..sig_end]}"
+    end
+  end
+
+  private
+
+  # Extract the parameters from the Struct.new AST node, returning them as a list
+  # of strings
+  #
+  # @param [MethodCallNode] superclass the AST node for the Struct.new call
+  # @return [Array<String>] the member names to generate methods for
+  def extract_parameters(superclass)
+    members = superclass.parameters.select {|x| x && x.type == :symbol_literal}
+    members.map! {|x| x.source.strip[1..-1]}
+    members
+  end
+
+  def create_struct_superclass(superclass, superclass_def)
+    return if superclass == "Struct"
+    the_super = register ClassObject.new(P("Struct"), superclass[8..-1]) do |o|
+      o.superclass = "Struct"
+    end
+    parse_struct_superclass(the_super, superclass_def)
+    the_super
+  end
+
+  def struct_superclass_name(superclass)
+    if superclass.call?
+      first = superclass.parameters.first
+      if first.type == :string_literal && first[0].type == :string_content && first[0].size == 1
+        return "Struct::#{first[0][0][0]}"
+      end
+    end
+    "Struct"
+  end
+
+  def parse_struct_superclass(klass, superclass)
+    return unless superclass.call? && superclass.parameters
+    members = extract_parameters(superclass)
+    create_attributes(klass, members)
+  end
+
+  def parse_superclass(superclass)
+    return nil unless superclass
+
+    case superclass.type
+    when :var_ref
+      return namespace.path if superclass.first == s(:kw, "self")
+      return superclass.source if superclass.first.type == :const
+    when :const, :const_ref, :const_path_ref, :top_const_ref
+      return superclass.source
+    when :fcall, :command
+      methname = superclass.method_name.source
+      if methname == "DelegateClass"
+        return superclass.parameters.first.source
+      elsif superclass.method_name.type == :const
+        return methname
+      end
+    when :call, :command_call
+      cname = superclass.namespace.source
+      if cname =~ /^O?Struct$/ && superclass.method_name(true) == :new
+        return cname
+      end
+    end
+    nil
+  end
+end

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

@@ -0,0 +1,16 @@
+# Handles a class variable (@@variable)
+class YARD::Handlers::Ruby::ClassVariableHandler < YARD::Handlers::Ruby::Base
+  handles :assign
+  namespace_only
+
+  process do
+    if statement[0].type == :var_field && statement[0][0].type == :cvar
+      name = statement[0][0][0]
+      value = statement[1].source
+      register ClassVariableObject.new(namespace, name) do |o|
+        o.source = statement
+        o.value = value
+      end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# Handles any lone comment statement in a Ruby file
+class YARD::Handlers::Ruby::CommentHandler < YARD::Handlers::Ruby::Base
+  handles :comment, :void_stmt
+  namespace_only
+
+  process do
+    register_docstring(nil)
+  end
+end

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

@@ -0,0 +1,45 @@
+# Handles any constant assignment
+class YARD::Handlers::Ruby::ConstantHandler < YARD::Handlers::Ruby::Base
+  include YARD::Handlers::Ruby::StructHandlerMethods
+  handles :assign
+  namespace_only
+
+  process do
+    if statement[1].call? && statement[1][0][0] == s(:const, "Struct") &&
+        statement[1][2] == s(:ident, "new")
+      process_structclass(statement)
+    elsif statement[0].type == :var_field && statement[0][0].type == :const
+      process_constant(statement)
+    end
+  end
+
+  private
+
+  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 }
+  end
+
+  def process_structclass(statement)
+    lhs = statement[0][0]
+    if lhs.type == :const
+      klass = create_class(lhs[0], P(:Struct))
+      create_attributes(klass, extract_parameters(statement[1]))
+    else
+      raise YARD::Parser::UndocumentableError, "Struct assignment to #{statement[0].source}"
+    end
+  end
+
+  # Extract the parameters from the Struct.new AST node, returning them as a list
+  # of strings
+  #
+  # @param [MethodCallNode] superclass the AST node for the Struct.new call
+  # @return [Array<String>] the member names to generate methods for
+  def extract_parameters(superclass)
+    return [] unless superclass.parameters
+    members = superclass.parameters.select {|x| x && x.type == :symbol_literal}
+    members.map! {|x| x.source.strip[1..-1]}
+    members
+  end
+end

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

@@ -0,0 +1,14 @@
+module YARD
+  module Handlers
+    module Ruby
+      # Handles automatic detection of dsl-style methods
+      class DSLHandler < Base
+        include CodeObjects
+        include DSLHandlerMethods
+        handles method_call
+        namespace_only
+        process { handle_comments }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+module YARD
+  module Handlers
+    module Ruby
+      module DSLHandlerMethods
+        include CodeObjects
+        include Parser
+
+        IGNORE_METHODS = Hash[*%w(alias alias_method autoload attr attr_accessor
+          attr_reader attr_writer extend include public private protected
+          private_constant).map {|n| [n, true] }.flatten]
+
+        def handle_comments
+          return if IGNORE_METHODS[caller_method]
+
+          @docstring = statement.comments || ""
+          @docstring = @docstring.join("\n") if @docstring.is_a?(Array)
+
+          if @docstring =~ /^@!?macro\s+\[[^\]]*attach/
+            register_docstring(nil)
+            @docstring = ""
+          end
+
+          if macro = find_attached_macro
+            @docstring += "\n" +
+              macro.expand([caller_method, *call_params], statement.source)
+          elsif !statement.comments_hash_flag && !implicit_docstring?
+            return register_docstring(nil)
+          end
+
+          # ignore DSL definitions if @method/@attribute directive is used
+          if @docstring =~ /^@!?(method|attribute)\b/
+            return register_docstring(nil)
+          end
+
+          object = MethodObject.new(namespace, method_name, scope)
+          object.signature = method_signature
+          register(object)
+        end
+
+        def register_docstring(object, docstring = @docstring, stmt = statement)
+          super
+        end
+
+        private
+
+        def implicit_docstring?
+          tags = %w(method attribute overload visibility scope return)
+          tags.any? {|tag| @docstring =~ /^@!?#{tag}\b/ }
+        end
+
+        def method_name
+          name = call_params.first || ""
+          if name =~ /^#{CodeObjects::METHODNAMEMATCH}$/
+            name
+          else
+            raise UndocumentableError, "method, missing name"
+          end
+        end
+
+        def method_signature
+          "def #{method_name}"
+        end
+
+        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
+            (namespace.inheritance_tree(true) + [P('Object')]).each do |obj|
+              return macro if obj == macro.method_object.namespace
+            end
+          end
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# Handles 'raise' calls inside methods
+class YARD::Handlers::Ruby::ExceptionHandler < YARD::Handlers::Ruby::Base
+  handles method_call(:raise)
+
+  process do
+    return unless owner.is_a?(MethodObject) # Only methods yield
+    return if [:command_call, :call].include? statement.type
+    return if owner.has_tag?(:raise)
+
+    klass = nil
+    if statement.call?
+      params = statement.parameters(false)
+      if params.size == 1
+        if params.first.ref? && params.first.first.type != :ident
+          klass = params.first.source
+        elsif params.first.call? && params.first.method_name(true) == :new
+          klass = params.first.namespace.source
+        end
+      elsif params.size > 1
+        klass = params.first.source
+      end
+    end
+
+    owner.add_tag YARD::Tags::Tag.new(:raise, '', klass) if klass
+  end
+end