yard 0.2.2 → 0.2.3

data/lib/yard/generators/helpers/base_helper.rb

@@ -48,5 +48,22 @@ module YARD::Generators::Helpers
         object.type.to_s.capitalize
       end
     end
+    
+    def format_object_title(object)
+      case object
+      when YARD::CodeObjects::RootObject
+        "Top Level Namespace"
+      else
+        format_object_type(object) + ": " + object.path
+      end
+    end
+
+    def overloads(method)
+      if method.has_tag?(:overload)
+        method.tags(:overload)
+      else
+        [method]
+      end
+    end
   end
-end
+end

data/lib/yard/generators/helpers/filter_helper.rb

@@ -2,7 +2,7 @@ module YARD
   module Generators::Helpers
     module FilterHelper
       def is_method?(object)
-        object.is_a?(CodeObjects::MethodObject)
+        object.type == :method
       end
 
       def is_namespace?(object)
@@ -18,4 +18,4 @@ module YARD
       end
     end
   end
-end
+end

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

@@ -1,12 +1,12 @@
 require 'cgi'
-require 'rdoc/markup/simple_markup'
-require 'rdoc/markup/simple_markup/to_html'
 
 module YARD
   module Generators::Helpers
     module HtmlHelper
-      SimpleMarkup = SM::SimpleMarkup.new
-      SimpleMarkupHtml = SM::ToHtml.new
+      include MarkupHelper
+      include HtmlSyntaxHighlightHelper
+      
+      SimpleMarkupHtml = RUBY19 ? RDoc::Markup::ToHtml.new : SM::ToHtml.new
     
       def h(text)
         CGI.escapeHTML(text.to_s)
@@ -16,23 +16,70 @@ module YARD
         CGI.escape(text.to_s)
       end
 
-      def htmlify(text)
-        html = resolve_links SimpleMarkup.convert(text, SimpleMarkupHtml)
-        html = html.gsub(/<pre>(.+?)<\/pre>/m) { '<pre class="code">' + html_syntax_highlight(CGI.unescapeHTML($1)) + '</pre>' }
+      def htmlify(text, markup = options[:markup])
+        return text unless markup
+        load_markup_provider(markup)
+
+        case markup
+        when :markdown, :textile
+          # TODO: other libraries might be more complex
+          html = markup_class(markup).new(text).to_html
+        when :rdoc
+          html = MarkupHelper::SimpleMarkup.convert(text, SimpleMarkupHtml)
+          html = fix_dash_dash(html)
+          html = fix_typewriter(html)
+        end
+
+        html = resolve_links(html)
+        html = html.gsub(/<pre>(?:\s*<code>)?(.+?)(?:<\/code>\s*)?<\/pre>/m) do
+          str = $1
+          str = html_syntax_highlight(CGI.unescapeHTML(str)) unless options[:no_highlight]
+          %Q{<pre class="code">#{str}</pre>}
+        end
         html
       end
+      
+      # @todo Refactor into own SimpleMarkup subclass
+      def fix_typewriter(text)
+        text.gsub(/\+(?! )([^\+]{1,900})(?! )\+/, '<tt>\1</tt>')
+      end
+      
+      # Don't allow -- to turn into &#8212; element. The chances of this being
+      # some --option is far more likely than the typographical meaning.
+      # 
+      # @todo Refactor into own SimpleMarkup subclass
+      def fix_dash_dash(text)
+        text.gsub(/&#8212;(?=\S)/, '--')
+      end
 
       def resolve_links(text)
-        text.gsub(/(\s)\{(\S+?)(?:\s(.+?))?\}(?=(?:[\s\.,:!;\?][^<>]*)?<\/(?!pre))/) do 
-          name = $2
-          title = $3 || $2
-          obj = P(current_object, name)
-          if obj.is_a?(CodeObjects::Proxy)
-            log.warn "In documentation for #{current_object.path}: Cannot resolve link to #{obj.path} from text:"
-            log.warn '...' + text[/(.{0,20}\{#{Regexp.quote name}.*?\}.{0,20})/, 1].gsub(/\n/,"\n\t") + '...'
+        code_tags = 0
+        text.gsub(/<(\/)?(pre|code)|(\s|>|^)\{(\S+?)(?:\s(.*?\S))?\}(?=[\W<]|.+<\/|$)/) do |str|
+          tag = $2
+          closed = $1
+          if tag
+            code_tags += (closed ? -1 : 1)
+            next str
           end
+          next str unless code_tags == 0
+
+          sp, name = $3, $4
+          title = $5 || name
+
+          if name.include?("://")
+            sp + link_url(name, title, :target => '_parent')
+          elsif name =~ /^file:(\S+?)(?:#(\S+))?$/
+            sp + link_file($1, title == name ? $1 : title, $2)
+          else
+            obj = Registry.resolve(current_object, name, true, true)
+            if obj.is_a?(CodeObjects::Proxy)
+              match = text[/(.{0,20}\{.*?#{Regexp.quote name}.*?\}.{0,20})/, 1]
+              log.warn "In file `#{current_object.file}':#{current_object.line}: Cannot resolve link to #{obj.path} from text" + (match ? ":" : ".")
+              log.warn '...' + match.gsub(/\n/,"\n\t") + '...' if match
+            end
           
-          " <tt>" + linkify(obj, title) + "</tt>" 
+            "#{sp}<tt>" + linkify(obj, title) + "</tt>" 
+          end
         end
       end
 
@@ -55,25 +102,42 @@ module YARD
       #   to their respective descriptions.
       # 
       def format_types(typelist, brackets = true)
+        return unless typelist.is_a?(Array)
         list = typelist.map do |type| 
           "<tt>" + type.gsub(/(^|[<>])\s*([^<>#]+)\s*(?=[<>]|$)/) {|m| h($1) + linkify($2, $2) } + "</tt>"
         end
         list.empty? ? "" : (brackets ? "[#{list.join(", ")}]" : list.join(", "))
       end
+      
+      def link_file(filename, title = nil, anchor = nil)
+        link_url(url_for_file(filename, anchor), title)
+      end
     
-      def link_object(object, otitle = nil, anchor = nil)
-        object = P(current_object, object) if object.is_a?(String)
+      def link_object(object, otitle = nil, anchor = nil, relative = true)
+        object = Registry.resolve(current_object, object, true, true) if object.is_a?(String)
         title = h(otitle ? otitle.to_s : object.path)
         return title unless serializer
 
         return title if object.is_a?(CodeObjects::Proxy)
       
-        link = url_for(object, anchor)
-        link ? "<a href='#{link}' title='#{title}'>#{title}</a>" : title
+        link = url_for(object, anchor, relative)
+        link ? link_url(link, title) : title
+      end
+      
+      def link_url(url, title = nil, params = {})
+        params = SymbolHash.new(false).update(
+          :href => url,
+          :title  => 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(" ")
       end
     
       def anchor_for(object)
-        urlencode case object
+        case object
         when CodeObjects::MethodObject
           "#{object.name}-#{object.scope}_#{object.type}"
         when CodeObjects::Base
@@ -110,28 +174,19 @@ module YARD
           link = objpath
         end
       
-        link + (anchor ? '#' + anchor_for(anchor) : '')
+        link + (anchor ? '#' + urlencode(anchor_for(anchor)) : '')
       end
-
-      def html_syntax_highlight(source)
-        tokenlist = Parser::TokenList.new(source)
-        tokenlist.map do |s| 
-          prettyclass = s.class.class_name.sub(/^Tk/, '').downcase
-          prettysuper = s.class.superclass.class_name.sub(/^Tk/, '').downcase
-
-          case s
-          when Parser::RubyToken::TkWhitespace, Parser::RubyToken::TkUnknownChar
-            h s.text
-          when Parser::RubyToken::TkId
-            prettyval = h(s.text)
-            "<span class='#{prettyval} #{prettyclass} #{prettysuper}'>#{prettyval}</span>"
-          else
-            "<span class='#{prettyclass} #{prettysuper}'>#{h s.text}</span>"
-          end
-        end.join
+      
+      def url_for_file(filename, anchor = nil)
+        fromobj = current_object
+        if CodeObjects::Base === fromobj && !fromobj.is_a?(CodeObjects::NamespaceObject)
+          fromobj = fromobj.namespace
+        end
+        from = serializer.serialized_path(fromobj)
+        link = File.relative_path(from, filename)
+        link + '.html' + (anchor ? '#' + urlencode(anchor) : '')
       end
     end
   end
 end
     
-    

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

@@ -0,0 +1,49 @@
+module YARD
+  module Generators
+    module Helpers
+      module HtmlSyntaxHighlightHelper
+        def html_syntax_highlight(source)
+          tokenlist = Parser::Ruby::RubyParser.parse(source, "(syntax_highlight)").tokens
+          output = ""
+          tokenlist.each do |s|
+            output << "<span class='tstring'>" if [:tstring_beg, :regexp_beg].include?(s[0])
+            case s.first
+            when :nl, :ignored_nl, :sp
+              output << h(s.last)
+            when :ident
+              output << "<span class='id #{h(s.last)}'>#{h(s.last)}</span>"
+            else
+              output << "<span class='#{s.first}'>#{h(s.last)}</span>"
+            end
+            output << "</span>" if [:tstring_end, :regexp_end].include?(s[0])
+          end
+          output
+        rescue Parser::Ruby::ParserSyntaxError
+          source
+        end
+
+        def html_syntax_highlight_legacy(source)
+          tokenlist = Parser::Ruby::Legacy::TokenList.new(source)
+          tokenlist.map do |s| 
+            prettyclass = s.class.class_name.sub(/^Tk/, '').downcase
+            prettysuper = s.class.superclass.class_name.sub(/^Tk/, '').downcase
+
+            case s
+            when Parser::Ruby::Legacy::RubyToken::TkWhitespace, Parser::Ruby::Legacy::RubyToken::TkUnknownChar
+              h s.text
+            when Parser::Ruby::Legacy::RubyToken::TkId
+              prettyval = h(s.text)
+              "<span class='#{prettyval} #{prettyclass} #{prettysuper}'>#{prettyval}</span>"
+            else
+              "<span class='#{prettyclass} #{prettysuper}'>#{h s.text}</span>"
+            end
+          end.join
+        end
+        
+        if RUBY18
+          alias html_syntax_highlight html_syntax_highlight_legacy
+        end
+      end
+    end
+  end
+end

data/lib/yard/generators/helpers/markup_helper.rb

@@ -0,0 +1,86 @@
+if RUBY19
+  require 'rdoc/markup'
+  require 'rdoc/markup/to_html'
+else
+  require 'rdoc/markup/simple_markup'
+  require 'rdoc/markup/simple_markup/to_html'
+  require 'rubygems'
+end
+
+module YARD
+  module Generators::Helpers
+    module MarkupHelper
+      MARKUP_PROVIDERS = {
+        :markdown => [
+          {:lib => :bluecloth, :const => 'BlueCloth'},
+          {:lib => :maruku, :const => 'Maruku'},
+          {:lib => :"rpeg-markdown", :const => "PEGMarkdown"},
+          {:lib => :rdiscount, :const => "RDiscount"}
+        ],
+        :textile => [
+          {:lib => :redcloth, :const => 'RedCloth'}
+        ]
+      }
+      
+      SimpleMarkup = RUBY19 ? RDoc::Markup.new : SM::SimpleMarkup.new
+
+      private
+      
+      # Attempts to load the first valid markup provider in {MARKUP_PROVIDERS}.
+      # If a provider is specified, immediately try to load it.
+      # 
+      # On success this sets `@markup_provider` and `@markup_class` to
+      # the provider name and library constant class/module respectively for
+      # the loaded proider.
+      # 
+      # On failure this method will inform the user that no provider could be
+      # found and exit the program.
+      def load_markup_provider(type = options[:markup])
+        return if type == :rdoc || (@markup_cache && @markup_cache[type])
+        @markup_cache ||= {}
+        @markup_cache[type] ||= {}
+        
+        providers = MARKUP_PROVIDERS[type]
+        if options[:markup_provider]
+          providers = MARKUP_PROVIDERS[type].select {|p| p[:lib] == options[:markup_provider] }
+        end
+        
+        if providers == nil || providers.empty?
+          STDERR.puts "Invalid markup type '#{options[:markup]}'"
+          exit
+        end
+        
+        # Search for provider, return the library class name as const if found
+        providers.each do |provider|
+          begin require provider[:lib].to_s; rescue LoadError; next end
+          @markup_cache[type][:provider] = provider[:lib] # Cache the provider
+          @markup_cache[type][:class] = Kernel.const_get(provider[:const])
+          return
+        end
+        
+        # Show error message telling user to install first potential provider
+        name, lib = providers.first[:const], providers.first[:lib]
+        STDERR.puts "Missing #{name} gem for #{options[:markup].to_s.capitalize} formatting. Install it with `gem install #{lib}`"
+        exit
+      end
+      
+      # Gets the markup provider class/module constant for a markup type
+      # Call {#load_markup_provider} before using this method.
+      # 
+      # @param [Symbol] the markup type (:rdoc, :markdown, etc.)
+      # @return [Class] the markup class
+      def markup_class(type = options[:markup])
+        type == :rdoc ? SimpleMarkup : @markup_cache[type][:class]
+      end
+      
+      # Gets the markup provider name for a markup type
+      # Call {#load_markup_provider} before using this method.
+      # 
+      # @param [Symbol] the markup type (:rdoc, :markdown, etc.)
+      # @return [Symbol] the markup provider name (usually the gem name of the library)
+      def markup_provider(type = options[:markup])
+        type == :rdoc ? nil : @markup_cache[type][:provider]
+      end
+    end
+  end
+end

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

@@ -2,17 +2,18 @@ module YARD
   module Generators::Helpers
     module MethodHelper
       def format_args(object)
-        if object.signature
-          h object.signature[/#{Regexp.quote object.name.to_s}\s*(.*)/, 1]
+        unless object.parameters.empty?
+          args = object.parameters.map {|n, v| v ? "#{n} = #{v}" : n.to_s }.join(", ")
+          h("(#{args})")
         else
-          h "def #{object.name}"
+          ""
         end
       end
       
       def format_return_types(object)
-        if object.has_tag?(:return) && !object.tag(:return).types.empty?
-          format_types [object.tag(:return).types.first], false
-        end
+        return unless object.has_tag?(:return) && object.tag(:return).types
+        return if object.tag(:return).types.empty?
+        format_types [object.tag(:return).types.first], false
       end
       
       def format_block(object)
@@ -22,6 +23,21 @@ module YARD
           ""
         end
       end
+      
+      def format_lines(object)
+        i = -1
+        object.source.split(/\n/).map { object.line + (i += 1) }.join("\n")
+      end
+      
+      def format_code(object, show_lines = false)
+        i = -1
+        lines = object.source.split(/\n/)
+        longestline = (object.line + lines.size).to_s.length
+        lines.map do |line| 
+          lineno = object.line + (i += 1)
+          (" " * (longestline - lineno.to_s.length)) + lineno.to_s + "    " + line
+        end.join("\n")
+      end
     end
   end
-end
+end

data/lib/yard/generators/method_generator.rb

@@ -1,8 +1,11 @@
 module YARD
   module Generators
     class MethodGenerator < Base
+      include Helpers::MethodHelper
+
       before_generate :is_method?
       before_section :aliases, :has_aliases?
+      before_section :source, :isnt_overload?
       
       def sections_for(object) 
         [
@@ -16,16 +19,25 @@ module YARD
             G(DeprecatedGenerator), 
             G(DocstringGenerator), 
             G(TagsGenerator), 
-            G(SourceGenerator)
+            G(OverloadsGenerator),
+            :source
           ]
         ]
       end
       
       protected
-      
+
+      def source(object)
+        render_section(G(SourceGenerator), object)
+      end
+
       def has_aliases?(object)
         !object.aliases.empty?
       end
+
+      def isnt_overload?(object)
+        !object.is_a?(Tags::OverloadTag)
+      end
     end
   end
-end
+end