yard 0.4.0 → 0.5.0

data/lib/yard/serializers/base.rb

@@ -37,7 +37,7 @@ module YARD
       # 
       # @abstract Should run code after serialization.
       # @param [String] data the data that was serialized.
-      # @return [nil]
+      # @return [void]
       def after_serialize(data); end
       
       # Serializes an object.

data/lib/yard/serializers/yardoc_serializer.rb

@@ -0,0 +1,113 @@
+module YARD
+  class StubProxy
+    instance_methods.each {|m| undef_method(m) unless m.to_s =~ /^__|^object_id$/ }
+
+    def _dump(depth) @path end
+    def self._load(str) new(str) end
+    
+    def initialize(path, transient = false) 
+      @path = path
+      @transient = transient
+    end
+    
+    def method_missing(meth, *args, &block)
+      return true if meth == :respond_to? && args.first == :_dump
+      return Registry.at(@path).send(meth, *args, &block) if @transient
+      @object ||= Registry.at(@path)
+      @object.send(meth, *args, &block)
+    rescue NoMethodError => e
+      e.backtrace.delete_if {|l| l[0, __FILE__.size] == __FILE__ }
+      raise
+    end
+  end
+
+  module Serializers
+    class YardocSerializer < FileSystemSerializer
+      def initialize(yfile)
+        super(:basepath => yfile, :extension => 'dat')
+      end
+      
+      def objects_path; File.join(basepath, 'objects') end
+      def proxy_types_path; File.join(basepath, 'proxy_types') end
+      def checksums_path; File.join(basepath, 'checksums') end
+      
+      def serialized_path(object)
+        path = case object
+        when String, Symbol
+          object = object.to_s
+          if object =~ /#/
+            object += '_i'
+          elsif object =~ /\./
+            object += '_c'
+          end
+          object.split(/::|\.|#/).map do |p|
+            p.gsub(/[^\w\.-]/) do |x|
+              encoded = '_'
+
+              x.each_byte { |b| encoded << ("%X" % b) }
+              encoded
+            end
+          end.join('/') + '.' + extension
+        when YARD::CodeObjects::RootObject
+          'root.dat'
+        else
+          super(object)
+        end
+        File.join('objects', path)
+      end
+      
+      def serialize(object)
+        super(object, dump(object))
+      end
+      
+      def deserialize(path, is_path = false)
+        path = File.join(basepath, serialized_path(path)) unless is_path
+        if File.file?(path)
+          log.debug "Deserializing #{path}..."
+          Marshal.load(File.read(path))
+        else
+          log.debug "Could not find #{path}"
+          nil
+        end
+      end
+      
+      private
+      
+      def dump(object)
+        Marshal.dump(internal_dump(object, true))
+      end
+      
+      def internal_dump(object, first_object = false)
+        if !first_object && object.is_a?(CodeObjects::Base) && 
+            !(Tags::OverloadTag === object)
+          return StubProxy.new(object.path, true)
+        end
+        
+        if object.is_a?(Hash) || object.is_a?(Array) || 
+            object.is_a?(CodeObjects::Base) ||
+            object.instance_variables.size > 0
+          object = object.dup
+        end
+        
+        object.instance_variables.each do |ivar|
+          ivar_obj = object.instance_variable_get(ivar)
+          ivar_obj_dump = internal_dump(ivar_obj)
+          object.instance_variable_set(ivar, ivar_obj_dump)
+        end
+        
+        case object
+        when Hash
+          list = object.map do |k, v|
+            [k, v].map {|item| internal_dump(item) }
+          end
+          object.replace(Hash[list])
+        when Array
+          list = object.map {|item| internal_dump(item) }
+          object.replace(list)
+        end
+        
+        object
+      end
+    end
+  end
+end

data/lib/yard/tags/library.rb

@@ -46,6 +46,10 @@ module YARD
         attr_reader :labels
         attr_accessor :default_factory
         
+        def instance
+          @instance ||= new
+        end
+        
         def default_factory
           @default_factory ||= DefaultFactory.new
         end

data/lib/yard/tags/overload_tag.rb

@@ -19,26 +19,37 @@ module YARD
       end
 
       def name(prefix = false)
-        object.name(prefix)
+        return @name unless prefix
+        object.scope == :class ? @name.to_s : "#{object.send(:sep)}#{@name}"
       end
       
       def method_missing(*args, &block)
         object.send(*args, &block)
       end
+      
+      def type
+        object.type
+      end
+      
+      def is_a?(other)
+        object.is_a?(other) || self.class >= other.class || false
+      end
+      alias kind_of? is_a?
 
       private
       
       def parse_tag(raw_text)
-        @signature, text = raw_text.split(/\r?\n/, 2)
-        text ||= ""
+        @signature, text = *raw_text.split(/\r?\n/, 2)
         @signature.strip!
+        text ||= ""
         numspaces = text[/\A(\s*)/, 1].length
-        text.gsub!(/^[ \t]{#{numspaces}}/, '').strip!
+        text.gsub!(/^[ \t]{#{numspaces}}/, '')
+        text.strip!
         @docstring = Docstring.new(text, nil)
       end
       
       def parse_signature
-        if signature =~ /^(?:def)?\s*(#{CodeObjects::METHODMATCH})(?:(?:\s+|\s*\()(.*)(?:\)\s*$)?)?/m
+        if signature =~ /^(?:def\s)?\s*(#{CodeObjects::METHODMATCH})(?:(?:\s+|\s*\()(.*)(?:\)\s*$)?)?/m
           meth, args = $1, $2
           meth.gsub!(/\s+/,'')
           # FIXME refactor this code to not make use of the Handlers::Base class (tokval_list should be moved)

data/lib/yard/tags/tag.rb

@@ -1,8 +1,7 @@
 module YARD
   module Tags
     class Tag
-      attr_reader :tag_name, :text, :types, :name
-      attr_accessor :object
+      attr_accessor :tag_name, :text, :types, :name, :object
 
       ##
       # Creates a new tag object with a tag name and text. Optionally, formally declared types

data/lib/yard/templates/engine.rb

@@ -8,7 +8,7 @@ module YARD
         # Registers a new template path in {template_paths}
         # 
         # @param [String] path a new template path
-        # @return [nil] 
+        # @return [void] 
         def register_template_path(path)
           template_paths.push path
         end
@@ -86,7 +86,7 @@ module YARD
         # @param [Array<CodeObjects::Base>] objects a list of {CodeObjects::Base}
         #   objects to pass to the template
         # @param [Hash] options (see {render})
-        # @return [nil]
+        # @return [void]
         def generate(objects, options = {})
           set_default_options(options)
           options[:objects] = objects
@@ -118,7 +118,7 @@ module YARD
         # @option options [Symbol] :format (:text) the default format
         # @option options [Symbol] :type (nil) the :object's type, if provided
         # @option options [Symbol] :template (:default) the default template
-        # @return [nil]
+        # @return [void]
         def set_default_options(options = {})
           options[:format] ||= :text
           options[:type] ||= options[:object].type if options[:object]

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

@@ -72,7 +72,7 @@ module YARD
       # 
       # @todo Refactor into own SimpleMarkup subclass
       def fix_typewriter(text)
-        text.gsub(/\+(?! )([^\+]{1,900})(?! )\+/) do
+        text.gsub(/\+(?! )([^\n\+]{1,900})(?! )\+/) do
           '<tt>' + $1.gsub(/(.)/, "\\1\004") + '</tt>'
         end
       end
@@ -165,7 +165,7 @@ module YARD
         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 == Registry.root
+        title = "Top Level Namespace" if title == "" && obj.root?
         return title unless serializer
 
         return title if obj.is_a?(CodeObjects::Proxy)
@@ -177,13 +177,13 @@ module YARD
       def link_url(url, title = nil, params = {})
         params = SymbolHash.new(false).update(
           :href => url,
-          :title  => title || url
+          :title  => h(title || url)
         ).update(params)
         "<a #{tag_attrs(params)}>#{title}</a>"
       end
       
       def tag_attrs(opts = {})
-        opts.map {|k,v| "#{k}=#{v.to_s.inspect}" if v }.join(" ")
+        opts.sort_by {|k, v| k.to_s }.map {|k,v| "#{k}=#{v.to_s.inspect}" if v }.join(" ")
       end
     
       def anchor_for(object)
@@ -238,30 +238,46 @@ module YARD
         if filename == options[:readme]
           filename = 'index'
         else
-          filename = 'file.' + File.basename(filename).gsub(/\..+$/, '')
+          filename = 'file.' + File.basename(filename).gsub(/\.[^.]+$/, '')
         end
         link = File.relative_path(from, filename)
         link + '.html' + (anchor ? '#' + urlencode(anchor) : '')
       end
       
       def signature(meth, link = true, show_extras = true)
-        if link
-          type = (meth.tag(:return) && meth.tag(:return).types ? meth.tag(:return).types.first : nil) || "Object"
-          type = h(type)
-        else
-          arr = meth.tag(:return) ? [(meth.tag(:return).types || []).first].compact : []
-          arr << "Object" if arr.empty?
-          type = format_types(arr, false)
+        # 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
+        
+        type = options[:default_return] || ""
+        if meth.tag(:return) && meth.tag(:return).types
+          types = meth.tags(:return).map {|t| t.types ? t.types : [] }.flatten
+          first = link ? h(types.first) : format_types([types.first], false)
+          if types.size == 2 && types.last == 'nil'
+            type = first + '<sup>?</sup>'
+          elsif types.size == 2 && types.last =~ /^(Array)?<#{Regexp.quote types.first}>$/
+            type = first + '<sup>+</sup>'
+          elsif types.size > 2
+            type = [first, '...'].join(', ')
+          elsif types == ['void'] && options[:hide_void_return]
+            type = ""
+          else
+            type = link ? h(types.join(", ")) : format_types(types, false)
+          end
+        elsif !type.empty?
+          type = link ? h(type) : format_types([type], false)
         end
         
         scope = meth.scope == :class ? "+" : "-"
+        type = "(#{type}) " unless type.empty?
         name = meth.name
         blk = format_block(meth)
         args = format_args(meth)
         extras = []
         extras_text = ''
         if show_extras
-          if rw = meth.namespace.attributes[meth.scope][meth.name]
+          if meth.is_attribute? && rw = meth.namespace.attributes[meth.scope][meth.name]
             attname = [rw[:read] ? 'read' : nil, rw[:write] ? 'write' : nil].compact
             attname = attname.size == 1 ? attname.join('') + 'only' : nil
             extras << attname if attname
@@ -269,18 +285,36 @@ module YARD
           extras << meth.visibility if meth.visibility != :public
           extras_text = ' <span class="extras">(' + extras.join(", ") + ')</span>' unless extras.empty?
         end
-        title = "%s (%s) <strong>%s</strong>%s %s" % [scope, type, name, args, blk]
+        title = "%s %s<strong>%s</strong>%s %s" % [scope, type, h(name), args, blk]
         if link
           if meth.is_a?(YARD::CodeObjects::MethodObject)
-            link_title = "#{meth.name(true)} (#{meth.scope} #{meth.type})"
+            link_title = "#{h meth.name(true)} (#{meth.scope} #{meth.type})"
           else
-            link_title = "#{name} (#{meth.type})"
+            link_title = "#{h name} (#{meth.type})"
           end
           link_url(url_for(meth), title, :title => link_title) + extras_text
         else
           title + extras_text
         end
       end
+      
+      def html_syntax_highlight(source, type = :ruby)
+        return "" unless source
+        return source if options[:no_highlight]
+        
+        # handle !!!LANG prefix to send to html_syntax_highlight_LANG
+        if source =~ /\A[ \t]*!!!(\w+)[ \t]*\r?\n/
+          type, source = $1, $'
+          source = $'
+        end
+        
+        meth = "html_syntax_highlight_#{type}"
+        respond_to?(meth) ? send(meth, source) : h(source)
+      end
+      
+      def html_syntax_highlight_plain(source)
+        h(source)
+      end
     end
   end
 end

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

@@ -2,9 +2,7 @@ module YARD
   module Templates
     module Helpers
       module HtmlSyntaxHighlightHelper
-        def html_syntax_highlight(source)
-          return "" unless source
-          return source if options[:no_highlight]
+        def html_syntax_highlight_ruby(source)
           tokenlist = Parser::Ruby::RubyParser.parse(source, "(syntax_highlight)").tokens
           output = ""
           tokenlist.each do |s|

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

@@ -2,9 +2,7 @@ module YARD
   module Templates
     module Helpers
       module HtmlSyntaxHighlightHelper
-        def html_syntax_highlight(source)
-          return "" unless source
-          return source if options[:no_highlight]
+        def html_syntax_highlight_ruby(source)
           tokenlist = Parser::Ruby::Legacy::TokenList.new(source)
           tokenlist.map do |s| 
             prettyclass = s.class.class_name.sub(/^Tk/, '').downcase

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

@@ -2,6 +2,7 @@ module YARD
   module Templates::Helpers
     module MethodHelper
       def format_args(object)
+        return if object.parameters.nil?
         unless object.parameters.empty?
           args = object.parameters.map {|n, v| v ? "#{n} = #{v}" : n.to_s }.join(", ")
           h("(#{args})")
@@ -17,15 +18,21 @@ module YARD
       end
       
       def format_block(object)
-        if object.has_tag?(:yieldparam)
-          h "{|" + object.tags(:yieldparam).map {|t| t.name }.join(", ") + "| ... }"
+        if object.has_tag?(:yield) && object.tag(:yield).types
+          params = object.tag(:yield).types
+        elsif object.has_tag?(:yieldparam)
+          params = object.tags(:yieldparam).map {|t| t.name }
+        elsif object.has_tag?(:yield)
+          return "{ ... }"
         else
-          ""
+          params = nil
         end
+
+        params ? h("{|" + params.join(", ") + "| ... }") : ""
       end
       
       def format_lines(object)
-        return "" unless object.source
+        return "" if object.source.nil? || object.line.nil?
         i = -1
         object.source.split(/\n/).map { object.line + (i += 1) }.join("\n")
       end

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

@@ -37,7 +37,29 @@ module YARD
         end
         
         def signature(meth)
-          type = (meth.tag(:return) && meth.tag(:return).types ? meth.tag(:return).types.first : nil) || "Object"
+          # use first overload tag if it has a return type and method itself does not
+          if !meth.tag(:return) && meth.tag(:overload) && meth.tag(:overload).tag(:return)
+            meth = meth.tag(:overload)
+          end
+
+          type = options[:default_return] || ""
+          if meth.tag(:return) && meth.tag(:return).types
+            types = meth.tags(:return).map {|t| t.types ? t.types : [] }.flatten
+            first = types.first
+            if types.size == 2 && types.last == 'nil'
+              type = first + '?'
+            elsif types.size == 2 && types.last =~ /^(Array)?<#{Regexp.quote types.first}>$/
+              type = first + '+'
+            elsif types.size > 2
+              type = [first, '...'].join(', ')
+            elsif types == ['void'] && options[:hide_void_return]
+              type = ""
+            else
+              type = types.join(", ")
+            end
+          end
+          type = "(#{type})" if type.include?(',')
+          type = " -> #{type} " unless type.empty?
           scope = meth.scope == :class ? "#{meth.namespace.name}." : "#{meth.namespace.name.to_s.downcase}."
           name = meth.name
           blk = format_block(meth)
@@ -51,7 +73,7 @@ module YARD
           end
           extras << meth.visibility if meth.visibility != :public
           extras_text = '(' + extras.join(", ") + ')' unless extras.empty?
-          title = "%s%s%s %s -> %s %s" % [scope, name, args, blk, type, extras_text]
+          title = "%s%s%s %s%s%s" % [scope, name, args, blk, type, extras_text]
           title.gsub(/\s+/, ' ')
         end
       end

data/lib/yard/verifier.rb

@@ -73,20 +73,20 @@ module YARD
     # call returns nil, which means users don't need to perform
     # stringent nil checking
     # 
-    # @return [nil] 
+    # @return [void] 
     def modify_nilclass
       NilClass.send(:define_method, :method_missing) {|*args| }
     end
     
     # Returns the state of NilClass back to normal
-    # @return [nil] 
+    # @return [void] 
     def unmodify_nilclass
       NilClass.send(:undef_method, :method_missing)
     end
     
     # Creates the +__execute+ method by evaluating the expressions
     # as Ruby code
-    # @return [nil] 
+    # @return [void] 
     def create_method_from_expressions(exprs)
       expr = exprs.flatten.map {|e| "(#{parse_expression(e)})" }.join(" && ")