yard 0.2.1 → 0.2.2

data/lib/yard/generators/constructor_generator.rb

@@ -0,0 +1,25 @@
+module YARD
+  module Generators
+    class ConstructorGenerator < Base
+      before_generate :has_constructor?
+       
+      def sections_for(object) 
+        [:header, [G(MethodGenerator)]] 
+      end
+      
+      protected
+      
+      def has_constructor?
+        constructor_method ? true : false 
+      end
+      
+      def constructor_method
+        current_object.meths.find {|o| o.name == :initialize && o.scope == :instance }
+      end
+      
+      def constructor_method_inherited?
+        constructor_method.namespace != current_object
+      end
+    end
+  end
+end

data/lib/yard/generators/deprecated_generator.rb

@@ -0,0 +1,15 @@
+module YARD
+  module Generators
+    class DeprecatedGenerator < Base
+      before_generate :is_deprecated?
+      
+      def sections_for(object) [:main] end
+        
+      protected
+      
+      def is_deprecated?(object)
+        object.tag(:deprecated) ? true : false
+      end
+    end
+  end
+end

data/lib/yard/generators/docstring_generator.rb

@@ -0,0 +1,15 @@
+module YARD
+  module Generators
+    class DocstringGenerator < Base
+      before_section :main, :has_docstring?
+      
+      def sections_for(object) [:main] end
+      
+      protected
+      
+      def has_docstring?
+        !current_object.docstring.empty?
+      end
+    end
+  end
+end

data/lib/yard/generators/full_doc_generator.rb

@@ -0,0 +1,59 @@
+module YARD
+  module Generators
+    class FullDocGenerator < Base
+      before_generate :is_namespace?
+      before_list :generate_assets
+      before_list :generate_index
+      before_list :generate_readme
+      
+      def sections_for(object) 
+        case object
+        when CodeObjects::ClassObject
+          [:header, [G(ClassGenerator)]]
+        when CodeObjects::ModuleObject
+          [:header, [G(ModuleGenerator)]]
+        end
+      end
+      
+      protected
+    
+      def css_file;         'style.css'             end
+      def css_syntax_file;  'syntax_highlight.css'  end
+      def js_file;          'jquery.js'             end
+      def js_app_file;      'app.js'                end
+      
+      def readme_file
+        @readme_file ||= [options[:readme]].flatten.compact.find do |readme|
+          File.exists?(readme.to_s)
+        end.to_s
+      end
+      
+      def generate_assets
+        if format == :html && serializer
+          [css_file, css_syntax_file, js_file, js_app_file].each do |filename|
+            template_file = find_template template_path(filename)
+            serializer.serialize(filename, File.read(template_file))
+          end
+        end
+        true
+      end
+      
+      def generate_index
+        if format == :html && serializer
+          serializer.serialize 'index.html', render(:index)
+          serializer.serialize 'all-namespaces.html', render(:all_namespaces)
+          serializer.serialize 'all-methods.html', render(:all_methods)
+        end
+        true
+      end
+      
+      def generate_readme
+        if format == :html && serializer && readme_file
+          @contents = File.read(readme_file)
+          serializer.serialize 'readme.html', render(:readme)
+        end
+        true
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+module YARD::Generators::Helpers
+  module BaseHelper
+    # This is used a lot by the HtmlHelper and there should
+    # be some helper to "clean up" text for whatever, this is it.
+    def h(text)
+      text
+    end
+    
+    def linkify(*args) 
+      # The :// character sequence exists in no valid object path but just about every URL scheme.
+      if args.first.is_a?(String) && args.first.include?("://")
+        link_url(*args)
+      else
+        link_object(*args)
+      end
+    end
+
+    def link_object(object, title = nil)
+      return title if title
+      
+      case object
+      when YARD::CodeObjects::Base, YARD::CodeObjects::Proxy
+        object.path
+      when String, Symbol
+        P(object).path
+      else
+        object
+      end
+    end
+    
+    def link_url(url)
+      url
+    end
+    
+    def format_object_name_list(objects)
+      objects.sort_by {|o| o.name.to_s.downcase }.join(", ")
+    end
+    
+    def format_types(list, brackets = true)
+      list.empty? ? "" : (brackets ? "[#{list.join(", ")}]" : list.join(", "))
+    end
+
+    def format_object_type(object)
+      case object
+      when YARD::CodeObjects::ClassObject
+        object.is_exception? ? "Exception" : "Class"
+      else
+        object.type.to_s.capitalize
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+module YARD
+  module Generators::Helpers
+    module FilterHelper
+      def is_method?(object)
+        object.is_a?(CodeObjects::MethodObject)
+      end
+
+      def is_namespace?(object)
+        object.is_a?(CodeObjects::NamespaceObject)
+      end
+      
+      def is_class?(object)
+        object.is_a?(CodeObjects::ClassObject)
+      end
+      
+      def is_module?(object)
+        object.is_a?(CodeObjects::ModuleObject)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,137 @@
+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
+    
+      def h(text)
+        CGI.escapeHTML(text.to_s)
+      end
+    
+      def urlencode(text)
+        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>' }
+        html
+      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") + '...'
+          end
+          
+          " <tt>" + linkify(obj, title) + "</tt>" 
+        end
+      end
+
+      def format_object_name_list(objects)
+        objects.sort_by {|o| o.name.to_s.downcase }.map do |o| 
+          "<span class='name'>" + linkify(o, o.name) + "</span>" 
+        end.join(", ")
+      end
+      
+      # Formats a list of types from a tag.
+      # 
+      # @param [Array<String>, FalseClass] typelist
+      #   the list of types to be formatted. 
+      # 
+      # @param [Boolean] brackets omits the surrounding 
+      #   brackets if +brackets+ is set to +false+.
+      # 
+      # @return [String] the list of types formatted
+      #   as [Type1, Type2, ...] with the types linked
+      #   to their respective descriptions.
+      # 
+      def format_types(typelist, brackets = true)
+        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_object(object, otitle = nil, anchor = nil)
+        object = P(current_object, object) 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
+      end
+    
+      def anchor_for(object)
+        urlencode case object
+        when CodeObjects::MethodObject
+          "#{object.name}-#{object.scope}_#{object.type}"
+        when CodeObjects::Base
+          "#{object.name}-#{object.type}"
+        when CodeObjects::Proxy
+          object.path
+        else
+          object.to_s
+        end
+      end
+    
+      def url_for(object, anchor = nil, relative = true)
+        link = nil
+        return link unless serializer
+        
+        if object.is_a?(CodeObjects::Base) && !object.is_a?(CodeObjects::NamespaceObject)
+          # If the object is not a namespace object make it the anchor.
+          anchor, object = object, object.namespace
+        end
+        
+        objpath = serializer.serialized_path(object)
+        return link unless objpath
+      
+        if relative
+          fromobj = current_object
+          if current_object.is_a?(CodeObjects::Base) && 
+              !current_object.is_a?(CodeObjects::NamespaceObject)
+            fromobj = fromobj.namespace
+          end
+
+          from  = serializer.serialized_path(fromobj)
+          link  = File.relative_path(from, objpath)
+        else
+          link = objpath
+        end
+      
+        link + (anchor ? '#' + 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
+      end
+    end
+  end
+end
+    
+    

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

@@ -0,0 +1,27 @@
+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]
+        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
+      end
+      
+      def format_block(object)
+        if object.has_tag?(:yieldparam)
+          h "{|" + object.tags(:yieldparam).map {|t| t.name }.join(", ") + "| ... }"
+        else
+          ""
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+module YARD
+  module Generators::Helpers
+    module UMLHelper
+      def uml_visibility(object)
+        case object.visibility
+        when :public
+          '+'
+        when :protected
+          '#'
+        when :private
+          '-'
+        end
+      end
+    end
+  end
+end

data/lib/yard/generators/inheritance_generator.rb

@@ -0,0 +1,16 @@
+module YARD
+  module Generators
+    class InheritanceGenerator < Base
+      before_generate :has_inheritance_tree?
+      
+      def sections_for(object) [:header] end
+        
+      protected
+      
+      def has_inheritance_tree?(object)
+        return false unless object.is_a?(CodeObjects::ClassObject)
+        object.inheritance_tree.size > 1
+      end
+    end
+  end
+end

data/lib/yard/generators/method_details_generator.rb

@@ -0,0 +1,18 @@
+module YARD
+  module Generators
+    class MethodDetailsGenerator < MethodListingGenerator
+      before_generate :is_namespace?
+      before_generate :has_methods?
+
+      def sections_for(object)
+        [
+          :header, 
+          [ # with MethodObject
+            :method_header,
+            G(MethodGenerator),
+          ]
+        ]
+      end
+    end
+  end
+end

data/lib/yard/generators/method_generator.rb

@@ -0,0 +1,31 @@
+module YARD
+  module Generators
+    class MethodGenerator < Base
+      before_generate :is_method?
+      before_section :aliases, :has_aliases?
+      
+      def sections_for(object) 
+        [
+          :header,
+          [
+            :title,
+            [
+              G(MethodSignatureGenerator), 
+              :aliases
+            ], 
+            G(DeprecatedGenerator), 
+            G(DocstringGenerator), 
+            G(TagsGenerator), 
+            G(SourceGenerator)
+          ]
+        ]
+      end
+      
+      protected
+      
+      def has_aliases?(object)
+        !object.aliases.empty?
+      end
+    end
+  end
+end