yard 0.5.2 → 0.5.3

data/README.md

@@ -1,5 +1,5 @@
-YARD Release 0.5.1 "The Longest" (Dec 15th 2009)
-===================================================
+YARD Release 0.5.3 "The Longest" (Jan 11th 2010)
+================================================
 
 **Homepage**:  [http://yardoc.org](http://yardoc.org)   
 **IRC**:       **Join us on IRC in #yard on irc.freenode.net!**   
@@ -222,6 +222,18 @@ More options can be seen by typing `yard-graph --help`, but here is an example:
 CHANGELOG
 ---------
 
+- **January.11.10**: 0.5.3 release
+    - See {file:docs/WhatsNew.md what's new document} for changes
+
+- **December.16.09**: 0.5.2 release
+    - See {file:docs/WhatsNew.md what's new document} for changes
+
+- **December.15.09**: 0.5.1 release
+    - See {file:docs/WhatsNew.md what's new document} for changes
+
+- **December.13.09**: 0.5.0 release
+    - See {file:docs/WhatsNew.md what's new document} for changes
+
 - **November.15.09**: 0.4.0 release
     - Added new templating engine based on [tadpole](http://github.com/lsegal/tadpole)
     - Added YARD queries (`--query` CLI argument to yardoc)

data/Rakefile

@@ -1,23 +1,18 @@
 require File.dirname(__FILE__) + '/lib/yard'
-require 'rubygems'
-require 'rake/gempackagetask'
 
 WINDOWS = (RUBY_PLATFORM =~ /win32|cygwin/ ? true : false) rescue false
 SUDO = WINDOWS ? '' : 'sudo'
 
 task :default => :specs
 
-load 'yard.gemspec'
-Rake::GemPackageTask.new(SPEC) do |pkg|
-  pkg.gem_spec = SPEC
-  pkg.need_zip = true
-  pkg.need_tar = true
+desc "Builds the gem"
+task :gem do
+  sh "gem build yard.gemspec"
 end
 
-desc "Install the gem locally"
+desc "Installs the gem"
 task :install => :gem do 
-  sh "#{SUDO} gem install pkg/#{SPEC.name}-#{SPEC.version}.gem --local --no-rdoc --no-ri"
-  sh "rm -rf pkg/yard-#{SPEC.version}" unless ENV['KEEP_FILES']
+  sh "#{SUDO} gem install yard-#{YARD::VERSION}.gem --no-rdoc --no-ri"
 end
 
 begin

data/benchmarks/parsing.rb

@@ -14,8 +14,8 @@ PATH_ORDER = [
 ]
 
 Benchmark.bmbm do |x|
-  x.report("parse in order") { YARD::Registry.clear; YARD.parse PATH_ORDER, Logger::ERROR } 
-  x.report("parse") { YARD::Registry.clear; YARD.parse 'lib/**/*.rb', Logger::ERROR } 
+  x.report("parse in order") { YARD::Registry.clear; YARD.parse PATH_ORDER, [], Logger::ERROR } 
+  x.report("parse") { YARD::Registry.clear; YARD.parse 'lib/**/*.rb', [], Logger::ERROR } 
 end
 
 =begin

data/docs/WhatsNew.md

@@ -2,13 +2,16 @@ What's New in 0.5.x?
 ====================
 
 1. **Support for documenting native Ruby C code** (0.5.0)
-2. **Incremental parsing and output generation with `yardoc -c`** (0.5.0)
+2. **Incremental parsing and output generation with `yardoc -c`** (0.5.0, 0.5.3)
 2. **Improved `yri` support to perform lookups on installed Gems** (0.5.0)
 3. **Added `yardoc --default-return` and `yardoc --hide-void-return`** (0.5.0)
 4. **Multiple syntax highlighting language support** (0.5.0)
 5. **New .yardoc format** (0.5.0)
 6. **Support for yard-doc-* gem packages as hosted .yardoc dbs** (0.5.1)
 7. **Support for extra search paths in `yri`** (0.5.1)
+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)
 
 Support for documenting native Ruby C code (0.5.0)
 --------------------------------------------------
@@ -19,18 +22,26 @@ Ruby's core and stdlibs which will be hosted on http://yardoc.org/docs. In
 addition, the .yardoc dump for the Ruby-core classes will become available
 as an installable gem for yri support (see #3).
 
-Incremental parsing and output generation with `yardoc -c` (0.5.0)
-------------------------------------------------------------------
+Incremental parsing and output generation with `yardoc -c` (0.5.0, 0.5.3)
+-------------------------------------------------------------------------
 
-YARD now compares file checksums before parsing when using `yardoc -c` 
+<p class="note">Note: in 0.5.3 and above you must use <tt>--incremental</tt> 
+  to incrementally generate HTML, otherwise only parsing will be done 
+  incrementally but HTML will be generated with all objects. <tt>--incremental</tt>
+  implies <tt>-c</tt>, so no need to specify them both.</p>
+
+YARD now compares file checksums before parsing when using `yardoc -c`
 (aka `yardoc --use-cache`) to do incremental parsing of only the files that
 have changed. HTML (or other output format) generation will also only be
-done on the objects that were parsed from changed files. This makes doing
+done on the objects that were parsed from changed files (*). This makes doing
 a documentation development cycle much faster for quick HTML previews. Just
 remember that when using incremental output generation, the index will not
 be rebuilt and inter-file links might not hook up right, so it is best to
 perform a full rebuild at the end of such previews.
 
+(*) Only for versions prior to 0.5.3. For 0.5.3+, use `--incremental` for
+incremental HTML output.
+
 Improved `yri` support to perform lookups on installed Gems (0.5.0)
 -------------------------------------------------------------------
 
@@ -124,6 +135,33 @@ Support for extra search paths in `yri` (0.5.1)
 You can now add custom paths to non-gem .yardoc files 
 by adding them as newline separated paths in `~/.yard/yri_search_paths`.
 
+Generating HTML docs now adds frames view (0.5.3)
+-------------------------------------------------
+
+`yardoc` will now create a `frames.html` file when generating HTML documents
+which allows the user to view documentation inside frames, for those users who
+still find frames beneficial.
+
+Tree view for class list (0.5.3)
+--------------------------------
+
+The class list now displays as an expandable tree view to better organized an 
+otherwise cluttered namespace. If you properly namespace your less important
+classes (like Rails timezone classes), they will not take up space in the
+class list unless the user looks for them.
+
+Ability to specify markup format of extra files (0.5.3)
+-------------------------------------------------------
+
+You can now specify the markup format of an extra file (like README) at the
+top of the file with a shebang-like line:
+
+    #!textile
+    contents here
+    
+The above file contents will be rendered with a textile markup engine 
+(eg. RedCloth).
+
 
 What's New in 0.4.x?
 ====================

data/lib/rubygems_plugin.rb

@@ -6,7 +6,7 @@ class Gem::Specification
   overwrite_accessor(:has_rdoc) { @has_rdoc }
   overwrite_accessor(:has_rdoc=) {|v| @has_rdoc = v }
   
-  def self.has_yardoc=(value)
+  def has_yardoc=(value)
     @has_rdoc = 'yard'
   end
   
@@ -22,61 +22,65 @@ class Gem::Specification
   alias has_yardoc? has_yardoc
 end
 
-class Gem::DocManager
-  def self.load_yardoc
-    require File.dirname(__FILE__) + '/yard'
-  end
-  
-  def run_yardoc(*args)
-    args << @spec.rdoc_options
-    args << '--quiet'
-    if @spec.extra_rdoc_files.size > 0
-      args << '--files'
-      args << @spec.extra_rdoc_files.join(",")
+unless defined? Gem::DocManager.load_yardoc
+  class Gem::DocManager
+    def self.load_yardoc
+      require File.dirname(__FILE__) + '/yard'
     end
-    args << @spec.require_paths.map {|p| p + "/**/*.rb" }
-    args = args.flatten.map do |arg| arg.to_s end
-
-    old_pwd = Dir.pwd
-    Dir.chdir(@spec.full_gem_path)
-    YARD::CLI::Yardoc.run(*args)
-  rescue Errno::EACCES => e
-    dirname = File.dirname e.message.split("-")[1].strip
-    raise Gem::FilePermissionError.new(dirname)
-  rescue => ex
-    alert_error "While generating documentation for #{@spec.full_name}"
-    ui.errs.puts "... MESSAGE:   #{ex}"
-    ui.errs.puts "... YARDDOC args: #{args.join(' ')}"
-    ui.errs.puts "\t#{ex.backtrace.join("\n\t")}" if Gem.configuration.backtrace
-    ui.errs.puts "(continuing with the rest of the installation)"
-  ensure
-    Dir.chdir(old_pwd)
-  end
+  
+    def run_yardoc(*args)
+      args << '--quiet'
+      args << @spec.require_paths
+      if @spec.extra_rdoc_files.size > 0
+        args << '-'
+        args += @spec.extra_rdoc_files
+      end
+      args = args.flatten.map {|arg| arg.to_s }
 
-  undef setup_rdoc
-  def setup_rdoc
-    if File.exist?(@doc_dir) && !File.writable?(@doc_dir) then
-      raise Gem::FilePermissionError.new(@doc_dir)
+      old_pwd = Dir.pwd
+      Dir.chdir(@spec.full_gem_path)
+      YARD::CLI::Yardoc.run(*args)
+    rescue Errno::EACCES => e
+      dirname = File.dirname e.message.split("-")[1].strip
+      raise Gem::FilePermissionError.new(dirname)
+    rescue => ex
+      alert_error "While generating documentation for #{@spec.full_name}"
+      ui.errs.puts "... MESSAGE:   #{ex}"
+      ui.errs.puts "... YARDDOC args: #{args.join(' ')}"
+      ui.errs.puts "\t#{ex.backtrace.join("\n\t")}" if Gem.configuration.backtrace
+      ui.errs.puts "(continuing with the rest of the installation)"
+    ensure
+      Dir.chdir(old_pwd)
     end
 
-    FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir)
+    undef setup_rdoc
+    def setup_rdoc
+      if File.exist?(@doc_dir) && !File.writable?(@doc_dir) then
+        raise Gem::FilePermissionError.new(@doc_dir)
+      end
 
-    self.class.load_rdoc if @spec.has_rdoc?
-    self.class.load_yardoc if @spec.has_yardoc?
-  end
+      FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir)
+
+      self.class.load_rdoc if @spec.has_rdoc?
+      self.class.load_yardoc if @spec.has_yardoc?
+    end
 
-  def install_yardoc
-    rdoc_dir = File.join(@doc_dir, 'rdoc')
+    def install_yardoc
+      rdoc_dir = File.join(@doc_dir, 'rdoc')
 
-    FileUtils.rm_rf rdoc_dir
+      FileUtils.rm_rf rdoc_dir
 
-    say "Installing YARD documentation for #{@spec.full_name}..."
-    run_yardoc '-o', rdoc_dir
-  end
+      say "Installing YARD documentation for #{@spec.full_name}..."
+      run_yardoc '-o', rdoc_dir
+    end
 
-  unless instance_methods.include?(:install_ri_yard)
     def install_ri_yard
       install_ri_yard_orig if @spec.has_rdoc?
+      return if @spec.has_yardoc?
+      
+      self.class.load_yardoc
+      say "Building YARD (yri) index for #{@spec.full_name}..."
+      run_yardoc '-c', '-n'
     end
     alias install_ri_yard_orig install_ri
     alias install_ri install_ri_yard

data/lib/yard.rb

@@ -1,5 +1,5 @@
 module YARD
-  VERSION = "0.5.2"
+  VERSION = "0.5.3"
   ROOT = File.dirname(__FILE__)
   TEMPLATE_ROOT = File.join(File.dirname(__FILE__), '..', 'templates')
   CONFIG_DIR = File.expand_path('~/.yard')

data/lib/yard/cli/base.rb

@@ -7,6 +7,10 @@ module YARD
     # 
     # @abstract
     class Base
+      def initialize
+        log.show_backtraces = false
+      end
+      
       # Adds a set of common options to the tail of the OptionParser
       # 
       # @param [OptionParser] opts the option parser object

data/lib/yard/cli/yard_graph.rb

@@ -20,6 +20,7 @@ module YARD
         
       # Creates a new instance of the command-line utility
       def initialize
+        super
         @serializer = YARD::Serializers::StdoutSerializer.new
         @options = SymbolHash[
           :format => :dot,

data/lib/yard/cli/yardoc.rb

@@ -14,11 +14,18 @@ module YARD
       # @return [Array<String>] list of Ruby source files to process
       attr_accessor :files
       
+      # @return [Array<String>] list of excluded paths (regexp matches)
+      attr_accessor :excluded
+      
       # @return [Boolean] whether to use the existing yardoc db if the 
       #   .yardoc already exists. Also makes use of file checksums to
       #   parse only changed files.
       attr_accessor :use_cache
       
+      # @return [Boolean] whether to generate output incrementally (
+      #   implies use_cache and generate)
+      attr_accessor :incremental
+      
       # @return [Boolean] whether to generate output
       attr_accessor :generate
       
@@ -32,6 +39,7 @@ module YARD
         
       # Creates a new instance of the commandline utility
       def initialize
+        super
         @options = SymbolHash.new(false)
         @options.update(
           :format => :html, 
@@ -45,9 +53,11 @@ module YARD
           :visibilities => [:public],
           :verifier => nil
         )
+        @excluded = []
         @files = []
         @use_cache = false
         @generate = true
+        @incremental = false
         @options_file = DEFAULT_YARDOPTS_FILE
       end
       
@@ -65,13 +75,14 @@ module YARD
           Registry.load
           checksums = Registry.checksums.dup
         end
-        YARD.parse(files)
+        YARD.parse(files, excluded)
         Registry.save(use_cache)
         
         if generate
-          if use_cache
+          if incremental
             generate_with_cache(checksums)
           else
+            Registry.load_all if use_cache
             Templates::Engine.generate(all_objects, options)
           end
         end
@@ -184,6 +195,7 @@ module YARD
       # Parses commandline options.
       # @param [Array<String>] args each tokenized argument
       def optparse(*args)
+        excluded = []
         query_expressions = []
         do_build_gems, do_rebuild_gems = false, false
         serialopts = SymbolHash.new
@@ -225,6 +237,16 @@ module YARD
           end
         end
         
+        opts.on('--incremental', 'Generates output for changed files only (implies -c)') do
+          self.incremental = true
+          self.generate = true
+          self.use_cache = true
+        end
+        
+        opts.on('--exclude REGEXP', 'Ignores a file if it matches path match (regexp)') do |path|
+          self.excluded << path
+        end
+        
         opts.on('--legacy', 'Use old style parser and handlers. Unavailable under Ruby 1.8.x') do
           YARD::Parser::SourceParser.parser_type = :ruby18
         end

data/lib/yard/cli/yri.rb

@@ -10,6 +10,7 @@ module YARD
       def self.run(*args) new.run(*args) end
         
       def initialize
+        super
         @cache = {}
         @search_paths = []
         add_default_paths

data/lib/yard/code_objects/base.rb

@@ -129,6 +129,7 @@ module YARD
         # @return [Base] 
         # @see #initialize
         def new(namespace, name, *args, &block)
+          raise ArgumentError, "invalid empty object name" if name.to_s.empty?
           if name.to_s[0,2] == NSEP
             name = name.to_s[2..-1]
             namespace = Registry.root
@@ -346,6 +347,14 @@ module YARD
       end
       alias_method :to_s, :path
       
+      # @param [Base, String] other another code object (or object path)
+      # @return [String] the shortest relative path from this object to +other+
+      def relative_path(other)
+        other = other.path if other.respond_to?(:path)
+        return other unless namespace
+        other.gsub(/^#{Regexp.quote namespace.path}(::|\.)?/, '')
+      end
+      
       # Renders the object using the {Templates::Engine templating system}.
       # 
       # @example Formats a class in plaintext

data/lib/yard/code_objects/class_object.rb

@@ -120,7 +120,7 @@ module YARD::CodeObjects
         raise ArgumentError, "superclass must be CodeObject, Proxy, String or Symbol" 
       end
 
-      if name == @superclass.name && namespace != YARD::Registry.root && object.is_a?(String)
+      if name == @superclass.name && namespace != YARD::Registry.root && !object.is_a?(Base)
         @superclass = Proxy.new(namespace.namespace, object)
       end
       

data/lib/yard/code_objects/method_object.rb

@@ -56,14 +56,30 @@ module YARD::CodeObjects
     def constructor?
       name == :initialize && scope == :instance && namespace.is_a?(ClassObject)
     end
+    
+    # Returns the read/writer info for the attribute if it is one
+    # @return [SymbolHash] if there is information about the attribute
+    # @return [nil] if the method is not an attribute
+    def attr_info
+      return nil unless namespace.is_a?(NamespaceObject)
+      namespace.attributes[scope][name.to_s.gsub(/=$/, '')]
+    end
+    
+    # @return [Boolean] whether the method is a writer attribute
+    def writer?
+      !!((info = attr_info) && info[:write] == self)
+    end
+
+    # @return [Boolean] whether the method is a reader attribute
+    def reader?
+      !!((info = attr_info) && info[:read] == self)
+    end
       
     # Tests if the object is defined as an attribute in the namespace
     # @return [Boolean] whether the object is an attribute
     def is_attribute?
-      return false unless namespace.is_a?(NamespaceObject)
-      attr_obj = namespace.attributes[scope][name.to_s.gsub(/=$/, '')]
-      return false unless attr_obj
-      attr_obj[name.to_s =~ /=$/ ? :write : :read] ? true : false
+      return false unless info = attr_info
+      info[name.to_s =~ /=$/ ? :write : :read] ? true : false
     end
       
     # Tests if the object is defined as an alias of another method