yard 0.2.3.5 → 0.4.0

data/{README.markdown → README.md}

@@ -1,5 +1,5 @@
-YARD Release 0.2.3.4 (August 7th 2009)
-=====================================
+YARD Release 0.4.0 "The Whole Nine" (Nov 15th 2009)
+===================================================
 
 **Homepage**:  [http://yard.rubyforge.org](http://yard.rubyforge.org)   
 **IRC**:       **Join us on IRC in #yard on irc.freenode.net!**   
@@ -35,7 +35,7 @@ important information about objects, such as what parameters they take and what
 they are expected to be, what type a
method should return, what exceptions it can 
 raise, if it is deprecated, etc.. It also allows information to be better (and more 
 consistently) organized
during the output generation phase. You can find a list
-of tags in the {file:GETTING_STARTED.markdown#taglist GETTING_STARTED.markdown} file.
+of tags in the {file:GettingStarted.md#taglist GettingStarted.md} file.
 
 YARD also supports an optional "types" declarations for certain tags.

 This allows the developer to document type signatures for ruby methods and

@@ -121,19 +121,52 @@ option to speed up the generation process by skipping source parsing.
 
 YARD will by default only document code in your public visibility. You can
 document your protected and private code by adding `--protected` or
-`--private` to the option switches.
+`--private` to the option switches. In addition, you can add `--no-private`
+to also ignore any object that has the `@private` meta-tag. This is similar
+to RDoc's ":nodoc:" behaviour, though the distinction is important. RDoc
+implies that the object with :nodoc: would not be documented, whereas
+YARD still recommends documenting private objects for the private API (for
+maintainer/developer consumption).
 
-You can also add extra informative files with the `--files` switch,
-for example:
+You can also add extra informative files (README, LICENSE) by separating
+the globs and the filenames with '-'.
 
-    $ yardoc --files FAQ,LICENSE
+    $ yardoc 'app/**/*.rb' - README LICENSE FAQ
+    
+If no globs preceed the '-' argument, the default glob (lib/**/*.rb) is
+used:
 
-Note that the README file is specified with its own `--readme` switch.
+    $ yardoc - README LICENSE FAQ
+
+Note that the README file can be specified with its own `--readme` switch.
 
 You can also add a `.yardopts` file to your project directory which lists
 the switches separated by whitespace (newlines or space) to pass to yardoc 
 whenever it is run.
 
+<h4>Queries</h4>
+
+The `yardoc` tool also supports a `--query` argument to only include objects
+that match a certain data or meta-data query. The query syntax is Ruby, though
+a few shortcuts are available. For instance, to document only objects that have
+an "@api" tag with the value "public", all of the following syntaxes would give
+the same result:
+
+    --query '@api.text == "public"'
+    --query 'object.has_tag?(:api) && object.tag(:api).text == "public"'
+    --query 'has_tag?(:api) && tag(:api).text == "public"'
+
+Note that the "@tag" syntax returns the first tag named "tag" on the object. 
+To return the array of all tags named "tag", use "@@tag".
+    
+Multiple `--query` arguments are allowed in the command line parameters. The
+following two lines both check for the existence of a return and param tag:
+
+    --query '@return' --query '@param'
+    --query '@rturn && @param'
+    
+For more information about the query syntax, see the {YARD::Verifier} class.
+
 **2. Rake Task**
 
 The second most obvious is to generate docs via a Rake task. You can do this by 
@@ -150,7 +183,7 @@ to add. Again, a full list of options is available by typing `yardoc --help`
 in a shell. You can also override the options at the Rake command-line with the
 OPTS environment variable:
 
-    $ rake yardoc OPTS='--any --extra --opts'
+    $ rake yard OPTS='--any --extra --opts'
                                                                               
 **3. `yri` RI Implementation**
 
@@ -159,7 +192,10 @@ access to your documentation. It's way faster than ri but currently does not
 work with the stdlib or core Ruby libraries, only the active project. Example:
 
     $ yri YARD::Handlers::Base#register
-    $ yri File::relative_path
+    $ yri File.relative_path
+    
+Note that class methods must not be referred to with the "::" namespace 
+separator. Only modules, classes and constants should use "::".
 
 **4. `yard-graph` Graphviz Generator**
 
@@ -178,6 +214,24 @@ More options can be seen by typing `yard-graph --help`, but here is an example:
 CHANGELOG
 ---------
 
+- **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)
+    - Greatly expanded YARD documentation
+    - Added plugin support
+    - New `@abstract` and `@private` tags
+    - Changed default rake task to `rake yard`
+    - Read about changes in {file:WhatsNew.md}
+
+- **August.13.09**: 0.2.3.5 release
+    - Minor bug fixes.
+
+- **August.07.09**: 0.2.3.4 release
+    - Minor bug fixes.
+
+- **July.26.09**: 0.2.3.3 release
+    - Minor bug fixes.
+
 - **July.06.09**: 0.2.3.2 release
     - Fix Textile hard-break issues
     - Add description for @see tag to use as link title in HTML docs.
@@ -196,7 +250,7 @@ CHANGELOG
       RDoc. To take advantage of this plugin, set `has_rdoc = 'yard'` in your
       .gemspec file.
 
-- **Jun.07.09**: 0.2.3 release. See the {file:WHATSNEW.markdown} file for a 
+- **Jun.07.09**: 0.2.3 release. See the {file:WhatsNew.md} file for a 
   list of important new features.
 
 - **Jun.16.08**: 0.2.2 release. This is the largest changset since yard's 

data/Rakefile

@@ -1,8 +1,6 @@
 require File.dirname(__FILE__) + '/lib/yard'
 require 'rubygems'
 require 'rake/gempackagetask'
-require 'spec'
-require 'spec/rake/spectask'
 
 WINDOWS = (PLATFORM =~ /win32|cygwin/ ? true : false) rescue false
 SUDO = WINDOWS ? '' : 'sudo'
@@ -17,22 +15,36 @@ Rake::GemPackageTask.new(SPEC) do |pkg|
 end
 
 desc "Install the gem locally"
-task :install => :package do 
-  sh "#{SUDO} gem install pkg/#{SPEC.name}-#{SPEC.version}.gem --local"
+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']
 end
 
-desc "Run all specs"
-Spec::Rake::SpecTask.new("specs") do |t|
-  $DEBUG = true if ENV['DEBUG']
-  t.spec_opts = ["--format", "specdoc", "--colour"]
-  t.spec_opts += ["--require", File.join(File.dirname(__FILE__), 'spec', 'spec_helper')]
-  t.spec_files = Dir["spec/**/*_spec.rb"].sort
-  t.rcov = true if ENV['RCOV']
-  t.rcov_opts = ['-x', '_spec\.rb$,spec_helper\.rb$']
+begin
+  require 'spec'
+  require 'spec/rake/spectask'
+
+  desc "Run all specs"
+  Spec::Rake::SpecTask.new("specs") do |t|
+    $DEBUG = true if ENV['DEBUG']
+    t.spec_opts = ["--format", "specdoc", "--colour"]
+    t.spec_opts += ["--require", File.join(File.dirname(__FILE__), 'spec', 'spec_helper')]
+    t.spec_files = Dir["spec/**/*_spec.rb"].sort
+  
+    if ENV['RCOV']
+      hide = '_spec\.rb$,spec_helper\.rb$,ruby_lex\.rb$,autoload\.rb$'
+      hide += ',legacy\/.+_handler,html_syntax_highlight_helper18\.rb$' if RUBY19
+      hide += ',ruby_parser\.rb$,ast_node\.rb$,handlers\/ruby\/[^\/]+\.rb$,html_syntax_highlight_helper\.rb$' if RUBY18
+      t.rcov = true 
+      t.rcov_opts = ['-x', hide]
+    end
+  end
+  task :spec => :specs
+rescue LoadError
+  warn "warn: RSpec tests not available. `gem install rspec` to enable them."
 end
-task :spec => :specs
 
 YARD::Rake::YardocTask.new do |t|
+  t.options += ['--title', "YARD #{YARD::VERSION} Documentation"]
   t.after = lambda { `cp -R docs/images/ doc/images/` }
 end

data/benchmarks/concat_vs_join.rb

@@ -0,0 +1,12 @@
+require "benchmark"
+
+STR1 = "Hello"
+JOIN = "::"
+STR2 = "World"
+
+TESTS = 100_000
+Benchmark.bmbm do |results|
+  results.report("concat") { TESTS.times { "".concat(STR1).concat(JOIN).concat(STR2) } }
+  results.report("add   ") { TESTS.times { STR1 + JOIN + STR2 } }
+  results.report("join  ") { TESTS.times { [STR1, STR2].join(JOIN) } }
+end

data/benchmarks/erb_vs_erubis.rb

@@ -6,16 +6,16 @@ require "benchmark"
 require File.join(File.dirname(__FILE__), '..', 'lib', 'yard')
 
 def rungen
-  YARD::Registry.clear
-  YARD::CLI::Yardoc.run('--quiet', '--use-cache') 
+  YARD::Registry.load_yardoc(File.join(File.dirname(__FILE__), '..', '.yardoc'))
+  YARD::Registry.at("YARD::CodeObjects::Base").format(:format => :html)
 end
 
 Benchmark.bmbm do |x|
   x.report("erubis") do
     eval <<-eof
-      class YARD::Generators::Base
-        def erb(str) Erubis::Eruby.new(str) end
-      end
+      module YARD; module Templates; module Template
+        def erb_with(str, x) Erubis::Eruby.new(str) end
+      end end end
     eof
     
     rungen
@@ -23,9 +23,9 @@ Benchmark.bmbm do |x|
 
   x.report("fast-erubis") do
     eval <<-eof
-      class YARD::Generators::Base
-        def erb(str) Erubis::FastEruby.new(str) end
-      end
+      module YARD; module Templates; module Template
+        def erb_with(str, x) Erubis::FastEruby.new(str) end
+      end end end
     eof
     
     rungen
@@ -33,9 +33,9 @@ Benchmark.bmbm do |x|
 
   x.report("tiny-erubis") do
     eval <<-eof
-      class YARD::Generators::Base
-        def erb(str) Erubis::TinyEruby.new(str) end
-      end
+      module YARD; module Templates; module Template
+        def erb_with(str, x) Erubis::TinyEruby.new(str) end
+      end end end
     eof
     
     rungen
@@ -43,9 +43,9 @@ Benchmark.bmbm do |x|
 
   x.report("erb")  do
     eval <<-eof
-      class YARD::Generators::Base
-        def erb(str) ERB.new(str, nil, '<>') end
-      end
+       module YARD; module Templates; module Template
+        def erb_with(str, x) ERB.new(str, nil) end
+      end end end
     eof
     
     rungen

data/benchmarks/marshal_vs_dbm.rb

@@ -29,7 +29,7 @@ def write_marshal
   File.unlink(MARSHAL_FILE) if File.exist?(MARSHAL_FILE)
   handle = {}
   NUM_INDICES.times {|t| handle[t.to_s] = generate_index }
-  File.open(MARSHAL_FILE, "w") {|f| f.write(Marshal.dump(handle)) }
+  File.open(MARSHAL_FILE, "wb") {|f| f.write(Marshal.dump(handle)) }
 end
 
 def read_marshal

data/benchmarks/pathname_vs_string.rb

@@ -0,0 +1,50 @@
+require 'pathname'
+require "benchmark"
+require File.dirname(__FILE__) + '/../lib/yard'
+
+pathobj = Pathname.new("a/b/c")
+strobj  = "a/b/c"
+
+TIMES = 1_000
+
+puts "join:"
+Benchmark.bmbm do |x|
+  x.report("pathname") { TIMES.times { Pathname.new("a/b/c").join("d", "e", "f") } }
+  x.report("string  ") { TIMES.times { File.join("a/b/c", "d", "e", "f") } }
+  x.report("pathname-sameobject") { TIMES.times { pathobj.join("d", "e", "f") } }
+  x.report("string-sameobject  ") { TIMES.times { File.join(strobj, "d", "e", "f") } }
+end
+
+puts
+puts
+puts "cleanpath:"
+Benchmark.bmbm do |x|
+  x.report("pathname") { TIMES.times { Pathname.new("a/b//.././c").cleanpath } }
+  x.report("string  ") { TIMES.times { File.cleanpath("a/b//.././c") } }
+end
+
+__END__
+join:
+Rehearsal -------------------------------------------------------
+pathname              0.330000   0.020000   0.350000 (  0.353481)
+string                0.010000   0.000000   0.010000 (  0.001390)
+pathname-sameobject   0.360000   0.020000   0.380000 (  0.384473)
+string-sameobject     0.000000   0.000000   0.000000 (  0.001187)
+---------------------------------------------- total: 0.740000sec
+
+                          user     system      total        real
+pathname              0.330000   0.020000   0.350000 (  0.350820)
+string                0.000000   0.000000   0.000000 (  0.001055)
+pathname-sameobject   0.330000   0.010000   0.340000 (  0.346949)
+string-sameobject     0.000000   0.000000   0.000000 (  0.001141)
+
+
+cleanpath:
+Rehearsal --------------------------------------------
+pathname   0.060000   0.000000   0.060000 (  0.059767)
+string     0.010000   0.000000   0.010000 (  0.013775)
+----------------------------------- total: 0.070000sec
+
+               user     system      total        real
+pathname   0.060000   0.000000   0.060000 (  0.059697)
+string     0.020000   0.000000   0.020000 (  0.013624)

data/benchmarks/template_erb.rb

@@ -0,0 +1,22 @@
+require "benchmark"
+require File.join(File.dirname(__FILE__), '..', 'lib', 'yard')
+
+YARD::Registry.load_yardoc(File.join(File.dirname(__FILE__), '..', '.yardoc'))
+obj = YARD::Registry.at("YARD::CodeObjects::Base")
+
+TIMES = 3
+Benchmark.bm do |x|
+  x.report("trim-line") { TIMES.times { obj.format(:format => :html) } }
+  module YARD
+    module Templates
+      module Template
+        def erb(section, &block)
+          erb = ERB.new(cache(section), nil)
+          erb.filename = cache_filename(section).to_s
+          erb.result(binding, &block)
+        end
+      end
+    end
+  end
+  x.report("no-trim  ") { TIMES.times { obj.format(:format => :html) } }
+end

data/benchmarks/template_format.rb

@@ -0,0 +1,6 @@
+require "benchmark"
+require File.join(File.dirname(__FILE__), '..', 'lib', 'yard')
+
+YARD::Registry.load_yardoc(File.join(File.dirname(__FILE__), '..', '.yardoc'))
+obj = YARD::Registry.at("YARD::CodeObjects::Base")
+puts Benchmark.measure { obj.format(:format => :html) }

data/benchmarks/template_profile.rb

@@ -0,0 +1,17 @@
+require 'rubygems'
+require 'ruby-prof'
+#require 'benchmark'
+require File.join(File.dirname(__FILE__), '..', 'lib', 'yard')
+
+YARD::Registry.load_yardoc(File.join(File.dirname(__FILE__), '..', '.yardoc'))
+obj = YARD::Registry.at("YARD::CodeObjects::Base")
+
+#PerfTools::CpuProfiler.start("template_profile") do
+#end
+
+result = RubyProf.profile do
+  obj.format(:format => :html, :no_highlight => true)
+end
+
+printer = RubyProf::CallTreePrinter.new(result)
+printer.print(STDOUT)

data/bin/yri

@@ -10,11 +10,20 @@ else
   output = YARD::Serializers::ProcessSerializer.new('less')
 end
 
-object = YARD::Registry.at(ARGV[0])
-options = {
-  :format => :text, 
-  :template => :default, 
-  :serializer => output
-}
+if ARGV[0].nil? || ARGV[0].empty?
+  puts "Missing object argument"
+  exit(1)
+end
+
+obj = YARD::Registry.at(ARGV[0])
+if obj.nil?
+  puts "No documentation for #{ARGV[0]}"
+  exit(1)
+end
 
-YARD::Generators::QuickDocGenerator.new(options).generate(object)
+if obj.type == :method && obj.is_alias?
+  tmp = P(obj.namespace, (obj.scope == :instance ? "#" : "") + 
+    obj.namespace.aliases[obj].to_s) 
+  obj = tmp unless YARD::CodeObjects::Proxy === tmp
+end
+obj.format(:serializer => output)

data/docs/{GETTING_STARTED.markdown → GettingStarted.md}

@@ -8,6 +8,7 @@ document will cover the most common ways to use YARD:
 * [Using YARD to Generate Documentation](#using)
 * [Extending YARD](#extending)
 * [Templating YARD](#templating)
+* [Plugin Support](#plugins)
 
 <a name="docing"></a>
 Documenting Code with YARD
@@ -32,10 +33,10 @@ and easier to read. Consider the RDoc documentation for a method reverse:
     #
     # == Returns:
     # A string representing the object in a specified
-    #
     # format.
+    #
     def to_format(format = :html)
-      # reverse the string
+      # format the object
     end
     
 While this may seem easy enough to read and understand, it's hard for a machine
@@ -51,6 +52,7 @@ In YARD, we would simply define our method as:
     # @param [Symbol] format the format type, `:text` or `:html`
     # @return [String] the object converted into the expected format.
     def to_format(format = :html)
+      # format the object
     end
     
 Using tags we can add semantic metadata to our code without worrying about
@@ -114,6 +116,11 @@ List of Tags
     
 A list of common tags and example usage is below:
 
+  * `@abstract`: Marks a class/module/method as abstract with optional
+    implementor information.
+    
+        @abstract Subclass and override {#run} to implement a custom Threadable class.
+
   * `@author`: List the author(s) of a class/method
 
         @author Full Name
@@ -161,6 +168,15 @@ A list of common tags and example usage is below:
   * `@param`: Defines method parameters
 
         @param [optional, types, ...] argname description
+        
+  * `@private`: Defines an object as private. This exists for classes,
+    modules and constants that do not obey Ruby's visibility rules. For
+    instance, an inner class might be considered "private", though Ruby
+    would make no such distinction. By declaring the @private tag, the
+    class can be hidden from documentation by using the `--no-private`
+    command-line switch to yardoc (see {file:README.md}).
+    
+        @private
 
   * `@raise`: Describes an Exception that a method may throw
 
@@ -213,7 +229,7 @@ Other Extended Syntax
 To minimize rewriting of documentation and to ease maintenance, a special
 tag syntax is allowed to reference tags from other objects. Doing this allows
 a tag to be added as meta-data for multiple objects. A full example of this
-syntax is found in the {file:TAGS.markdown#reftags TAGS.markdown} file.
+syntax is found in the {file:Tags.md#reftags Tags} file.
 
 **Inter-Document Links**
 
@@ -233,7 +249,7 @@ documentation to HTML document files. In addition to this, YARD ships with
 two more tools allowing you to quickly view `ri`-style documentation for
 a specific class or method as well as an extra tool to generate UML diagrams
 for your code using [Graphviz][graphviz]. An overview of these tools can
-be found in the {file:README.markdown README} under the Usage section.
+be found in the {file:README.md README} under the Usage section.
 
 <a name="extending"></a>
 Extending YARD
@@ -242,22 +258,44 @@ Extending YARD
 There are many ways to extend YARD to support non-standard Ruby syntax (DSLs), 
 add new meta-data tags or programmatically access the intermediate metadata
 and documentation from code. An overview of YARD's full architecture can be
-found in the {file:OVERVIEW.markdown} document.
+found in the {file:Overview.md} document.
 
-For information on adding support for Ruby DSLs, see the {file:HANDLERS.markdown}
-and {file:PARSER.markdown} architecture documents.
+For information on adding support for Ruby DSLs, see the {file:Handlers.md}
+and {file:Parser.md} architecture documents.
 
-For information on adding extra tags, see {file:TAGS.markdown}.
+For information on adding extra tags, see {file:Tags.md}.
 
 For information on accessing the data YARD stores about your documentation,
-look at the {file:CODE_OBJECTS.markdown} architecture document.
+look at the {file:CodeObjects.md} architecture document.
 
 <a name="templating"></a>
 Templating YARD
 ===============
 
 In many cases you may want to change the style of YARD's templates or add extra
-information after extending it. The {file:GENERATORS.markdown} architecture
+information after extending it. The {file:Templates.md} architecture
 document covers the basics of how YARD's templating system works.
 
-[graphviz]:http://www.graphviz.org
+<a name="plugins"></a>
+Plugin Support
+==============
+
+As of 0.4, YARD will automatically load any gem named with the prefix of
+`yard-` or `yard_`. You can use this to load a custom plugin that 
+[extend](#extending) YARD's functionality. A good example of this
+is the [yard-rspec][yard-rspec] plugin, which adds [RSpec][rspec] specifications
+to your documentation (`yardoc` and `yri`). You can try it out by installing
+the gem or cloning the project and trying the example:
+
+    $ gem install yard-rspec -s http://gemcutter.org
+    or
+    $ git clone git://github.com/lsegal/yard-spec-plugin
+
+YARD also provides a way to temporarily disable plugins on a per-user basis.
+To disable a plugin create the file `~/.yard/ignored_plugins` with a list
+of plugin names separated by newlines. Note that the `.yard` directory might
+not exist, so you may need to create it.
+
+[graphviz]:http://www.graphviz.org
+[yard-rspec]:http://github.com/lsegal/yard-spec-plugin
+[rspec]:http://rspec.info