yard 0.5.8 → 0.6.0

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

@@ -1,3 +1,4 @@
+# (see Ruby::ModuleHandler)
 class YARD::Handlers::Ruby::Legacy::ModuleHandler < YARD::Handlers::Ruby::Legacy::Base
   handles TkMODULE
   

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

@@ -1,3 +1,4 @@
+# (see Ruby::ProcessHandler)
 class YARD::Handlers::Ruby::Legacy::ProcessHandler < YARD::Handlers::Ruby::Legacy::Base
   handles /\Aprocess(?:\(?|\s)/
   namespace_only

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

@@ -1,3 +1,4 @@
+# (see Ruby::VisibilityHandler)
 class YARD::Handlers::Ruby::Legacy::VisibilityHandler < YARD::Handlers::Ruby::Legacy::Base
   handles /\A(protected|private|public)(\s|\(|$)/
   

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

@@ -1,3 +1,4 @@
+# (see Ruby::YieldHandler)
 class YARD::Handlers::Ruby::Legacy::YieldHandler < YARD::Handlers::Ruby::Legacy::Base
   handles TkYIELD
   

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

@@ -1,3 +1,4 @@
+# Handles a conditional inside a method
 class YARD::Handlers::Ruby::MethodConditionHandler < YARD::Handlers::Ruby::Base
   handles :if_mod, :unless_mod
   

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

@@ -1,3 +1,4 @@
+# Handles a method definition
 class YARD::Handlers::Ruby::MethodHandler < YARD::Handlers::Ruby::Base
   handles :def, :defs
   
@@ -5,8 +6,11 @@ class YARD::Handlers::Ruby::MethodHandler < YARD::Handlers::Ruby::Base
     nobj = namespace
     mscope = scope
     if statement.type == :defs
+      if statement[0][0].type == :ident
+        raise YARD::Parser::UndocumentableError, 'method defined on object instance'
+      end
       meth = statement[2][0]
-      nobj = P(namespace, statement[0].source) unless statement[0].source == "self"
+      nobj = P(namespace, statement[0].source) if statement[0][0].type == :const
       args = format_args(statement[3])
       blk = statement[4]
       mscope = :class

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

@@ -1,3 +1,4 @@
+# Handles the 'include' statement to mixin a module in the instance scope
 class YARD::Handlers::Ruby::MixinHandler < YARD::Handlers::Ruby::Base
   namespace_only
   handles method_call(:include)
@@ -20,6 +21,6 @@ class YARD::Handlers::Ruby::MixinHandler < YARD::Handlers::Ruby::Base
       obj = Proxy.new(namespace, obj.value)
     end
     
-    namespace.mixins(scope) << obj
+    namespace.mixins(scope).unshift(obj) unless namespace.mixins(scope).include?(obj)
   end
 end

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

@@ -1,3 +1,4 @@
+# Handles the declaration of a module
 class YARD::Handlers::Ruby::ModuleHandler < YARD::Handlers::Ruby::Base
   handles :module
   

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

@@ -1,10 +1,16 @@
+# This is a YARD-specific handler for handler DSL syntax. It handles the 
+# "process do ... end" syntax and translates it into a "def process; end"
+# method declaration.
+# 
+# @since 0.5.4
 class YARD::Handlers::Ruby::ProcessHandler < YARD::Handlers::Ruby::Base
   handles method_call(:process)
   namespace_only
   
   process do
     return unless namespace.is_a?(ClassObject) && namespace.superclass.to_s =~ /^YARD::Handlers/
-    register MethodObject.new(namespace, :process) do |o| 
+    register MethodObject.new(namespace, :process) do |o|
+      o.docstring = "Main processing callback"
       o.signature = "def process"
       o.parameters = []
     end

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

@@ -1,3 +1,6 @@
+# Helper methods to parse @attr_* tags on a Struct class.
+# 
+# @since 0.5.6
 module YARD::Handlers::Ruby::StructHandlerMethods
   include YARD::CodeObjects
   

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

@@ -1,7 +1,9 @@
+# Handles 'private', 'protected', and 'public' calls.
 class YARD::Handlers::Ruby::VisibilityHandler < YARD::Handlers::Ruby::Base
   handles method_call(:private)
   handles method_call(:protected)
   handles method_call(:public)
+  namespace_only
   
   process do
     return if (ident = statement.jump(:ident)) == statement
@@ -10,8 +12,12 @@ class YARD::Handlers::Ruby::VisibilityHandler < YARD::Handlers::Ruby::Base
       self.visibility = ident.first
     when :fcall, :command
       statement[1].traverse do |node|
-        next unless node.type == :ident || node.type == :string_content
-        MethodObject.new(namespace, node.source, scope) {|o| o.visibility = ident.first }
+        case node.type
+        when :symbol; source = node.jump(:ident).last
+        when :string_content; source = node.source
+        else next
+        end
+        MethodObject.new(namespace, source, scope) {|o| o.visibility = ident.first }
       end
     end
   end

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

@@ -1,3 +1,4 @@
+# Handles 'yield' calls
 class YARD::Handlers::Ruby::YieldHandler < YARD::Handlers::Ruby::Base
   handles :yield, :yield0
   

data/lib/yard/logging.rb

@@ -27,6 +27,10 @@ module YARD
       super
     end
     
+    # Prints the backtrace +exc+ to the logger as error data.
+    # 
+    # @param [Array<String>] exc the backtrace list
+    # @return [void]
     def backtrace(exc)
       return unless show_backtraces
       error "#{exc.class.class_name}: #{exc.message}"
@@ -49,7 +53,9 @@ module YARD
       self.level = old_level
     end
     
-    # Log format (from Logger implementation)
+    private
+    
+    # Log format (from Logger implementation). Used by Logger internally
     def format_log(sev, time, prog, msg)
       "[#{sev.downcase}]: #{msg}\n"
     end

data/lib/yard/parser/base.rb

@@ -11,6 +11,7 @@ module YARD
     # @see #parse
     # @see #tokenize
     # @see #enumerator
+    # @since 0.5.6
     class Base
       # Convenience method to create a new parser and {#parse}
       def self.parse(source, filename = nil)

data/lib/yard/parser/c_parser.rb

@@ -18,12 +18,14 @@ module YARD
         parse_includes
       end
       
+      # @since 0.5.6
       def tokenize
         raise NotImplementedError, "no tokenization support for C/C++ files"
       end
       
       private
       
+      # @since 0.5.3
       def remove_var_prefix(var)
         var.gsub(/^rb_[mc]|^[a-z_]+/, '')
       end

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

@@ -38,12 +38,51 @@ module YARD
       # 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, :docstring_range, :source
+        attr_accessor :docstring, :docstring_range, :source, :group
         attr_writer :source_range, :line_range, :file, :full_source
         alias comments docstring
         alias comments_range docstring_range
         alias to_s source
         
+        # @return [Symbol] the node's unique symbolic type
+        attr_accessor :type
+        
+        # @return [AstNode, nil] the node's parent or nil if it is a root node.
+        attr_accessor :parent
+
+        # @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 [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
+        
         # List of all known keywords
         # @return [Hash] 
         KEYWORDS = { class: true, alias: true, lambda: true, do_block: true,
@@ -54,6 +93,8 @@ module YARD
           while: true, while_mod: true, yield: true, yield0: true, zsuper: true,
           unless: true, unless_mod: true, for: true, super: true, return0: true }
         
+        # @group Creating an AstNode
+
         # Finds the node subclass that should be instantiated for a specific
         # node type
         # 
@@ -73,7 +114,7 @@ module YARD
             AstNode
           end
         end
-
+        
         # Creates a new AST node
         # 
         # @param [Symbol] type the type of node being created
@@ -99,44 +140,13 @@ module YARD
         
         # @return [Boolean] whether the node is equal to another by checking 
         #   the list and type
+        # @private
         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
-        
+        # @group Traversing a Node
+    
         # 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).
@@ -167,6 +177,21 @@ module YARD
           @children ||= select {|e| AstNode === e }
         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 [void] 
+        def traverse
+          nodes = [self]
+          nodes.each.with_index do |node, index|
+            yield node
+            nodes.insert index+1, *node.children
+          end
+        end
+        
+        # @group Node Meta Types
+
         # @return [Boolean] whether the node is a token
         def token?
           @token
@@ -198,25 +223,30 @@ module YARD
           false
         end
 
-        # @return [String] the filename the node was parsed from
-        def file
-          return parent.file if parent
-          @file
+        # @group Getting Line Information
+        
+        # @return [Boolean] whether the node has a {#line_range} set
+        def has_line?
+          @line_range ? true : false
         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)
+        
+        # @return [Fixnum] the starting line number of the node
+        def line
+          line_range && line_range.first
         end
-
-        # @return [String] the parse of {#full_source} that the node represents
-        def source
-          return parent.full_source[source_range] if parent
-          full_source
+        
+        # @return [String] the first line of source represented by the node.
+        def first_line
+          full_source.split(/\r?\n/)[line - 1].strip
         end
 
+        # @group Printing a Node
+        
+        # @return [String] the first line of source the node represents
+        def show
+          "\t#{line}: #{first_line}"
+        end
+        
         # @return [nil] pretty prints the node
         def pretty_print(q)
           objs = [*self.dup, :__last__]
@@ -257,18 +287,7 @@ module YARD
           '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 [void] 
-        def traverse
-          nodes = [self]
-          nodes.each.with_index do |node, index|
-            yield node
-            nodes.insert index+1, *node.children
-          end
-        end
+        # @endgroup
         
         private
 

data/lib/yard/parser/ruby/legacy/ruby_lex.rb

@@ -3,6 +3,7 @@ require "irb/slex"
 
 module YARD
   module Parser::Ruby::Legacy
+    # Legacy lexical tokenizer module.
     module RubyToken
       EXPR_BEG   = :EXPR_BEG
       EXPR_MID   = :EXPR_MID
@@ -12,30 +13,50 @@ module YARD
       EXPR_DOT   = :EXPR_DOT
       EXPR_CLASS = :EXPR_CLASS
       
+      # Represents a token in the Ruby lexer
       class Token
+        # @return [Integer] the line number in the file/stream the token is
+        #   located.
+        attr_reader :line_no
+        
+        # @return [Integer] the character number in the file/stream the token
+        #   is located.
+        attr_reader :char_no
+        
+        # @return [String] the token text value
+        attr_reader :text
+        
+        # @return [Symbol] the lexical state at the token
+        attr_accessor :lex_state
+
+        # @private
         NO_TEXT = "??".freeze
 
+        # Creates a new Token object
+        # @param [Integer] line_no the line number to initialize the token to
+        # @param [Integer] char_no the char number to initialize the token to
         def initialize(line_no, char_no)
           @line_no = line_no
           @char_no = char_no
           @text    = NO_TEXT
         end
 
-        # Because we're used in contexts that expect to return a token,
-        # we set the text string and then return ourselves
+        # Chainable way to sets the text attribute
+        # 
+        # @param [String] text the new text
+        # @return [Token] this token object
         def set_text(text)
           @text = text
           self
         end
-
-        attr_reader :line_no, :char_no, :text
-        attr_accessor :lex_state
       end
       
+      # Represents a block
       class TkBlockContents < Token
         def text; '...' end
       end
       
+      # Represents an end statement
       class TkStatementEnd < Token
         def text; '' end
       end
@@ -44,9 +65,11 @@ module YARD
         attr :node
       end
       
+      # Represents whitespace
       class TkWhitespace < Token
       end
 
+      # Represents a Ruby identifier
       class TkId < Token
         def initialize(line_no, char_no, name)
           super(line_no, char_no)
@@ -55,9 +78,11 @@ module YARD
         attr :name
       end
 
+      # Represents a Ruby keyword
       class TkKW < TkId
       end
 
+      # Represents a Ruby value
       class TkVal < Token
         def initialize(line_no, char_no, value = nil)
           super(line_no, char_no)
@@ -91,11 +116,13 @@ module YARD
       class TkError < Token
       end
 
+      # @private
       def set_token_position(line, char)
         @prev_line_no = line
         @prev_char_no = char
       end
 
+      # @private
       def Token(token, value = nil)
         tk = nil
         case token
@@ -117,6 +144,7 @@ module YARD
         tk
       end
 
+      # @private
       TokenDefinitions = [
         [:TkCLASS,      TkKW,  "class",  EXPR_CLASS],
         [:TkMODULE,     TkKW,  "module", EXPR_BEG],
@@ -257,6 +285,7 @@ module YARD
       TkReading2Token = {}
       TkSymbol2Token = {}
 
+      # @private
       def RubyToken.def_token(token_n, super_token = Token, reading = nil, *opts)
         token_n = token_n.id2name unless token_n.kind_of?(String)
         if RubyToken.const_defined?(token_n)
@@ -298,11 +327,8 @@ module YARD
 
 
     # Lexical analyzer for Ruby source
-
+    # @private
     class RubyLex
-
-      ######################################################################
-      #
       # Read an input stream character by character. We allow for unlimited
       # ungetting of characters just read.
       #
@@ -330,7 +356,7 @@ module YARD
       # here document.  Once complete, it needs to read the rest of the
       # original line, but then skip the here document body.
       #
-  
+      # @private
       class BufferedReader
     
         attr_reader :line_num