yard 0.6.4 → 0.6.5

data/lib/yard/docstring.rb

@@ -24,6 +24,10 @@ module YARD
     
     # @return [String] the raw documentation (including raw tag text)
     attr_reader :all
+    
+    # @return [Boolean] whether the docstring was started with "##"
+    attr_reader :hash_flag
+    def hash_flag=(v) @hash_flag = v == nil ? false : v end
 
     # Matches a tag at the start of a comment line
     META_MATCH = /^@([a-z_0-9]+)(?:\s+(.*))?$/i
@@ -43,6 +47,7 @@ module YARD
     def initialize(content = '', object = nil)
       @object = object
       @summary = nil
+      @hash_flag = false
       
       self.all = content
     end

data/lib/yard/handlers/base.rb

@@ -4,7 +4,7 @@ module YARD
     # an operation on an object's namespace but the namespace could
     # not be resolved.
     class NamespaceMissingError < Parser::UndocumentableError
-      # The object the error occured on
+      # The object the error occurred on
       # @return [CodeObjects::Base] a code object
       attr_accessor :object
       
@@ -394,6 +394,7 @@ module YARD
 
           # Add docstring if there is one.
           object.docstring = statement.comments if statement.comments
+          object.docstring.hash_flag = statement.comments_hash_flag
           object.docstring.line_range = statement.comments_range
           
           # Add group information
@@ -446,6 +447,7 @@ module YARD
       #   finishes processing.
       def ensure_loaded!(object, max_retries = 1)
         return if object.root?
+        return object unless object.is_a?(Proxy)
         unless parser.load_order_errors
           if object.is_a?(Proxy)
             raise NamespaceMissingError, object

data/lib/yard/handlers/processor.rb

@@ -14,7 +14,7 @@ module YARD
     class Processor
 
       class << self
-        # Registeres a new namespace for handlers of the given type.
+        # Registers a new namespace for handlers of the given type.
         # @since 0.6.0
         def register_handler_namespace(type, ns)
           namespace_for_handler[type] = ns

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

@@ -5,7 +5,7 @@ class YARD::Handlers::Ruby::AliasHandler < YARD::Handlers::Ruby::Base
   process do
     names = []
     if statement.type == :alias
-      names = statement.map {|o| o.jump(:ident, :op, :kw, :const).first }
+      names = statement.map {|o| o.jump(:ident, :op, :kw, :const).source }
     elsif statement.call?
       statement.parameters(false).each do |obj|
         case obj.type
@@ -24,14 +24,15 @@ class YARD::Handlers::Ruby::AliasHandler < YARD::Handlers::Ruby::Base
       o.visibility = visibility
       o.scope = scope
       o.add_file(parser.file, statement.line)
-      o.docstring = statement.comments
+    end
 
-      if old_obj
-        o.signature = old_obj.signature
-        o.source = old_obj.source
-      else
-        o.signature = "def #{new_meth}" # this is all we know.
-      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.object = new_obj
+    else
+      new_obj.signature = "def #{new_meth}" # this is all we know.
     end
     
     namespace.aliases[new_obj] = old_meth

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

@@ -23,14 +23,14 @@ class YARD::Handlers::Ruby::ClassHandler < YARD::Handlers::Ruby::Base
       elsif klass
         create_attributes(klass, members_from_tags(klass))
       end
-      parse_block(statement[2], namespace: klass)
+      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)
+        parse_block(statement[1], :namespace => namespace, :scope => :class)
       else
         classname = statement[0].source
         proxy = Proxy.new(namespace, classname)
@@ -46,7 +46,7 @@ class YARD::Handlers::Ruby::ClassHandler < YARD::Handlers::Ruby::Base
 
         if classname[0,1] =~ /[A-Z]/
           register ClassObject.new(namespace, classname) if Proxy === proxy
-          parse_block(statement[1], namespace: proxy, scope: :class)
+          parse_block(statement[1], :namespace => proxy, :scope => :class)
         else
           raise YARD::Parser::UndocumentableError, "class '#{classname}'"
         end

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

@@ -5,7 +5,7 @@ class YARD::Handlers::Ruby::Legacy::AliasHandler < YARD::Handlers::Ruby::Legacy:
   process do
     if TkALIAS === statement.tokens.first 
       tokens = statement.tokens[2..-1].to_s.split(/\s+/)
-      names = [tokens[0], tokens[1]].map {|t| t.gsub(/^:/, '') }
+      names = [tokens[0], tokens[1]].map {|t| t.gsub(/^:(['"])?(.+?)\1?$|^(:)(.+)/, '\2') }
     else
       names = tokval_list(statement.tokens[2..-1], :attr)
     end
@@ -18,13 +18,15 @@ class YARD::Handlers::Ruby::Legacy::AliasHandler < YARD::Handlers::Ruby::Legacy:
       o.scope = scope
       o.add_file(parser.file, statement.tokens.first.line_no)
       o.docstring = statement.comments
+    end
 
-      if old_obj
-        o.signature = old_obj.signature
-        o.source = old_obj.source
-      else
-        o.signature = "def #{new_meth}" # this is all we know.
-      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.object = new_obj
+    else
+      new_obj.signature = "def #{new_meth}" # this is all we know.
     end
     
     namespace.aliases[new_obj] = old_meth

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

@@ -31,6 +31,13 @@ class YARD::Handlers::Ruby::Legacy::MethodHandler < YARD::Handlers::Ruby::Legacy
       o.explicit = true
       o.parameters = args
     end
+    
+    # delete any aliases referencing old method
+    nobj.aliases.each do |aobj, name|
+      next unless name == obj.name
+      nobj.aliases.delete(aobj)
+    end if nobj.is_a?(NamespaceObject)
+    
     if mscope == :instance && meth == "initialize"
       unless obj.has_tag?(:return)
         obj.docstring.add_tag(YARD::Tags::Tag.new(:return, 

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

@@ -0,0 +1,21 @@
+# (see Ruby::PrivateConstantHandler)
+class YARD::Handlers::Ruby::Legacy::PrivateConstantHandler < YARD::Handlers::Ruby::Legacy::Base
+  namespace_only
+  handles /\Aprivate_constant(\s|\(|$)/
+  
+  process do
+    tokval_list(statement.tokens[2..-1], :attr, TkCONSTANT).each do |name|
+      privatize_constant name
+    end
+  end
+  
+  private
+  
+  def privatize_constant(name)
+    const = Proxy.new(namespace, name)
+    ensure_loaded!(const)
+    const.visibility = :private
+  rescue NamespaceMissingError
+    raise UndocumentableError, "private visibility set on unrecognized constant: #{name}"
+  end
+end

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

@@ -3,6 +3,6 @@ class YARD::Handlers::Ruby::MethodConditionHandler < YARD::Handlers::Ruby::Base
   handles :if_mod, :unless_mod
   
   process do
-    parse_block(statement.then_block, owner: owner)
+    parse_block(statement.then_block, :owner => owner)
   end
 end

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

@@ -28,6 +28,13 @@ class YARD::Handlers::Ruby::MethodHandler < YARD::Handlers::Ruby::Base
       o.explicit = true
       o.parameters = args
     end
+    
+    # delete any aliases referencing old method
+    nobj.aliases.each do |aobj, name|
+      next unless name == obj.name
+      nobj.aliases.delete(aobj)
+    end if nobj.is_a?(NamespaceObject)
+    
     if mscope == :instance && meth == "initialize"
       unless obj.has_tag?(:return)
         obj.docstring.add_tag(YARD::Tags::Tag.new(:return, 

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

@@ -0,0 +1,36 @@
+# Sets visibility of a constant (class, module, const)
+class YARD::Handlers::Ruby::PrivateConstantHandler < YARD::Handlers::Ruby::Base
+  namespace_only
+  handles method_call(:private_constant)
+  
+  process do
+    errors = []
+    statement.parameters.each do |param|
+      next unless AstNode === param
+      begin
+        privatize_constant(param)
+      rescue UndocumentableError => err
+        errors << err.message
+      end
+    end
+    if errors.size > 0
+      msg = errors.size == 1 ? ": #{errors[0]}" : "s: #{errors.join(", ")}"
+      raise UndocumentableError, "private constant#{msg} for #{namespace.path}"
+    end
+  end
+  
+  private
+  
+  def privatize_constant(node)
+    if node.literal? || (node.type == :var_ref && node[0].type == :const)
+      node = node.jump(:tstring_content, :const)
+      const = Proxy.new(namespace, node[0])
+      ensure_loaded!(const)
+      const.visibility = :private
+    else
+      raise UndocumentableError, "invalid argument to private_constant: #{node.source}"
+    end
+  rescue NamespaceMissingError
+    raise UndocumentableError, "private visibility set on unrecognized constant: #{node[0]}"
+  end
+end

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

@@ -38,10 +38,12 @@ 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 :docstring_hash_flag
         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 comments_hash_flag docstring_hash_flag
         alias to_s source
         
         # @return [Symbol] the node's unique symbolic type
@@ -85,13 +87,13 @@ module YARD
         
         # 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,
-          when: true, next: true, break: true, retry: true, redo: true,
-          return: true, throw: true, catch: true, until: true, until_mod: true,
-          while: true, while_mod: true, yield: true, yield0: true, zsuper: true,
-          unless: true, unless_mod: true, for: true, super: true, return0: true }
+        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,
+          :when => true, :next => true, :break => true, :retry => true, :redo => true,
+          :return => true, :throw => true, :catch => true, :until => true, :until_mod => true,
+          :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
 
@@ -108,10 +110,16 @@ module YARD
             MethodCallNode
           when :if, :elsif, :if_mod, :unless, :unless_mod
             ConditionalNode
-          when /_ref\Z/
-            ReferenceNode
           else
-            AstNode
+            if type.to_s =~ /_ref\Z/
+              ReferenceNode
+            elsif type.to_s =~ /_literal\Z/
+              LiteralNode
+            elsif KEYWORDS.has_key?(type)
+              KeywordNode
+            else
+              AstNode
+            end
           end
         end
         
@@ -147,7 +155,7 @@ module YARD
         
         # @group Traversing a Node
     
-        # Searches through the node and all descendents and returns the
+        # Searches through the node and all descendants and returns the
         # first node with a type matching any of +node_types+, otherwise
         # returns the original node (self).
         # 
@@ -177,10 +185,10 @@ module YARD
           @children ||= select {|e| AstNode === e }
         end
 
-        # Traverses the object and yields each node (including descendents) in order.
+        # Traverses the object and yields each node (including descendants) in order.
         # 
-        # @yield each descendent node in order
-        # @yieldparam [AstNode] self, or a child/descendent node
+        # @yield each descendant node in order
+        # @yieldparam [AstNode] self, or a child/descendant node
         # @return [void] 
         def traverse
           nodes = [self]
@@ -205,12 +213,12 @@ module YARD
         
         # @return [Boolean] whether the node is a literal value
         def literal?
-          @literal ||= type =~ /_literal$/ ? true : false
+          false
         end
         
         # @return [Boolean] whether the node is a keyword
         def kw?
-          @kw ||= KEYWORDS.has_key?(type)
+          false
         end
         
         # @return [Boolean] whether the node is a method call
@@ -249,26 +257,27 @@ module YARD
         
         # @return [nil] pretty prints the node
         def pretty_print(q)
-          objs = [*self.dup, :__last__]
+          objs = self.dup + [:__last__]
           objs.unshift(type) if type && type != :list
 
-          options = {}
+          options = []
           if @docstring
-            options[:docstring] = docstring
+            options << ['docstring', docstring]
           end
           if @source_range || @line_range
-            options[:line] = line_range
-            options[:source] = source_range
+            options << ['line', line_range]
+            options << ['source', source_range]
           end
           objs.pop if options.size == 0
 
           q.group(3, 's(', ')') do
             q.seplist(objs, nil, :each) do |v| 
               if v == :__last__
-                q.seplist(options, nil, :each) do |k, v2| 
+                q.seplist(options, nil, :each) do |arr|
+                  k, v2 = *arr
                   q.group(3) do 
                     q.text k
-                    q.group(3) do 
+                    q.group(3) do
                       q.text ': '
                       q.pp v2 
                     end
@@ -323,6 +332,14 @@ module YARD
         end
       end
       
+      class LiteralNode < AstNode
+        def literal?; true end
+      end
+      
+      class KeywordNode < AstNode
+        def kw?; true end
+      end
+      
       class ParameterNode < AstNode
         def required_params; self[0] end
         def required_end_params; self[3] end
@@ -360,7 +377,7 @@ module YARD
         end
       end
       
-      class ConditionalNode < AstNode
+      class ConditionalNode < KeywordNode
         def condition?; true end
         def condition; first end
         def then_block; self[1] end

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

@@ -20,6 +20,9 @@ module YARD
           def enumerator
             @parse
           end
+          
+          def encoding_line; @parse.encoding_line end
+          def shebang_line; @parse.shebang_line end
         end
       end
     end

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

@@ -3,11 +3,13 @@ module YARD
     class Statement 
       attr_reader :tokens, :comments, :block
       attr_accessor :comments_range, :group
+      attr_accessor :comments_hash_flag
 
       def initialize(tokens, block = nil, comments = nil)
         @tokens = tokens
         @block  = block
         @comments = comments
+        @comments_hash_flag = false
       end
       
       def first_line

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

@@ -2,6 +2,8 @@ module YARD
   module Parser::Ruby::Legacy
     class StatementList < Array
       include RubyToken
+      
+      attr_accessor :shebang_line, :encoding_line
 
       # The following list of tokens will require a block to be opened 
       # if used at the beginning of a statement.
@@ -13,6 +15,8 @@ module YARD
       # @param [TokenList, String] content the tokens to create the list from
       def initialize(content)
         @group = nil
+        @shebang_line = nil
+        @encoding_line = nil
         if content.is_a? TokenList
           @tokens = content.dup
         elsif content.is_a? String
@@ -41,6 +45,7 @@ module YARD
         @done = false
         @current_block = nil
         @comments_line = nil
+        @comments_hash_flag = nil
         @statement, @block, @comments = TokenList.new, nil, nil
         @last_tk, @last_ns_tk, @before_last_tk, @before_last_ns_tk = nil, nil, nil, nil
         @first_line = nil
@@ -50,8 +55,10 @@ module YARD
 
           @before_last_tk = @last_tk
           @last_tk = tk # Save last token
-          @before_last_ns_tk = @last_ns_tk
-          @last_ns_tk = tk unless [TkSPACE, TkNL, TkEND_OF_SCRIPT].include? tk.class
+          unless [TkSPACE, TkNL, TkEND_OF_SCRIPT].include? tk.class
+            @before_last_ns_tk = @last_ns_tk
+            @last_ns_tk = tk
+          end
         end
 
         # Return the code block with starting token and initial comments
@@ -65,6 +72,7 @@ module YARD
           stmt.group = @group
           if @comments && @comments_line
             stmt.comments_range = (@comments_line..(@comments_line + @comments.size - 1))
+            stmt.comments_hash_flag = @comments_hash_flag
           end
           stmt
         else
@@ -209,10 +217,24 @@ module YARD
       # @return [Boolean] whether or not +tk+ was processed as an initial comment
       def process_initial_comment(tk)
         if @statement.empty? && (@comments_last_line || 0) < tk.line_no - 2
-          @comments = nil 
+          @comments = nil
         end
         
         return unless tk.class == TkCOMMENT
+
+        case tk.text
+        when Parser::SourceParser::SHEBANG_LINE
+          if !@last_ns_tk && !@encoding_line
+            @shebang_line = tk.text
+            return
+          end
+        when Parser::SourceParser::ENCODING_LINE
+          if (@last_ns_tk.class == TkCOMMENT && @last_ns_tk.text == @shebang_line) ||
+              !@last_ns_tk
+            @encoding_line = tk.text
+            return
+          end
+        end
         return if !@statement.empty? && @comments
         return if @first_line && tk.line_no > @first_line
         
@@ -228,7 +250,8 @@ module YARD
           @comments += tk.text.gsub(/\A=begin.*\r?\n|\r?\n=end.*\r?\n?\Z/, '').split(/\r?\n/)
           @comments_last_line = tk.line_no + lines
         else
-          @comments << tk.text.gsub(/^#+\s{0,1}/, '')
+          @comments << tk.text.gsub(/^(#+)\s{0,1}/, '')
+          @comments_hash_flag = $1 == '##' if @comments_hash_flag == nil
           @comments_last_line = tk.line_no
         end
         @comments.pop if @comments.size == 1 && @comments.first =~ /^\s*$/