yard 0.5.2 → 0.5.3

data/lib/yard/core_ext/file.rb

@@ -49,4 +49,10 @@ class File
     FileUtils.mkdir_p(dir) unless directory?(dir)
     open(file, *args, &block)
   end
+  
+  # Reads a file with binary encoding
+  # @return [String] the ascii-8bit encoded data
+  def self.read_binary(file)
+    File.open(file, 'rb') {|f| f.read }
+  end
 end

data/lib/yard/core_ext/hash.rb

@@ -1,7 +1,7 @@
 class Hash
   class << self
     def create(*args)
-      if args.is_a?(Array)
+      if args.first.is_a?(Array) && args.size == 1
         obj = new
         args.first.each {|k, v| obj[k] = v }
         obj

data/lib/yard/core_ext/string.rb

@@ -4,6 +4,7 @@ class String
   # 
   # @example
   #   "FooBar".underscore # => "foo_bar"
+  #   "Foo::Bar".underscore # => "foo/bar"
   # @return [String] the underscored lower case string
   def underscore
     gsub(/([a-z])([A-Z])/, '\1_\2').downcase.gsub('::', '/')
@@ -13,9 +14,10 @@ class String
   # 
   # @example
   #   "foo_bar_baz".camelcase # => "FooBarBaz"
+  #   "foo/bar".camelcase # => "Foo::Bar"
   # @return [String] the camel cased text
   def camelcase
-    gsub(/([a-z])_([a-z])/i) { $1 + $2.upcase }.sub(/^(.)/) { $1.upcase }.gsub('/', '::') 
+    gsub(/\/(.?)/) { "::" + $1.upcase }.gsub(/(?:^|_)(.)/) { $1.upcase }
   end
   
   # Splits text into tokens the way a shell would, handling quoted

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

@@ -26,29 +26,33 @@ class YARD::Handlers::Ruby::AttributeHandler < YARD::Handlers::Ruby::Base
 
     # Add all attributes
     validated_attribute_names(params).each do |name|
-      namespace.attributes[scope][name] = SymbolHash[:read => nil, :write => nil]
+      namespace.attributes[scope][name] ||= SymbolHash[:read => nil, :write => nil]
       
       # Show their methods as well
       {:read => name, :write => "#{name}="}.each do |type, meth|
-        next unless (type == :read ? read : write)
-        
-        namespace.attributes[scope][name][type] = MethodObject.new(namespace, meth, scope) do |o|
-          if type == :write
-            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}"
+        if (type == :read ? read : write)
+          namespace.attributes[scope][name][type] = MethodObject.new(namespace, meth, scope) do |o|
+            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
+            o.docstring = statement.comments.to_s.empty? ? doc : statement.comments
           end
-          o.source ||= full_src
-          o.signature ||= src
-          o.docstring = statement.comments.to_s.empty? ? doc : statement.comments
+
+          # Register the objects explicitly
+          register namespace.attributes[scope][name][type]
+        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
-        
-        # Register the objects explicitly
-        register namespace.attributes[scope][name][type]
       end
     end
   end

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

@@ -29,25 +29,29 @@ class YARD::Handlers::Ruby::Legacy::AttributeHandler < YARD::Handlers::Ruby::Leg
       
       # Show their methods as well
       {:read => name, :write => "#{name}="}.each do |type, meth|
-        next unless (type == :read ? read : write)
-        
-        namespace.attributes[scope][name][type] = MethodObject.new(namespace, meth, scope) do |o|
-          if type == :write
-            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}"
+        if (type == :read ? read : write)
+          namespace.attributes[scope][name][type] = MethodObject.new(namespace, meth, scope) do |o|
+            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
+            o.docstring = statement.comments.to_s.empty? ? doc : statement.comments
           end
-          o.source ||= full_src
-          o.signature ||= src
-          o.docstring = statement.comments.to_s.empty? ? doc : statement.comments
-        end
         
-        # Register the objects explicitly
-        register namespace.attributes[scope][name][type]
+          # Register the objects explicitly
+          register namespace.attributes[scope][name][type]
+        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

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

@@ -41,6 +41,14 @@ class YARD::Handlers::Ruby::Legacy::MethodHandler < YARD::Handlers::Ruby::Legacy
         obj.docstring.add_tag(YARD::Tags::Tag.new(:return, "", "Boolean"))
       end
     end
+    
+    if info = obj.attr_info
+      if meth.to_s =~ /=$/ # writer
+        info[:write] = obj if info[:read]
+      else
+        info[:read] = obj if info[:write]
+      end
+    end
 
     parse_block(:owner => obj) # mainly for yield/exceptions
   end

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

@@ -22,7 +22,6 @@ 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)
@@ -40,6 +39,14 @@ class YARD::Handlers::Ruby::MethodHandler < YARD::Handlers::Ruby::Base
       end
     end
     
+    if info = obj.attr_info
+      if meth.to_s =~ /=$/ # writer
+        info[:write] = obj if info[:read]
+      else
+        info[:read] = obj if info[:write]
+      end
+    end
+    
     parse_block(blk, :owner => obj) # mainly for yield/exceptions
   end
   

data/lib/yard/logging.rb

@@ -15,7 +15,7 @@ module YARD
     # Creates a new logger
     def initialize(*args)
       super
-      self.show_backtraces = false
+      self.show_backtraces = true
       self.level = WARN
       self.formatter = method(:format_log)
     end

data/lib/yard/parser/c_parser.rb

@@ -18,7 +18,11 @@ module YARD
         parse_includes
       end
       
-      protected
+      private
+      
+      def remove_var_prefix(var)
+        var.gsub(/^rb_[mc]|^[a-z_]+/, '')
+      end
       
       def ensure_loaded!(object, max_retries = 1)
         return if object.is_a?(CodeObjects::RootObject)
@@ -45,7 +49,7 @@ module YARD
       end
 
       def handle_module(var_name, mod_name, in_module = nil)
-        namespace = @namespaces[in_module] || (in_module ? P(in_module.gsub(/^rb_[mc]/, '')) : :root)
+        namespace = @namespaces[in_module] || (in_module ? P(remove_var_prefix(in_module)) : :root)
         ensure_loaded!(namespace)
         obj = CodeObjects::ModuleObject.new(namespace, mod_name)
         obj.add_file(@file)
@@ -55,10 +59,10 @@ module YARD
 
       def handle_class(var_name, class_name, parent, in_module = nil)
         parent = nil if parent == "0"
-        namespace = @namespaces[in_module] || (in_module ? P(in_module.gsub(/^rb_[mc]/, '')) : :root)
+        namespace = @namespaces[in_module] || (in_module ? P(remove_var_prefix(in_module)) : :root)
         ensure_loaded!(namespace)
         obj = CodeObjects::ClassObject.new(namespace, class_name)
-        obj.superclass = @namespaces[parent] || parent.gsub(/^rb_[mc]/, '') if parent
+        obj.superclass = @namespaces[parent] || remove_var_prefix(parent) if parent
         obj.add_file(@file)
         find_namespace_docstring(obj)      
         @namespaces[var_name] = obj
@@ -71,7 +75,7 @@ module YARD
         else; scope = :instance
         end
         
-        namespace = @namespaces[var_name] || P(var_name.gsub(/^rb_[mc]/, ''))
+        namespace = @namespaces[var_name] || P(remove_var_prefix(var_name))
         ensure_loaded!(namespace)
         obj = CodeObjects::MethodObject.new(namespace, name, scope)
         obj.add_file(@file)
@@ -112,17 +116,6 @@ module YARD
           comment = $1
         elsif @content =~ %r{Document-(?:class|module):\s#{object.path}\s*?(?:<\s+[:,\w]+)?\n((?>.*?\*/))}m
           comment = $1
-        else
-          if @content =~ /rb_define_(class|module)/m then
-            comments = []
-            @content.split(/(\/\*.*?\*\/)\s*?\n/m).each_with_index do |chunk, index|
-              comments[index] = chunk
-              if chunk =~ /rb_define_(class|module).*?"(#{object.name})"/m then
-                comment = comments[index-1]
-                break
-              end
-            end
-          end
         end
         object.docstring = parse_comments(object, comment) if comment
       end
@@ -344,7 +337,7 @@ module YARD
       def parse_includes
         @content.scan(/rb_include_module\s*\(\s*(\w+?),\s*(\w+?)\s*\)/) do |klass, mod|
           if klass = @namespaces[klass]
-            mod = @namespaces[mod] || P(mod.gsub(/^rb_[mc]/, ''))
+            mod = @namespaces[mod] || P(remove_var_prefix(mod))
             klass.mixins(:instance) << mod
           end
         end

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

@@ -48,6 +48,7 @@ module YARD
         @comments_line = nil
         @statement, @block, @comments = TokenList.new, nil, nil
         @last_tk, @last_ns_tk, @before_last_tk = nil, nil, nil
+        @first_line = nil
 
         while !@done && tk = @tokens.shift
           process_token(tk)
@@ -149,6 +150,10 @@ module YARD
           process_statement_end(tk)
           @state = :block
         end
+        
+        if @first_line == tk.line_no && !@statement.empty? && TkCOMMENT === tk
+          process_initial_comment(tk)
+        end
       end
 
       ##
@@ -182,6 +187,7 @@ module YARD
         
         return unless tk.class == TkCOMMENT
         return if !@statement.empty? && @comments
+        return if @first_line && tk.line_no > @first_line
         
         @comments = nil if @comments_last_line && @comments_last_line < tk.line_no - 1
         @comments_line = tk.line_no unless @comments
@@ -316,6 +322,7 @@ module YARD
       #
       # @param [RubyToken::Token] tk the token to process
       def push_token(tk)
+        @first_line = tk.line_no if @statement.empty?
         @statement << tk unless @level == 0 && [TkCOMMENT].include?(tk.class)
       end
 

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

@@ -308,12 +308,13 @@ module YARD
           comment = comment.gsub(/^\#{1,2}\s{0,1}/, '').chomp
           append_comment = @comments[lineno - 1]
           
-          if append_comment
+          if append_comment && @comments_last_column == column
             @comments.delete(lineno - 1)
             comment = append_comment + "\n" + comment
           end
           
           @comments[lineno] = comment
+          @comments_last_column = column
         end
         
         def on_parse_error(msg)

data/lib/yard/parser/source_parser.rb

@@ -46,15 +46,22 @@ module YARD
         # 
         # @param [String, Array<String>] paths a path, glob, or list of paths to
         #   parse
+        # @param [Array<String, Regexp>] excluded a list of excluded path matchers
         # @param [Fixnum] level the logger level to use during parsing. See
         #   {YARD::Logger}
         # @return the parser object that was used to parse the source. 
-        def parse(paths = ["lib/**/*.rb", "ext/**/*.c"], level = log.level)
+        def parse(paths = ["lib/**/*.rb", "ext/**/*.c"], excluded = [], level = log.level)
           log.debug("Parsing #{paths} with `#{parser_type}` parser")
+          excluded = excluded.map do |path|
+            case path
+            when Regexp; path
+            else Regexp.new(path.to_s, Regexp::IGNORECASE)
+            end
+          end
           files = [paths].flatten.
             map {|p| File.directory?(p) ? "#{p}/**/*.{rb,c}" : p }.
             map {|p| p.include?("*") ? Dir[p] : p }.flatten.
-            reject {|p| !File.file?(p) }
+            reject {|p| !File.file?(p) || excluded.any? {|re| p =~ re } }
 
           log.enter_level(level) do
             parse_in_order(*files.uniq)
@@ -143,7 +150,7 @@ module YARD
         case content
         when String
           @file = content
-          content = IO.read(content)
+          content = convert_encoding(File.read_binary(content))
           checksum = Registry.checksum_for(content)
           return if Registry.checksums[file] == checksum
 
@@ -183,6 +190,16 @@ module YARD
       end
       
       private
+      
+      # Searches for encoding line and forces encoding
+      def convert_encoding(content)
+        return content if RUBY18
+        if content =~ /\A\s*#.*coding:\s*(\S+)\s*$/
+          content.force_encoding($1)
+        else
+          content
+        end
+      end
 
       # Runs a {Handlers::Processor} object to post process the parsed statements.
       # @return [void] 

data/lib/yard/templates/helpers/html_helper.rb

@@ -44,14 +44,14 @@ module YARD
           doc.hard_breaks = false if doc.respond_to?(:hard_breaks=)
           html = doc.to_html
         when :rdoc
-          html = fix_typewriter(text)
 
           begin
             SimpleMarkupHtml.instance_variable_set("@from_path", url_for(object))
-            html = MarkupHelper::SimpleMarkup.convert(html, SimpleMarkupHtml)
+            html = MarkupHelper::SimpleMarkup.convert(text, SimpleMarkupHtml)
           end
 
           html = fix_dash_dash(html)
+          html = fix_typewriter(html)
         end
 
         html = resolve_links(html)
@@ -73,7 +73,13 @@ module YARD
       # @todo Refactor into own SimpleMarkup subclass
       def fix_typewriter(text)
         text.gsub(/\+(?! )([^\n\+]{1,900})(?! )\+/) do
-          '<tt>' + $1.gsub(/(.)/, "\\1\004") + '</tt>'
+          type_text, pre_text, no_match = $1, $`, $&
+          pre_match = pre_text.scan(%r(</?(?:pre|tt|code).*?>))
+          if pre_match.last.nil? || pre_match.last.include?('/')
+            '<tt>' + type_text + '</tt>'
+          else
+            no_match
+          end
         end
       end
       
@@ -96,7 +102,7 @@ module YARD
       # @return [String] HTML with linkified references
       def resolve_links(text)
         code_tags = 0
-        text.gsub(/<(\/)?(pre|code|tt)|(\s|>|^)\{(\S+?)(?:\s(.*?\S))?\}(?=[\W<]|.+<\/|$)/) do |str|
+        text.gsub(/<(\/)?(pre|code|tt)|\{(\S+?)(?:\s(.*?\S))?\}(?=[\W<]|.+<\/|$)/) do |str|
           tag = $2
           closed = $1
           if tag
@@ -105,14 +111,14 @@ module YARD
           end
           next str unless code_tags == 0
           
-          sp, name = $3, $4
-          title = $5 || name
+          name = $3
+          title = $4 || name
 
           case name
           when %r{://}, /^mailto:/
-            sp + link_url(name, title, :target => '_parent')
+            link_url(name, title, :target => '_parent')
           when /^file:(\S+?)(?:#(\S+))?$/
-            sp + link_file($1, title == name ? $1 : title, $2)
+            link_file($1, title == name ? $1 : title, $2)
           else
             if object.is_a?(String)
               obj = name
@@ -123,7 +129,7 @@ module YARD
                 log.warn "In file `#{object.file}':#{object.line}: Cannot resolve link to #{obj.path} from text" + (match ? ":" : ".")
                 log.warn '...' + match.gsub(/\n/,"\n\t") + '...' if match
               end
-              "#{sp}<tt>" + linkify(obj, title) + "</tt>" 
+              "<tt>" + linkify(obj, title) + "</tt>" 
             end
           end
         end
@@ -164,14 +170,21 @@ module YARD
       def link_object(obj, otitle = nil, anchor = nil, relative = true)
         return otitle if obj.nil?
         obj = Registry.resolve(object, obj, true, true) if obj.is_a?(String)
-        title = otitle ? otitle.to_s : h(obj.path)
-        title = "Top Level Namespace" if title == "" && obj.root?
+        if !otitle && obj.root?
+          title = "Top Level Namespace"
+        elsif otitle
+          title = otitle.to_s
+        elsif object.is_a?(CodeObjects::Base)
+          title = h(object.relative_path(obj))
+        else
+          title = h(obj.to_s)
+        end
         return title unless serializer
 
         return title if obj.is_a?(CodeObjects::Proxy)
       
         link = url_for(obj, anchor, relative)
-        link ? link_url(link, title) : title
+        link ? link_url(link, title, :title => "#{obj.path} (#{obj.type})") : title
       end
       
       def link_url(url, title = nil, params = {})
@@ -244,12 +257,9 @@ module YARD
         link + '.html' + (anchor ? '#' + urlencode(anchor) : '')
       end
       
-      def signature(meth, link = true, show_extras = true)
-        # use first overload tag if it has a return type and method itself does not
-        if !meth.tag(:return) && meth.tags(:overload).size == 1 && meth.tag(:overload).tag(:return)
-          meth = meth.tag(:overload)
-        end
-        
+      def signature_types(meth, link = true)
+        meth = convert_method_to_overload(meth)
+
         type = options[:default_return] || ""
         if meth.tag(:return) && meth.tag(:return).types
           types = meth.tags(:return).map {|t| t.types ? t.types : [] }.flatten
@@ -268,16 +278,22 @@ module YARD
         elsif !type.empty?
           type = link ? h(type) : format_types([type], false)
         end
+        type = "(#{type}) " unless type.empty?
+        type
+      end
+      
+      def signature(meth, link = true, show_extras = true, full_attr_name = true)
+        meth = convert_method_to_overload(meth)
         
+        type = signature_types(meth, link)
         scope = meth.scope == :class ? "+" : "-"
-        type = "(#{type}) " unless type.empty?
-        name = meth.name
+        name = full_attr_name ? meth.name : meth.name.to_s.gsub(/=$/, '')
         blk = format_block(meth)
-        args = format_args(meth)
+        args = !full_attr_name && meth.writer? ? "" : format_args(meth)
         extras = []
         extras_text = ''
         if show_extras
-          if meth.is_attribute? && rw = meth.namespace.attributes[meth.scope][meth.name]
+          if rw = meth.attr_info
             attname = [rw[:read] ? 'read' : nil, rw[:write] ? 'write' : nil].compact
             attname = attname.size == 1 ? attname.join('') + 'only' : nil
             extras << attname if attname
@@ -315,6 +331,16 @@ module YARD
       def html_syntax_highlight_plain(source)
         h(source)
       end
+      
+      private
+      
+      def convert_method_to_overload(meth)
+        # use first overload tag if it has a return type and method itself does not
+        if !meth.tag(:return) && meth.tags(:overload).size == 1 && meth.tag(:overload).tag(:return)
+          return meth.tag(:overload)
+        end
+        meth
+      end
     end
   end
 end