yard 0.2.3.5 → 0.4.0

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

@@ -1,4 +1,5 @@
 class YARD::Handlers::Ruby::ClassHandler < YARD::Handlers::Ruby::Base
+  namespace_only
   handles :class, :sclass
   
   def process
@@ -8,7 +9,6 @@ class YARD::Handlers::Ruby::ClassHandler < YARD::Handlers::Ruby::Base
       undocsuper = statement[1] && superclass.nil?
 
       klass = register ClassObject.new(namespace, classname) do |o|
-        o.docstring = statement.comments
         o.superclass = superclass if superclass
         o.superclass.type = :class if o.superclass.is_a?(Proxy)
       end

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

@@ -5,7 +5,11 @@ class YARD::Handlers::Ruby::ClassVariableHandler < YARD::Handlers::Ruby::Base
   def process
     if statement[0].type == :var_field && statement[0][0].type == :cvar
       name = statement[0][0][0]
-      register ClassVariableObject.new(namespace, name) {|o| o.source = statement }
+      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/constant_handler.rb

@@ -3,10 +3,44 @@ class YARD::Handlers::Ruby::ConstantHandler < YARD::Handlers::Ruby::Base
   handles :assign
   
   def process
-    if statement[0].type == :var_field && statement[0][0].type == :const
-      name = statement[0][0][0]
-      value = statement[1].source
-      register ConstantObject.new(namespace, name) {|o| o.source = statement; o.value = value.strip }
+    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 = register ClassObject.new(namespace, lhs[0])
+      klass.superclass = P(:Struct)
+      parse_attributes(klass, statement[1].parameters)
+    else
+      raise YARD::Parser::UndocumentableError, "Struct assignment to #{statement[0].source}"
+    end
+  end
+  
+  def parse_attributes(klass, attributes)
+    return unless attributes
+    
+    scope = :instance
+    attributes.each do |node|
+      next if !node.respond_to?(:type) || node.type != :symbol_literal
+      name = node.jump(:ident).source
+      klass.attributes[scope][name] = SymbolHash[:read => nil, :write => nil]
+      {read: name, write: "#{name}="}.each do |type, meth|
+        klass.attributes[scope][name][type] = MethodObject.new(klass, meth, scope)
+      end
     end
   end
 end

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

@@ -3,6 +3,7 @@ class YARD::Handlers::Ruby::ExceptionHandler < YARD::Handlers::Ruby::Base
   
   def process
     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

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

@@ -49,7 +49,7 @@ module YARD
         # 
         # @param [Array<Class<Token>>, Symbol] accepted_types
         #   The allowed token types that this token can be. Defaults to [{TkVal}].
-        #   A list of types would be, for example, [{TkSTRING}, {TkSYMBOL}], to return
+        #   A list of types would be, for example, [+TkSTRING+, +TkSYMBOL+], to return
         #   the token's value if it is either of those types. If +TkVal+ is accepted, 
         #   +TkNode+ is also accepted.
         # 
@@ -116,7 +116,7 @@ module YARD
         #   attr_accessor :a, 'b', :c, :d => ['a', 'b', 'c', 'd']
         #   attr_accessor 'a', UNACCEPTED_TYPE, 'c' => ['a', 'c'] 
         # 
-        # The tokval list of a {TokenList} of the above
+        # The tokval list of a {Parser::Ruby::Legacy::TokenList} of the above
         # code would be the {#tokval} value of :a, 'b',
         # :c and :d.
         # 

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

@@ -1,5 +1,5 @@
 class YARD::Handlers::Ruby::Legacy::ClassVariableHandler < YARD::Handlers::Ruby::Legacy::Base
-  HANDLER_MATCH = /\A@@\S*\s*=\s*/m
+  HANDLER_MATCH = /\A@@\w+\s*=\s*/m
   handles HANDLER_MATCH
   
   def process
@@ -7,7 +7,10 @@ class YARD::Handlers::Ruby::Legacy::ClassVariableHandler < YARD::Handlers::Ruby:
     # they're not "static" when executed from a method
     return unless owner.is_a? NamespaceObject
     
-    name, value = *statement.tokens.to_s.gsub(/\r?\n/, '').split(/\s*=\s*/, 2)
-    register ClassVariableObject.new(namespace, name) {|o| o.source = statement }
+    name, value = *statement.tokens.to_s.split(/\s*=\s*/, 2)
+    register ClassVariableObject.new(namespace, name) do |o| 
+      o.source = statement
+      o.value = value.strip
+    end
   end
 end

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

@@ -7,7 +7,26 @@ class YARD::Handlers::Ruby::Legacy::ConstantHandler < YARD::Handlers::Ruby::Lega
     # they're not "static" when executed from a method
     return unless owner.is_a? NamespaceObject
     
-    name, value = *statement.tokens.to_s.gsub(/\r?\n/, '').split(/\s*=\s*/, 2)
-    register ConstantObject.new(namespace, name) {|o| o.source = statement; o.value = value.strip }
+    name, value = *statement.tokens.to_s.split(/\s*=\s*/, 2)
+    if value =~ /\A\s*Struct.new(?:\s*\(?|\b)/
+      process_structclass(name, $')
+    else
+      register ConstantObject.new(namespace, name) {|o| o.source = statement; o.value = value.strip }
+    end
+  end
+  
+  private
+  
+  def process_structclass(classname, parameters)
+    scope = :instance
+    klass = register ClassObject.new(namespace, classname)
+    klass.superclass = P(:Struct)
+
+    tokval_list(YARD::Parser::Ruby::Legacy::TokenList.new(parameters), TkSYMBOL).each do |name|
+      klass.attributes[scope][name] = SymbolHash[:read => nil, :write => nil]
+      {:read => name, :write => "#{name}="}.each do |type, meth|
+        klass.attributes[scope][name][type] = MethodObject.new(klass, meth, scope)
+      end
+    end
   end
 end

data/lib/yard/handlers/ruby/legacy/method_handler.rb

@@ -26,6 +26,16 @@ class YARD::Handlers::Ruby::Legacy::MethodHandler < YARD::Handlers::Ruby::Legacy
       o.explicit = true
       o.parameters = args
     end
+    if mscope == :instance && meth == "initialize"
+      unless obj.has_tag?(:return)
+        obj.docstring.add_tag(YARD::Tags::Tag.new(:return, 
+          "a new instance of +#{namespace.name}+", namespace.name.to_s))
+      end
+    elsif mscope == :class && obj.docstring.blank? && %w(inherited included 
+        extended method_added method_removed method_undefined).include?(meth)
+      obj.docstring.add_tag(YARD::Tags::Tag.new(:private, nil))
+    end
+
     parse_block(:owner => obj) # mainly for yield/exceptions
   end
 end

data/lib/yard/handlers/ruby/legacy/yield_handler.rb

@@ -7,7 +7,6 @@ class YARD::Handlers::Ruby::Legacy::YieldHandler < YARD::Handlers::Ruby::Legacy:
     return if owner.has_tag? :yieldparam    # Same thing.
 
     yieldtag = YARD::Tags::Tag.new(:yield, "", [])
-    owner.docstring.add_tag(yieldtag)
     tokval_list(statement.tokens[2..-1], Token).each do |item|
       item = item.inspect unless item.is_a?(String)
       if item == "self"
@@ -22,5 +21,7 @@ class YARD::Handlers::Ruby::Legacy::YieldHandler < YARD::Handlers::Ruby::Legacy:
         yieldtag.types << item
       end
     end
+
+    owner.docstring.add_tag(yieldtag) unless yieldtag.types.empty?
   end
 end

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

@@ -22,6 +22,16 @@ class YARD::Handlers::Ruby::MethodHandler < YARD::Handlers::Ruby::Base
       o.signature = method_signature(meth)
       o.explicit = true
       o.parameters = args
+      
+    end
+    if mscope == :instance && meth == "initialize"
+      unless obj.has_tag?(:return)
+        obj.docstring.add_tag(YARD::Tags::Tag.new(:return, 
+          "a new instance of +#{namespace.name}+", namespace.name.to_s))
+      end
+    elsif mscope == :class && obj.docstring.blank? && %w(inherited included 
+        extended method_added method_removed method_undefined).include?(meth)
+      obj.docstring.add_tag(YARD::Tags::Tag.new(:private, nil))
     end
     
     parse_block(blk, :owner => obj) # mainly for yield/exceptions

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

@@ -7,7 +7,6 @@ class YARD::Handlers::Ruby::YieldHandler < YARD::Handlers::Ruby::Base
     return if owner.has_tag? :yieldparam    # Same thing.
 
     yieldtag = YARD::Tags::Tag.new(:yield, "", [])
-    owner.docstring.add_tag(yieldtag)
     
     if statement.type == :yield
       statement.jump(:list).children.each do |item|
@@ -24,5 +23,7 @@ class YARD::Handlers::Ruby::YieldHandler < YARD::Handlers::Ruby::Base
         end
       end
     end
+    
+    owner.docstring.add_tag(yieldtag) unless yieldtag.types.empty?
   end
 end

data/lib/yard/logging.rb

@@ -1,28 +1,45 @@
 require 'logger'
 
 module YARD
+  # Handles console logging for info, warnings and errors.
+  # Uses the stdlib Logger class in Ruby for all the backend logic.
   class Logger < ::Logger
+    # The logger instance
+    # @return [Logger] the logger instance
     def self.instance(pipe = STDERR)
       @logger ||= new(pipe)
     end
     
+    # Creates a new logger
     def initialize(*args)
       super
       self.level = INFO
       self.formatter = method(:format_log)
     end
     
+    # Changes the debug level to DEBUG if $DEBUG is set
+    # and writes a debugging message.
     def debug(*args)
       self.level = DEBUG if $DEBUG
       super
     end
     
+    # Sets the logger level for the duration of the block
+    # 
+    # @example
+    #   log.enter_level(Logger::ERROR) do
+    #     YARD.parse_string "def x; end"
+    #   end
+    # @param [Fixnum] new_level the logger level for the duration of the block.
+    #   values can be found in Ruby's Logger class.
+    # @yield the block with the logger temporarily set to +new_level+
     def enter_level(new_level = level, &block) 
       old_level, self.level = level, new_level
       yield
       self.level = old_level
     end
     
+    # Log format (from Logger implementation)
     def format_log(sev, time, prog, msg)
       "[#{sev.downcase}]: #{msg}\n"
     end

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

@@ -1,12 +1,42 @@
 module YARD
   module Parser
     module Ruby
+      # Builds and s-expression by creating {AstNode} objects with
+      # the type provided by the first argument.
+      # 
+      # @example An implicit list of keywords
+      #   ast = s(s(:kw, "if"), s(:kw, "else"))
+      #   ast.type # => :list
+      # @example A method call
+      #   s(:command, s(:var_ref, "mymethod"))
+      # 
+      # @overload s(*nodes, opts = {})
+      #   @param [Array<AstNode>] nodes a list of nodes. 
+      #   @param [Hash] opts any extra options (docstring, file, source) to
+      #     set on the object
+      #   @return [AstNode] an implicit node where node.type == +:list+
+      # @overload s(type, *children, opts = {})
+      #   @param [Symbol] type the node type
+      #   @param [Array<AstNode>] children any child nodes inside this one
+      #   @param [Hash] opts any extra options to set on the object
+      #   @return [AstNode] a node of type +type+.
+      # @see AstNode#initialize
       def s(*args)
         type = Symbol === args.first ? args.shift : :list
         opts = Hash === args.last ? args.pop : {}
         AstNode.node_class_for(type).new(type, args, opts)
       end
       
+      # An AST node is characterized by a type and a list of children. It
+      # is most easily represented by the s-expression {#s} such as:
+      #   # AST for "if true; 5 end":
+      #   s(s(:if, s(:var_ref, s(:kw, "true")), s(s(:int, "5")), nil))
+      # 
+      # The node type is not considered part of the list, only its children.
+      # So +ast[0]+ does not refer to the type, but rather the first child
+      # (or object). Items that are not +AstNode+ objects can be part of the
+      # list, like Strings or Symbols representing names. To return only 
+      # the AstNode children of the node, use {#children}.
       class AstNode < Array
         attr_accessor :type, :parent, :docstring, :file, :full_source, :source
         attr_accessor :source_range, :line_range, :docstring_range
@@ -14,6 +44,8 @@ module YARD
         alias comments_range docstring_range
         alias to_s source
         
+        # List of all known keywords
+        # @return [Hash] 
         KEYWORDS = { class: true, alias: true, lambda: true, do_block: true,
           def: true, defs: true, begin: true, rescue: true, rescue_mod: true,
           if: true, if_mod: true, else: true, elsif: true, case: true,
@@ -22,6 +54,11 @@ module YARD
           while: true, while_mod: true, yield: true, yield0: true, zsuper: true,
           unless: true, unless_mod: true, for: true, super: true, return0: true }
         
+        # Finds the node subclass that should be instantiated for a specific
+        # node type
+        # 
+        # @param [Symbol] type the node type to find a subclass for
+        # @return [Class] a subclass of AstNode to instantiate the node with.
         def self.node_class_for(type)
           case type
           when :params
@@ -37,6 +74,19 @@ module YARD
           end
         end
 
+        # Creates a new AST node
+        # 
+        # @param [Symbol] type the type of node being created
+        # @param [Array<AstNode>] arr the child nodes
+        # @param [Hash] opts any extra line options
+        # @option opts [Fixnum] :line (nil) the line the node starts on in source
+        # @option opts [String] :char (nil) the character number the node starts on
+        #   in source
+        # @option opts [Fixnum] :listline (nil) a special key like :line but for
+        #   list nodes
+        # @option opts [Fixnum] :listchar (nil) a special key like :char but for
+        #   list nodes
+        # @option opts [Boolean] :token (nil) whether the node represents a token
         def initialize(type, arr, opts = {})
           super(arr)
           self.type = type
@@ -47,85 +97,127 @@ module YARD
           @token = true if opts[:token]
         end
         
+        # @return [Boolean] whether the node is equal to another by checking 
+        #   the list and type
         def ==(ast)
           super && type == ast.type
         end
         
+        # @return [String] the first line of source the node represents
         def show
           "\t#{line}: #{first_line}"
         end
         
+        # @return [Range] the character range in {#full_source} represented
+        #   by the node
         def source_range
           reset_line_info unless @source_range
           @source_range
         end
         
+        # @return [Range] the line range in {#full_source} represented
+        #   by the node
         def line_range
           reset_line_info unless @line_range
           @line_range
         end
         
+        # @return [Boolean] whether the node has a {#line_range} set
         def has_line?
           @line_range ? true : false
         end
         
+        # @return [Fixnum] the starting line number of the node
         def line
           line_range && line_range.first
         end
         
+        # @return [String] the first line of source represented by the node.
         def first_line
           full_source.split(/\r?\n/)[line - 1].strip
         end
         
+        # Searches through the node and all descendents and returns the
+        # first node with a type matching any of +node_types+, otherwise
+        # returns the original node (self).
+        # 
+        # @example Returns the first method definition in a block of code
+        #   ast = YARD.parse_string("if true; def x; end end").ast
+        #   ast.jump(:def)
+        #   # => s(:def, s(:ident, "x"), s(:params, nil, nil, nil, nil, 
+        #   #      nil), s(s(:void_stmt, )))
+        # @example Returns first 'def' or 'class' statement
+        #   ast = YARD.parse_string("class X; def y; end end")
+        #   ast.jump(:def, :class).first
+        #   # => 
+        # @example If the node types are not present in the AST
+        #   ast = YARD.parse("def x; end")
+        #   ast.jump(:def)
+        # 
+        # @param [Array<Symbol>] node_types a set of node types to match
+        # @return [AstNode] the matching node, if one was found
+        # @return [self] if no node was found
         def jump(*node_types)
           traverse {|child| return(child) if node_types.include?(child.type) }
           self
         end
 
+        # @return [Array<AstNode>] the {AstNode} children inside the node
         def children
           @children ||= select {|e| AstNode === e }
         end
 
+        # @return [Boolean] whether the node is a token
         def token?
           @token
         end
         
+        # @return [Boolean] whether the node is a reference (variable, 
+        #   constant name)
         def ref?
           false
         end
         
+        # @return [Boolean] whether the node is a literal value
         def literal?
           @literal ||= type =~ /_literal$/ ? true : false
         end
         
+        # @return [Boolean] whether the node is a keyword
         def kw?
           @kw ||= KEYWORDS.has_key?(type)
         end
         
+        # @return [Boolean] whether the node is a method call
         def call?
           false
         end
         
+        # @return [Boolean] whether the node is a if/elsif/else condition
         def condition?
           false
         end
 
+        # @return [String] the filename the node was parsed from
         def file
           return parent.file if parent
           @file
         end
 
+        # @return [String] the full source that the node was parsed from
         def full_source
           return parent.full_source if parent
           return @full_source if @full_source
           return IO.read(@file) if file && File.exist?(file)
         end
 
+        # @return [String] the parse of {#full_source} that the node represents
         def source
           return parent.full_source[source_range] if parent
           full_source
         end
 
+        # @return [nil] pretty prints the node
         def pretty_print(q)
           objs = [*self.dup, :__last__]
           objs.unshift(type) if type && type != :list
@@ -159,11 +251,17 @@ module YARD
           end
         end
 
+        # @return [String] inspects the object
         def inspect 
           typeinfo = type && type != :list ? ':' + type.to_s + ', ' : ''
           's(' + typeinfo + map(&:inspect).join(", ") + ')'
         end
 
+        # Traverses the object and yields each node (including descendents) in order.
+        # 
+        # @yield each descendent node in order
+        # @yieldparam [AstNode] self, or a child/descendent node
+        # @return [nil] 
         def traverse
           nodes = [self]
           nodes.each.with_index do |node, index|
@@ -174,6 +272,8 @@ module YARD
         
         private
 
+        # Resets line information
+        # @return [nil] 
         def reset_line_info
           if size == 0
             self.line_range = @fallback_line
@@ -227,6 +327,7 @@ module YARD
 
         def parameters(include_block_param = true)
           params = self[1 + index_adjust]
+          return nil unless params
           params = call_has_paren? ? params.first : params
           include_block_param ? params : params[0...-1]
         end