yard 0.2.3.5 → 0.4.0

data/lib/yard/serializers/base.rb

@@ -1,15 +1,62 @@
 module YARD
   module Serializers
+    # The abstract base serializer. Serializers allow templates to be
+    # rendered to various endpoints. For instance, a {FileSystemSerializer}
+    # would allow template contents to be written to the filesystem
+    # 
+    # To implement a custom serializer, override the following methods:
+    # * {#serialize}
+    # * {#serialized_path}
+    # 
+    # Optionally, a serializer can implement before and after filters:
+    # * {#before_serialize}
+    # * {#after_serialize}
+    # 
+    # @abstract Override this class to implement a custom serializer.
     class Base
+      # All serializer options are saved so they can be passed to other serializers.
+      # 
+      # @return [SymbolHash] the serializer options
       attr_reader :options
       
+      # Creates a new serializer with options
+      # 
+      # @param [Hash] opts the options to assign to {#options}
       def initialize(opts = {})
         @options = SymbolHash.new(false).update(opts)
       end
       
+      # Called before serialization. 
+      # 
+      # @abstract Should run code before serialization. Should return false
+      #   if serialization should not occur.
+      # @return [Boolean] whether or not serialization should occur
       def before_serialize; end
-      def serialize(object, data) end
+      
+      # Called after serialization. 
+      # 
+      # @abstract Should run code after serialization.
+      # @param [String] data the data that was serialized.
+      # @return [nil]
       def after_serialize(data); end
+      
+      # Serializes an object.
+      # 
+      # @abstract This method should implement the logic that serializes 
+      #   +data+ to the respective endpoint. This method should also call
+      #   the before and after callbacks {#before_serialize} and {#after_serialize}
+      # @param [CodeObjects::Base, String] object the object to serialize the
+      #   data for. The object can also be a string (for non-object serialization)
+      # @param [String] data the contents that should be serialized
+      def serialize(object, data) end
+        
+      # The serialized path of an object
+      # 
+      # @abstract This method should return the path of the object on the
+      #   endpoint. For instance, for a file serializer, this should return
+      #   the filename that represents the object on disk.
+      # @param [CodeObjects::Base] object the object to return a path for
+      # @return [String] the serialized path of an object
       def serialized_path(object) end
     end
   end

data/lib/yard/serializers/file_system_serializer.rb

@@ -3,21 +3,42 @@ require 'fileutils'
 module YARD
   module Serializers
     class FileSystemSerializer < Base
-      attr_reader :basepath, :extension
+      # The base path to write data to.
+      # @return [String] a base path
+      attr_reader :basepath
       
+      # The extension of the filename (defaults to +html+)
+      # 
+      # @return [String] the extension of the file. Empty string for no extension.
+      attr_reader :extension
+      
+      # Creates a new FileSystemSerializer with options
+      # 
+      # @option opts [String] :basepath ('doc') the base path to write data to
+      # @option opts [String] :extension ('html') the extension of the serialized
+      #   path filename. If this is set to the empty string, no extension is used.
       def initialize(opts = {})
         super
         @basepath = (options[:basepath] || 'doc').to_s
         @extension = (options.has_key?(:extension) ? options[:extension] : 'html').to_s
       end
       
+      # Serializes object with data to its serialized path (prefixed by the {#basepath}).
+      # 
+      # @return [String] the written data (for chaining)
       def serialize(object, data)
         path = File.join(basepath, *serialized_path(object))
         FileUtils.mkdir_p File.dirname(path)
         log.debug "Serializing to #{path}"
-        File.open(path, "w") {|f| f.write data }
+        File.open(path, "wb") {|f| f.write data }
       end
       
+      # Implements the serialized path of a code object.
+      # 
+      # @param [CodeObjects::Base, String] object the object to get a path for.
+      #   The path of a string is the string itself.
+      # @return [String] if object is a String, returns
+      #   object, otherwise the path on disk (without the basepath).
       def serialized_path(object)
         return object if object.is_a?(String)
 

data/lib/yard/serializers/process_serializer.rb

@@ -1,10 +1,20 @@
 module YARD
   module Serializers
+    # Serializes an object to a process (like less)
+    # 
+    # @example Serializing to a pager (less)
+    #   serializer = ProcessSerializer.new('less')
+    #   serializer.serialize(object, "data!")
     class ProcessSerializer < Base
+      # Creates a new ProcessSerializer for the shell command +cmd+
+      # 
+      # @param [String] cmd the command that will accept data on stdin
       def initialize(cmd)
         @cmd = cmd
       end
       
+      # Overrides serialize behavour and writes data to standard input
+      # of the associated command
       def serialize(object, data)
         IO.popen(@cmd, 'w') {|io| io.write(data) }
       end

data/lib/yard/serializers/stdout_serializer.rb

@@ -1,16 +1,27 @@
 module YARD
   module Serializers
+    # A serializer that writes data to standard output.
     class StdoutSerializer < Base
+      # Creates a serializer to print text to stdout
+      # 
+      # @param [Fixnum, nil] wrap if wrap is a number, wraps text to +wrap+
+      #   columns, otherwise no wrapping is done.
       def initialize(wrap = nil)
         @wrap = wrap
       end
       
+      # Overrides serialize behaviour to write data to standard output
       def serialize(object, data)
         print(@wrap ? word_wrap(data, @wrap) : data)
       end
       
       private
       
+      # Wraps text to a specific column length
+      # 
+      # @param [String] text the text to wrap
+      # @param [Fixnum] length the column length to wrap to
+      # @return [String] the wrapped text
       def word_wrap(text, length = 80)
         # See ruby-talk/10655 / Ernest Ellingson
         text.gsub(/\t/,"     ").gsub(/.{1,50}(?:\s|\Z)/){($& + 

data/lib/yard/tags/library.rb

@@ -139,10 +139,13 @@ module YARD
       define_tag "Since",             :since
       define_tag "Version",           :version
       define_tag "API Visibility",    :api
-      define_tag "Todo Item",         :todo,        :with_raw_title_and_text
+      define_tag "Note",              :note
+      define_tag "Todo Item",         :todo
       define_tag "Example",           :example,     :with_raw_title_and_text
       define_tag "Options Hash",      :option,      :with_options
       define_tag "Overloads",         :overload,    OverloadTag
+      define_tag "Private",           :private
+      define_tag "Abstract",          :abstract
     end
   end
 end

data/lib/yard/tags/overload_tag.rb

@@ -2,7 +2,6 @@ module YARD
   module Tags
     class OverloadTag < Tag
       attr_reader :signature, :parameters, :docstring
-      undef_method :to_s, :inspect
       
       def initialize(tag_name, text, raw_text)
         super(tag_name, nil)
@@ -19,22 +18,14 @@ module YARD
         docstring.object = value
       end
 
-      def type
-        object.type
-      end
-
       def name(prefix = false)
         object.name(prefix)
       end
-
-      def inspect
-        "#<yardoc overload #{path}>"
-      end
       
-      def method_missing(sym, *args, &block)
-        object ? object.send(sym, *args, &block) : super
+      def method_missing(*args, &block)
+        object.send(*args, &block)
       end
-        
+
       private
       
       def parse_tag(raw_text)

data/lib/yard/templates/engine.rb

@@ -0,0 +1,162 @@
+module YARD
+  module Templates
+    module Engine
+      class << self
+        # @return [Array<String>] the list of registered template paths
+        attr_accessor :template_paths
+
+        # Registers a new template path in {template_paths}
+        # 
+        # @param [String] path a new template path
+        # @return [nil] 
+        def register_template_path(path)
+          template_paths.push path
+        end
+        
+        # Creates a template module representing the path. Searches on disk 
+        # for the first directory named +path+ (joined by '/') within the 
+        # template paths and builds a template module for. All other matching 
+        # directories in other template paths will be included in the 
+        # generated module as mixins (for overriding).
+        # 
+        # @param [Array<String, Symbol>] path a list of path components
+        # @return [Template] the module representing the template
+        def template(*path)
+          from_template = nil
+          from_template = path.shift if path.first.is_a?(Template)
+          path = path.join('/')
+          full_paths = find_template_paths(from_template, path)
+          
+          path = File.cleanpath(path).gsub('../', '')
+          raise ArgumentError, "No such template for #{path}" if full_paths.empty?
+          mod = template!(path, full_paths)
+
+          mod
+        end
+        
+        # Forces creation of a template at +path+ within a +full_path+.
+        # 
+        # @param [String] path the path name of the template
+        # @param [Array<String>] full_paths the full path on disk of the template
+        # @return [Template] the template module representing the +path+
+        def template!(path, full_paths = nil)
+          full_paths ||= [path]
+          full_paths = [full_paths] unless full_paths.is_a?(Array)
+          name = template_module_name(full_paths.first)
+          return const_get(name) rescue NameError 
+
+          mod = const_set(name, Module.new)
+          mod.send(:include, Template)
+          mod.send(:initialize, path, full_paths)
+          mod
+        end
+
+        # Renders a template on a {CodeObjects::Base code object} using
+        # a set of default (overridable) options. Either the +:object+
+        # or +:type+ keys must be provided. 
+        # 
+        # If a +:serializer+ key is provided and +:serialize+ is not set to
+        # false, the rendered contents will be serialized through the {Serializers::Base}
+        # object. See {with_serializer}.
+        # 
+        # @example Renders an object with html formatting
+        #   Engine.render(:format => :html, :object => obj)
+        # @example Renders without an object
+        #   Engine.render(:type => :fulldoc, :otheropts => somevalue)
+        # @param [Hash] options the options hash
+        # @option options [Symbol] :format (:text) the default format
+        # @option options [Symbol] :type (nil) the :object's type.
+        # @option options [Symbol] :template (:default) the default template
+        # @return [String] the rendered template
+        def render(options = {})
+          set_default_options(options)
+          mod = template(options[:template], options[:type], options[:format])
+          
+          if options[:serialize] != false
+            with_serializer(options[:object], options[:serializer]) { mod.run(options) }
+          else
+            mod.run(options)
+          end
+        end
+        
+        # Passes a set of objects to the +:fulldoc+ template for full documentation generation. 
+        # This is called by {CLI::Yardoc} to most commonly perform HTML 
+        # documentation generation.
+        # 
+        # @param [Array<CodeObjects::Base>] objects a list of {CodeObjects::Base}
+        #   objects to pass to the template
+        # @param [Hash] options (see {render})
+        # @return [nil]
+        def generate(objects, options = {})
+          set_default_options(options)
+          options[:objects] = objects
+          template(options[:template], :fulldoc, options[:format]).run(options)
+        end
+
+        # Serializes the results of a block with a +serializer+ object.
+        # 
+        # @param [CodeObjects::Base] object the code object to serialize
+        # @param [Serializers::Base] serializer the serializer object
+        # @yield a block whose result will be serialize
+        # @yieldreturn [String] the contents to serialize
+        # @see Serializers::Base
+        def with_serializer(object, serializer, &block)
+          serializer.before_serialize if serializer
+          output = yield
+          if serializer
+            serializer.serialize(object, output)
+            serializer.after_serialize(output)
+          end
+          output
+        end
+        
+        private
+        
+        # Sets default options on the options hash
+        # 
+        # @param [Hash] options the options hash
+        # @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]
+        def set_default_options(options = {})
+          options[:format] ||= :text
+          options[:type] ||= options[:object].type if options[:object]
+          options[:template] ||= :default
+        end
+
+        # Searches through the registered {template_paths} and returns
+        # all full directories that have the +path+ within them on disk.
+        # 
+        # @param [Template] from_template if provided, allows a relative
+        #   path to be specified from this template's full path.
+        # @param [String] path the path component to search for in the
+        #   {template_paths}
+        # @return [Array<String>] a list of full paths that are existing
+        #   candidates for a template module
+        def find_template_paths(from_template, path)
+          paths = template_paths.dup
+          paths = from_template.full_paths + paths if from_template
+          
+          paths.inject([]) do |acc, tp|
+            full_path = File.cleanpath(File.join(tp, path))
+            acc.unshift(full_path) if File.directory?(full_path)
+            acc
+          end.uniq
+        end
+
+        # The name of the module that represents a +path+
+        # 
+        # @param [String] the path toe generate a module name for
+        # @return [String] the module name
+        def template_module_name(path)
+          'Template_' + path.to_s.gsub(/[^a-z0-9]/i, '_')
+        end
+      end
+
+      self.template_paths = []
+    end
+    
+    Engine.register_template_path(File.join(YARD::ROOT, '..', 'templates'))
+  end
+end

data/lib/yard/{generators → templates}/helpers/base_helper.rb

@@ -1,5 +1,12 @@
-module YARD::Generators::Helpers
+module YARD::Templates::Helpers
   module BaseHelper
+    attr_accessor :object, :serializer
+    
+    def run_verifier(list)
+      return list unless options[:verifier]
+      list.reject {|item| options[:verifier].call(item).is_a?(FalseClass) }
+    end
+    
     # 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)
@@ -32,12 +39,8 @@ module YARD::Generators::Helpers
       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(", "))
+      list.nil? || list.empty? ? "" : (brackets ? "(#{list.join(", ")})" : list.join(", "))
     end
 
     def format_object_type(object)
@@ -57,13 +60,11 @@ module YARD::Generators::Helpers
         format_object_type(object) + ": " + object.path
       end
     end
-
-    def overloads(method)
-      if method.has_tag?(:overload)
-        method.tags(:overload)
-      else
-        [method]
-      end
+    
+    def format_source(value)
+      sp = value.split("\n").last[/^(\s+)/, 1]
+      num = sp ? sp.size : 0
+      value.gsub(/^\s{#{num}}/, '')
     end
   end
 end

data/lib/yard/{generators → templates}/helpers/filter_helper.rb

@@ -1,5 +1,5 @@
 module YARD
-  module Generators::Helpers
+  module Templates::Helpers
     module FilterHelper
       def is_method?(object)
         object.type == :method

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

@@ -0,0 +1,287 @@
+require 'cgi'
+
+module YARD
+  module Templates::Helpers
+    module HtmlHelper
+      include MarkupHelper
+      include HtmlSyntaxHighlightHelper
+      
+      SimpleMarkupHtml = RDoc::Markup::ToHtml.new rescue SM::ToHtml.new
+    
+      # Escapes HTML entities
+      # 
+      # @param [String] text the text to escape
+      # @return [String] the HTML with escaped entities
+      def h(text)
+        CGI.escapeHTML(text.to_s)
+      end
+    
+      # Escapes a URL
+      # 
+      # @param [String] text the URL
+      # @return [String] the escaped URL
+      def urlencode(text)
+        CGI.escape(text.to_s)
+      end
+
+      # Turns text into HTML using +markup+ style formatting.
+      # 
+      # @param [String] text the text to format
+      # @param [Symbol] markup examples are +:markdown+, +:textile+, +:rdoc+.
+      #   To add a custom markup type, see {MarkupHelper}
+      # @return [String] the HTML
+      def htmlify(text, markup = options[:markup])
+        return "" unless text
+        return text unless markup
+        load_markup_provider(markup)
+
+        # TODO: other libraries might be more complex
+        case markup
+        when :markdown
+          html = markup_class(markup).new(text).to_html
+        when :textile
+          doc = markup_class(markup).new(text)
+          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)
+          end
+
+          html = fix_dash_dash(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
+      
+      # @return [String] HTMLified text as a single line (paragraphs removed)
+      def htmlify_line(*args)
+        htmlify(*args).gsub(/<\/?p>/, '')
+      end
+      
+      # Fixes RDoc behaviour with ++ only supporting alphanumeric text.
+      # 
+      # @todo Refactor into own SimpleMarkup subclass
+      def fix_typewriter(text)
+        text.gsub(/\+(?! )([^\+]{1,900})(?! )\+/) do
+          '<tt>' + $1.gsub(/(.)/, "\\1\004") + '</tt>'
+        end
+      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
+
+      # Resolves any text in the form of +{Name}+ to the object specified by
+      # Name. Also supports link titles in the form +{Name title}+.
+      # 
+      # @example Linking to an instance method
+      #   resolve_links("{MyClass#method}") # => "<a href='...'>MyClass#method</a>"
+      # @example Linking to a class with a title
+      #   resolve_links("{A::B::C the C class}") # => "<a href='...'>the c class</a>"
+      # @param [String] text the text to resolve links in
+      # @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|
+          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
+
+          case name
+          when %r{://}, /^mailto:/
+            sp + link_url(name, title, :target => '_parent')
+          when /^file:(\S+?)(?:#(\S+))?$/
+            sp + link_file($1, title == name ? $1 : title, $2)
+          else
+            if object.is_a?(String)
+              obj = name
+            else
+              obj = Registry.resolve(object, name, true, true)
+              if obj.is_a?(CodeObjects::Proxy)
+                match = text[/(.{0,20}\{.*?#{Regexp.quote name}.*?\}.{0,20})/, 1]
+                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>" 
+            end
+          end
+        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)
+        return unless typelist.is_a?(Array)
+        list = typelist.map do |type| 
+          type = type.gsub(/([<>])/) { h($1) }
+          type = type.gsub(/([\w:]+)/) { $1 == "lt" || $1 == "gt" ? $1 : linkify($1, $1) }
+          "<tt>" + type + "</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(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 == Registry.root
+        return title unless serializer
+
+        return title if obj.is_a?(CodeObjects::Proxy)
+      
+        link = url_for(obj, 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)
+        case object
+        when CodeObjects::MethodObject
+          "#{object.name}-#{object.scope}_#{object.type}"
+        when CodeObjects::ClassVariableObject
+          "#{object.name.to_s.gsub('@@', '')}-#{object.type}"
+        when CodeObjects::Base
+          "#{object.name}-#{object.type}"
+        when CodeObjects::Proxy
+          object.path
+        else
+          object.to_s
+        end
+      end
+    
+      def url_for(obj, anchor = nil, relative = true)
+        link = nil
+        return link unless serializer
+        
+        if obj.is_a?(CodeObjects::Base) && !obj.is_a?(CodeObjects::NamespaceObject)
+          # If the obj is not a namespace obj make it the anchor.
+          anchor, obj = obj, obj.namespace
+        end
+        
+        objpath = serializer.serialized_path(obj)
+        return link unless objpath
+      
+        if relative
+          fromobj = object
+          if object.is_a?(CodeObjects::Base) && 
+              !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 ? '#' + urlencode(anchor_for(anchor)) : '')
+      end
+      
+      def url_for_file(filename, anchor = nil)
+        fromobj = object
+        if CodeObjects::Base === fromobj && !fromobj.is_a?(CodeObjects::NamespaceObject)
+          fromobj = fromobj.namespace
+        end
+        from = serializer.serialized_path(fromobj)
+        if filename == options[:readme]
+          filename = 'index'
+        else
+          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)
+        end
+        
+        scope = meth.scope == :class ? "+" : "-"
+        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]
+            attname = [rw[:read] ? 'read' : nil, rw[:write] ? 'write' : nil].compact
+            attname = attname.size == 1 ? attname.join('') + 'only' : nil
+            extras << attname if attname
+          end
+          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]
+        if link
+          if meth.is_a?(YARD::CodeObjects::MethodObject)
+            link_title = "#{meth.name(true)} (#{meth.scope} #{meth.type})"
+          else
+            link_title = "#{name} (#{meth.type})"
+          end
+          link_url(url_for(meth), title, :title => link_title) + extras_text
+        else
+          title + extras_text
+        end
+      end
+    end
+  end
+end
+