yard 0.5.3 → 0.5.4

data/docs/WhatsNew.md

@@ -12,6 +12,7 @@ What's New in 0.5.x?
 8. **Generating HTML docs now adds frames view** (0.5.3)
 9. **Tree view for class list** (0.5.3)
 10. **Ability to specify markup format of extra files** (0.5.3)
+11. **Keyboard shortcuts for default HTML template** (0.5.4)
 
 Support for documenting native Ruby C code (0.5.0)
 --------------------------------------------------
@@ -162,6 +163,13 @@ top of the file with a shebang-like line:
 The above file contents will be rendered with a textile markup engine 
 (eg. RedCloth).
 
+Keyboard shortcuts for default HTML template (0.5.4)
+----------------------------------------------------
+
+You can now access the "Class List", "Method List" and "File List" with the
+'c', 'm' and 'f' keyboard shortcuts in the default HTML template, allowing
+for keyboard-only navigation around YARD documentation.
+
 
 What's New in 0.4.x?
 ====================

data/lib/yard.rb

@@ -1,7 +1,7 @@
 module YARD
-  VERSION = "0.5.3"
-  ROOT = File.dirname(__FILE__)
-  TEMPLATE_ROOT = File.join(File.dirname(__FILE__), '..', 'templates')
+  VERSION = "0.5.4"
+  ROOT = File.expand_path(File.dirname(__FILE__))
+  TEMPLATE_ROOT = File.join(ROOT, '..', 'templates')
   CONFIG_DIR = File.expand_path('~/.yard')
   
   # An alias to {Parser::SourceParser}'s parsing method
@@ -49,7 +49,7 @@ end
 $LOAD_PATH.push('.') if RUBY_VERSION >= '1.9.2'
 
 # Keep track of Ruby version for compatibility code
-RUBY19, RUBY18 = *(RUBY_VERSION >= "1.9" ? [true, false] : [false, true])
+RUBY19, RUBY18 = *(RUBY_VERSION >= "1.9.1" ? [true, false] : [false, true])
 
 # Load Ruby core extension classes
 Dir.glob(File.join(YARD::ROOT, 'yard', 'core_ext', '*')).each do |file|

data/lib/yard/autoload.rb

@@ -49,42 +49,45 @@ module YARD
   module Handlers
     module Ruby # All Ruby handlers
       module Legacy # Handlers for old Ruby 1.8 parser
-        autoload :Base,                 __p('handlers/ruby/legacy/base')
+        autoload :Base,                  __p('handlers/ruby/legacy/base')
 
-        autoload :AliasHandler,         __p('handlers/ruby/legacy/alias_handler')
-        autoload :AttributeHandler,     __p('handlers/ruby/legacy/attribute_handler')
-        autoload :ClassHandler,         __p('handlers/ruby/legacy/class_handler')
-        autoload :ClassVariableHandler, __p('handlers/ruby/legacy/class_variable_handler')
-        autoload :ConstantHandler,      __p('handlers/ruby/legacy/constant_handler')
-        autoload :ExceptionHandler,     __p('handlers/ruby/legacy/exception_handler')
-        autoload :ExtendHandler,        __p('handlers/ruby/legacy/extend_handler')
-        autoload :MethodHandler,        __p('handlers/ruby/legacy/method_handler')
-        autoload :MixinHandler,         __p('handlers/ruby/legacy/mixin_handler')
-        autoload :ModuleHandler,        __p('handlers/ruby/legacy/module_handler')
-        autoload :VisibilityHandler,    __p('handlers/ruby/legacy/visibility_handler')
-        autoload :YieldHandler,         __p('handlers/ruby/legacy/yield_handler')
+        autoload :AliasHandler,          __p('handlers/ruby/legacy/alias_handler')
+        autoload :AttributeHandler,      __p('handlers/ruby/legacy/attribute_handler')
+        autoload :ClassHandler,          __p('handlers/ruby/legacy/class_handler')
+        autoload :ClassConditionHandler, __p('handlers/ruby/legacy/class_condition_handler')
+        autoload :ClassVariableHandler,  __p('handlers/ruby/legacy/class_variable_handler')
+        autoload :ConstantHandler,       __p('handlers/ruby/legacy/constant_handler')
+        autoload :ExceptionHandler,      __p('handlers/ruby/legacy/exception_handler')
+        autoload :ExtendHandler,         __p('handlers/ruby/legacy/extend_handler')
+        autoload :MethodHandler,         __p('handlers/ruby/legacy/method_handler')
+        autoload :MixinHandler,          __p('handlers/ruby/legacy/mixin_handler')
+        autoload :ModuleHandler,         __p('handlers/ruby/legacy/module_handler')
+        autoload :ProcessHandler,        __p('handlers/ruby/legacy/process_handler')
+        autoload :VisibilityHandler,     __p('handlers/ruby/legacy/visibility_handler')
+        autoload :YieldHandler,          __p('handlers/ruby/legacy/yield_handler')
       end
 
-      autoload :Base,                   __p('handlers/ruby/base')
+      autoload :Base,                    __p('handlers/ruby/base')
 
-      autoload :AliasHandler,           __p('handlers/ruby/alias_handler')
-      autoload :AttributeHandler,       __p('handlers/ruby/attribute_handler')
-      autoload :ClassHandler,           __p('handlers/ruby/class_handler')
-      autoload :ClassConditionHandler,  __p('handlers/ruby/class_condition_handler')
-      autoload :ClassVariableHandler,   __p('handlers/ruby/class_variable_handler')
-      autoload :ConstantHandler,        __p('handlers/ruby/constant_handler')
-      autoload :ExceptionHandler,       __p('handlers/ruby/exception_handler')
-      autoload :ExtendHandler,          __p('handlers/ruby/extend_handler')
-      autoload :MethodHandler,          __p('handlers/ruby/method_handler')
-      autoload :MethodConditionHandler, __p('handlers/ruby/method_condition_handler')
-      autoload :MixinHandler,           __p('handlers/ruby/mixin_handler')
-      autoload :ModuleHandler,          __p('handlers/ruby/module_handler')
-      autoload :VisibilityHandler,      __p('handlers/ruby/visibility_handler')
-      autoload :YieldHandler,           __p('handlers/ruby/yield_handler')
+      autoload :AliasHandler,            __p('handlers/ruby/alias_handler')
+      autoload :AttributeHandler,        __p('handlers/ruby/attribute_handler')
+      autoload :ClassHandler,            __p('handlers/ruby/class_handler')
+      autoload :ClassConditionHandler,   __p('handlers/ruby/class_condition_handler')
+      autoload :ClassVariableHandler,    __p('handlers/ruby/class_variable_handler')
+      autoload :ConstantHandler,         __p('handlers/ruby/constant_handler')
+      autoload :ExceptionHandler,        __p('handlers/ruby/exception_handler')
+      autoload :ExtendHandler,           __p('handlers/ruby/extend_handler')
+      autoload :MethodHandler,           __p('handlers/ruby/method_handler')
+      autoload :MethodConditionHandler,  __p('handlers/ruby/method_condition_handler')
+      autoload :MixinHandler,            __p('handlers/ruby/mixin_handler')
+      autoload :ModuleHandler,           __p('handlers/ruby/module_handler')
+      autoload :ProcessHandler,          __p('handlers/ruby/process_handler')
+      autoload :VisibilityHandler,       __p('handlers/ruby/visibility_handler')
+      autoload :YieldHandler,            __p('handlers/ruby/yield_handler')
     end
 
-    autoload :Base,                     __p('handlers/base')
-    autoload :Processor,                __p('handlers/processor')
+    autoload :Base,                      __p('handlers/base')
+    autoload :Processor,                 __p('handlers/processor')
   end
 
   # The parser namespace holds all parsing engines used by YARD. 
@@ -147,6 +150,7 @@ module YARD
 
     autoload :Engine,   __p('templates/engine')
     autoload :Template, __p('templates/template')
+    autoload :ErbCache, __p('templates/erb_cache')
   end
 
   autoload :Docstring,      __p('docstring')

data/lib/yard/cli/base.rb

@@ -11,6 +11,8 @@ module YARD
         log.show_backtraces = false
       end
       
+      protected
+
       # Adds a set of common options to the tail of the OptionParser
       # 
       # @param [OptionParser] opts the option parser object
@@ -25,6 +27,18 @@ module YARD
         opts.on_tail('-v', '--version', 'Show version.') { puts "yard #{YARD::VERSION}"; exit }
         opts.on_tail('-h', '--help', 'Show this help.')  { puts opts; exit }
       end
+      
+      # Parses the option and gracefully handles invalid switches
+      # 
+      # @param [OptionParser] opts the option parser object
+      # @param [Array<String>] args the arguments passed from input. This
+      #   array will be modified.
+      # @return [void]
+      def parse_options(opts, args)
+        opts.parse!(args)
+      rescue OptionParser::InvalidOption => e
+        log.warn "Unrecognized/#{e.message}"
+      end
     end
   end
 end

data/lib/yard/cli/yard_graph.rb

@@ -90,18 +90,12 @@ module YARD
         end
         
         common_options(opts)
+        parse_options(opts, args)
 
-        begin
-          opts.parse!(args)
-          if args.first
-            @objects = args.map {|o| Registry.at(o) }.compact
-          else
-            @objects = [Registry.root]
-          end
-        rescue => e
-          STDERR.puts e.message
-          STDERR << "\n" << opts
-          exit
+        if args.first
+          @objects = args.map {|o| Registry.at(o) }.compact
+        else
+          @objects = [Registry.root]
         end
       end
     end

data/lib/yard/cli/yardoc.rb

@@ -323,6 +323,14 @@ module YARD
           options[:serializer] = nil
           serialopts[:basepath] = dir
         end
+        
+        opts.on('--charset ENC', 'Character set to use for HTML output (default is utf-8)') do |encoding|
+          begin
+            Encoding.default_external = encoding
+          rescue ArgumentError => e
+            raise OptionParser::InvalidOption, e
+          end
+        end
 
         opts.on('-t', '--template TEMPLATE', 
                 'The template to use. (defaults to "default")') do |template|
@@ -340,14 +348,7 @@ module YARD
         end
 
         common_options(opts)
-        
-        begin
-          opts.parse!(args)
-        rescue OptionParser::InvalidOption => e
-          STDERR.puts e.message
-          STDERR << "\n" << opts
-          exit
-        end
+        parse_options(opts, args)
         
         # Last minute modifications
         build_gems(do_rebuild_gems) if do_build_gems

data/lib/yard/cli/yri.rb

@@ -129,15 +129,8 @@ module YARD
         end
         
         common_options(opts)
-
-        begin
-          opts.parse!(args)
-          @name = args.first
-        rescue => e
-          STDERR.puts e.message
-          STDERR << "\n" << opts
-          exit
-        end
+        parse_options(opts, args)
+        @name = args.first
       end
     end
   end

data/lib/yard/code_objects/base.rb

@@ -280,12 +280,15 @@ module YARD
         end
       end
       
-      # Checks if the method matches the name of an existing custom
-      # attribute.
-      # 
-      # @param [Symbol] meth the name of the method/attribute
-      # @raise [NoMethodError] if no method or custom attribute exists by
-      #   the name +meth+
+      # @overload dynamic_attr_name
+      #   @return the value of attribute named by the method attribute name
+      #   @raise [NoMethodError] if no method or custom attribute exists by
+      #     the attribute name
+      #   @see #[]
+      # @overload dynamic_attr_name=(value)
+      #   @param value a value to set
+      #   @return +value+
+      #   @see #[]=
       def method_missing(meth, *args, &block)
         if meth.to_s =~ /=$/
           self[meth.to_s[0..-2]] = args.first

data/lib/yard/code_objects/class_object.rb

@@ -11,15 +11,15 @@ module YARD::CodeObjects
       super
 
       if is_exception?
-        self.superclass ||= :Exception unless P(namespace, name) == P(:Exception)
+        self.superclass ||= "::Exception" unless P(namespace, name) == P(:Exception)
       else
         case P(namespace, name).path
         when "BasicObject"
           nil
         when "Object"
-          self.superclass ||= :BasicObject
+          self.superclass ||= "::BasicObject"
         else
-          self.superclass ||= :Object
+          self.superclass ||= "::Object"
         end
       end
     end
@@ -38,7 +38,7 @@ module YARD::CodeObjects
     # @return [Array<NamespaceObject>] the list of code objects that make up
     #   the inheritance tree.
     def inheritance_tree(include_mods = false)
-      list = (include_mods ? mixins(:instance) : [])
+      list = (include_mods ? mixins(:instance, :class) : [])
       if superclass.is_a?(Proxy) || superclass.respond_to?(:inheritance_tree)
         list += [superclass] unless superclass == P(:Object) || superclass == P(:BasicObject)
       end
@@ -126,7 +126,7 @@ module YARD::CodeObjects
       
       if @superclass == self
         msg = "superclass #{@superclass.inspect} cannot be the same as the declared class #{self.inspect}"
-        @superclass = P(:Object)
+        @superclass = P("::Object")
         raise ArgumentError, msg
       end
     end

data/lib/yard/code_objects/module_object.rb

@@ -8,10 +8,11 @@ module YARD::CodeObjects
     # @return [Array<NamespaceObject>] a list of namespace objects
     def inheritance_tree(include_mods = false)
       return [self] unless include_mods
-      [self] + mixins(:instance).map do |m|
+      [self] + mixins(:instance, :class).map do |m|
+        next if m == self
         next m unless m.respond_to?(:inheritance_tree)
         m.inheritance_tree(true)
-      end.flatten
+      end.compact.flatten
     end
   end
 end

data/lib/yard/core_ext/file.rb

@@ -34,7 +34,7 @@ class File
     path = path.split(SEPARATOR)
     path = path.inject([]) do |acc, comp|
       next acc if comp == RELATIVE_SAMEDIR
-      if comp == RELATIVE_PARENTDIR && acc.size > 0
+      if comp == RELATIVE_PARENTDIR && acc.size > 0 && acc.last != RELATIVE_PARENTDIR
         acc.pop
         next acc
       end

data/lib/yard/docstring.rb

@@ -157,9 +157,8 @@ module YARD
     # 
     # @param [String] tag_name the tag name
     # @param [String] tag_buf the text attached to the tag with newlines removed.
-    # @param [String] raw_buf the raw buffer of text without removed newlines.
     # @return [Tags::Tag, Tags::RefTag] a tag
-    def create_tag(tag_name, tag_buf, raw_buf)
+    def create_tag(tag_name, tag_buf)
       if tag_buf =~ /\A\s*(?:(\S+)\s+)?\(\s*see\s+(\S+)\s*\)\s*\Z/
         return create_ref_tag(tag_name, $1, $2)
       end
@@ -167,11 +166,7 @@ module YARD
       tag_factory = Tags::Library.instance
       tag_method = "#{tag_name}_tag"
       if tag_name && tag_factory.respond_to?(tag_method)
-        if tag_factory.method(tag_method).arity == 2
-          add_tag *tag_factory.send(tag_method, tag_buf, raw_buf.join("\n"))
-        else
-          add_tag *tag_factory.send(tag_method, tag_buf) 
-        end
+        add_tag *tag_factory.send(tag_method, tag_buf)
       else
         log.warn "Unknown tag @#{tag_name}" + (object ? " in file `#{object.file}` near line #{object.line}" : "")
       end
@@ -195,7 +190,7 @@ module YARD
       indent, last_indent = comments.first[/^\s*/].length, 0
       orig_indent = 0
       last_line = ""
-      tag_name, tag_klass, tag_buf, raw_buf = nil, nil, "", []
+      tag_name, tag_klass, tag_buf = nil, nil, []
 
       (comments+['']).each_with_index do |line, index|
         indent = line[/^\s*/].length 
@@ -204,27 +199,21 @@ module YARD
 
         if tag_name && (((indent < orig_indent && !empty) || done) || 
             (indent <= last_indent && line =~ META_MATCH))
-          create_tag(tag_name, tag_buf, raw_buf)
-          tag_name, tag_buf, raw_buf = nil, '', []
+          create_tag(tag_name, tag_buf.join("\n"))
+          tag_name, tag_buf, = nil, []
           orig_indent = 0
         end
 
         # Found a meta tag
         if line =~ META_MATCH
-          orig_indent = indent
-          tag_name, tag_buf = $1, ($2 || '')
-          raw_buf = [tag_buf.dup]
+          tag_name, tag_buf = $1, [($2 || '')]
         elsif tag_name && indent >= orig_indent && !empty
+          orig_indent = indent if orig_indent == 0
           # Extra data added to the tag on the next line
           last_empty = last_line =~ /^[ \t]*$/ ? true : false
           
-          if last_empty
-            tag_buf << "\n\n" 
-            raw_buf << ''
-          end
-          
-          tag_buf << line.gsub(/^[ \t]{#{indent}}/, last_empty ? '' : ' ')
-          raw_buf << line.gsub(/^[ \t]{#{orig_indent}}/, '')
+          tag_buf << '' if last_empty
+          tag_buf << line.gsub(/^[ \t]{#{orig_indent}}/, '')
         elsif !tag_name
           # Regular docstring text
           docstring << line << "\n" 

data/lib/yard/handlers/base.rb

@@ -203,6 +203,19 @@ module YARD
         def namespace_only?
           @namespace_only ? true : false
         end
+        
+        # Generates a +process+ method, equivalent to +def process; ... end+.
+        # Blocks defined with this syntax will be wrapped inside an anonymous
+        # module so that the handler class can be extended with mixins that
+        # override the +process+ method without alias chaining.
+        # 
+        # @see #process
+        # @return [void]
+        def process(&block)
+          mod = Module.new
+          mod.send(:define_method, :process, &block)
+          include mod
+        end
       end
 
       def initialize(source_parser, stmt)

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

@@ -1,7 +1,7 @@
 class YARD::Handlers::Ruby::AliasHandler < YARD::Handlers::Ruby::Base
   handles :alias, method_call(:alias_method)
   
-  def process
+  process do
     names = []
     if statement.type == :alias
       names = statement.map {|o| o.jump(:ident, :op, :kw, :const).first }

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

@@ -4,7 +4,7 @@ class YARD::Handlers::Ruby::AttributeHandler < YARD::Handlers::Ruby::Base
   handles method_call(:attr_writer)
   handles method_call(:attr_accessor)
   
-  def process
+  process do
     return if statement.type == :var_ref
     read, write = true, false
     params = statement.parameters(false).dup

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

@@ -2,7 +2,7 @@ class YARD::Handlers::Ruby::ClassConditionHandler < YARD::Handlers::Ruby::Base
   namespace_only
   handles meta_type(:condition)
   
-  def process
+  process do
     condition = parse_condition
     if condition == nil
       # Parse both blocks if we're unsure of the condition

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

@@ -2,7 +2,7 @@ class YARD::Handlers::Ruby::ClassHandler < YARD::Handlers::Ruby::Base
   namespace_only
   handles :class, :sclass
   
-  def process
+  process do
     if statement.type == :class
       classname = statement[0].source
       superclass = parse_superclass(statement[1])

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

@@ -2,7 +2,7 @@ class YARD::Handlers::Ruby::ClassVariableHandler < YARD::Handlers::Ruby::Base
   namespace_only
   handles :assign
   
-  def process
+  process do
     if statement[0].type == :var_field && statement[0][0].type == :cvar
       name = statement[0][0][0]
       value = statement[1].source