yard 0.2.1 → 0.2.2

data/{LICENSE.txt → LICENSE}

@@ -1,4 +1,4 @@
-Copyright (c) 2007 Loren Segal
+Copyright (c) 2007-2008 Loren Segal
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation

data/README

@@ -0,0 +1,211 @@
+= YARD Release 0.2.2 (June 16th 2008) 
+Copyright 2007-2008 Loren Segal
+
+== SYNOPSIS
+
+YARD is a documentation generation tool for the Ruby programming language
+(http://www.ruby-lang.org). It enables the user to generate consistent, usable
+documentation that can be exported to a number of formats very easily, and
+also supports extending for custom Ruby constructs such as custom class level 
+definitions. Below is a summary of some of YARD's notable features.
+
+
+== FEATURE LIST
+                                                                              
+1. <b>RDoc/SimpleMarkup Formatting Compatibility</b>: YARD is made to be compatible   
+   with RDoc formatting. In fact, YARD does no processing on RDoc documentation  
+   strings, and leaves this up to the output generation tool to decide how to    
+   render the documentation.                                                     
+
+2. <b>Yardoc Meta-tag Formatting Like Python, Java, Objective-C and other        
+   languages</b>: YARD uses a '@tag' style definition syntax for meta tags alongside 
+   regular code documentation. These tags should be able to happily sit side by  
+   side RDoc formatted documentation, but provide a much more consistent and     
+   usable way to describe important information about objects, such as what      
+   parameters they take and what types 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. Some of the main tags are listed below:   
+                                                                              
+   <b>Table 1. Meta-tags and their descriptions</b>                                    
+                                                                              
+   <tt>@param [Types] name description</tt>::
+     Description Allows for the definition of a method parameter with 
+     optional type information.
+                                                                              
+   <tt>@yieldparam [Types] name description</tt>::
+     Description Allows for the definition of a method parameter to a
+     yield block with optional type information.
+   
+   <tt>@yield description</tt>::                                        
+     Allows the developer to document the purpose of a yield block in 
+     a method.
+   
+   @return [Types] description</tt>::
+     Describes what the method returns with optional type information.
+
+   <tt>@deprecated description</tt>::
+     Informs the developer that a method is deprecated and should no 
+     longer be used. The description offers the developer an alternative 
+     solution or method for the problem.
+                                                 
+   <tt>@raise class description</tt>::
+     Tells the developer that the method may raise an exception and of 
+     what type. 
+   
+   <tt>@see name</tt>::
+     References another object, URL, or other for extra information. 
+
+   <tt>@since number</tt>::
+     Lists the version number in which the object first appeared. 
+
+   <tt>@version number</tt>::
+     Lists the current version of the documentation for the object. 
+
+   <tt>@author name</tt>::
+     The authors responsible for the module
+
+   You might have noticed the optional "types" declarations for certain tags.    
+   This allows the developer to document type signatures for ruby methods and    
+   parameters in a non intrusive but helpful and consistent manner. Instead of   
+   describing this data in the body of the description, a developer may formally 
+   declare the parameter or return type(s) in a single line. Consider the        
+   following Yardoc'd method:                                                    
+
+     ## 
+     # Reverses the contents of a String or IO object. 
+     # 
+     # @param [String, #read] contents the contents to reverse 
+     # @return [String] the contents reversed lexically 
+     def reverse(contents) 
+       contents = contents.read if respond_to? :read 
+       contents.reverse 
+     end                                        
+                                                                               
+   With the above @param tag, we learn that the contents parameter can either be
+   a String or any object that responds to the 'read' method, which is more      
+   powerful than the textual description, which says it should be an IO object.  
+   This also informs the developer that they should expect to receive a String   
+   object returned by the method, and although this may be obvious for a         
+   'reverse' method, it becomes very useful when the method name may not be as   
+   descriptive.                                                                  
+                                                                              
+3. <b>Custom Constructs and Extensibility of YARD</b>: Take for instance the example:        
+   
+     class A 
+       class << self 
+         def define_name(name, value) 
+           class_eval "def #{name}; #{value.inspect} end" 
+         end 
+       end 
+    
+       # Documentation string for this name 
+       define_name :publisher, "O'Reilly"
+     end
+                                                                              
+   This custom declaration provides dynamically generated code that is hard for a
+   documentation tool to properly document without help from the developer. To   
+   ease the pains of manually documenting the procedure, YARD can be extended by 
+   the developer to handled the 'define_name' construct and add the required     
+   method to the defined methods of the class with its documentation. This makes 
+   documenting external API's, especially dynamic ones, a lot more consistent for
+   consumption by the users.                                                     
+                                                                              
+4. <b>Raw Data Output</b>: YARD also outputs documented objects as raw data (the      
+   dumped Namespace) which can be reloaded to do generation at a later date, or  
+   even auditing on code. This means that any developer can use the raw data to  
+   perform output generation for any custom format, such as YAML, for instance.  
+   While YARD plans to support XHTML style documentation output as well as       
+   command line (text based) and possibly XML, this may still be useful for those
+   who would like to reap the benefits of YARD's processing in other forms, such 
+   as throwing all the documentation into a database. Another useful way of      
+   exploiting this raw data format would be to write tools that can auto generate
+   test cases, for example, or show possible unhandled exceptions in code.       
+                                                                              
+
+== USAGE                                                                        
+
+There are a couple of ways to use YARD. The first is via command-line, and the
+second is the Rake task. There are also the +yard-graph+ and +yri+ binaries to
+look at, if you want to poke around.
+
+=== 1. yardoc Command-line Tool
+
+The most obvious way to run YARD is to run the +yardoc+ binary file that comes
+with YARD. This will, among other things, generate the HTML documentation for
+your project code. You can type <tt>yardoc --help</tt> to see the options
+that YARD provides, but the easiest way to generate docs for your code is to
+simply type +yardoc+ in your project root. This will assume your files are
+located in the +lib/+ directory. If they are located elsewhere, you can specify
+paths and globs from the commandline via:
+
+  yardoc 'lib/**/*.rb' 'app/**/*.rb' ...etc...
+  
+The tool will generate a +.yardoc+ file which will store the cached database
+of your source code and documentation. If you want to re-generate your docs
+with another template you can simply use the <tt>--use-cache</tt> (or -c) 
+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 <tt>--protected</tt> or
+<tt>--private</tt> to the option switches.
+
+=== 2. Rake Task
+
+The second most obvious is to generate docs via a Rake task. You can do this by 
+adding the following to your +Rakefile+:
+
+  YARD::Rake::YardocTask.new do |t|
+    t.files   = ['lib/**/*.rb', OTHER_PATHS]   # optional
+    t.options = ['--any', '--extra', '--opts'] # optional
+  end
+  
+both the +files+ and +options+ settings are optional. +files+ will default to
+<tt>lib/**/*.rb</tt> and +options+ will represents any options you might want
+to add. Again, a full list of options is available by typing <tt>yardoc --help</tt>
+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'
+                                                                              
+=== 3. yri RI Implementation
+
+The yri binary will use the cached .yardoc database to give you quick ri-style
+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
+
+=== 4. yard-graph Graphviz Generator
+
+You can use +yard-graph+ to generate dot graphs of your code. This, of course,
+requires Graphviz (http://www.graphviz.org) and the +dot+ binary. By default
+this will generate a graph of the classes and modules in the best UML2 notation
+that Graphviz can support, but without any methods listed. With the <tt>--full</tt>
+option, methods and attributes will be listed. There is also a <tt>--dependencies</tt>
+option to show mixin inclusions. You can output to stdout or a file, or pipe directly
+to +dot+. The same public, protected and private visibility rules apply to yard-graph.
+More options can be seen by typing <tt>yard-graph --help</tt>, but here is an example:
+
+  > yard-graph --protected --full --dependencies
+
+
+== CHANGELOG
+
+- <b>Jun.16.08</b>: 0.2.2 release. This is the largest changset since yard's 
+  conception and involves a complete overhaul of the parser and API to make it
+  more robust and far easier to extend and use for the developer.
+
+- <b>Feb.20.08</b>: 0.2.1 release. 
+
+- <b>Feb.24.07</b>: Released 0.1a experimental version for testing. The goal here is
+  to get people testing YARD on their code because there are too many possible  
+  code styles to fit into a sane amount of test cases. It also demonstrates the 
+  power of YARD and what to expect from the syntax (Yardoc style meta tags).    
+                                                                              
+
+== COPYRIGHT                                                                    
+
+YARD was created in 2007-2008 by Loren Segal (lsegal -AT- soen -DOT- ca) and is    
+licensed under the MIT license. Please see the LICENSE.txt for more information.

data/Rakefile

@@ -0,0 +1,31 @@
+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'
+
+task :default => :specs
+
+load 'yard.gemspec'
+Rake::GemPackageTask.new(SPEC) do |pkg|
+  pkg.gem_spec = SPEC
+  pkg.need_zip = true
+  pkg.need_tar = true
+end
+
+desc "Install the gem locally"
+task :install => :package do 
+  sh "#{SUDO} gem install pkg/#{SPEC.name}-#{SPEC.version}.gem --local"
+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_files = Dir["spec/**/*_spec.rb"].sort
+end
+
+YARD::Rake::YardocTask.new

data/benchmarks/builtins_vs_eval.rb

@@ -0,0 +1,23 @@
+require 'benchmark'
+require File.join(File.dirname(__FILE__), '..', 'lib', 'yard')
+
+TIMES = (ARGV[0] || 10_000).to_i
+
+def bench_builtins(name)
+  YARD::CodeObjects::BUILTIN_EXCEPTIONS_HASH.has_key? name
+end
+
+def bench_eval(name)
+  eval(name).is_a?(Class)
+rescue 
+  false
+end
+
+Benchmark.bmbm do |b|
+  b.report("builtins PASS") { TIMES.times {YARD::CodeObjects::BUILTIN_EXCEPTIONS.each {|y| bench_builtins(y) } } }
+  b.report("eval PASS") { TIMES.times {YARD::CodeObjects::BUILTIN_EXCEPTIONS.each {|y| bench_eval(y) }} }
+  b.report("builtins FAIL") { TIMES.times {YARD::CodeObjects::BUILTIN_MODULES.each {|y| bench_builtins(y) } } }
+  b.report("eval FAIL") { TIMES.times {YARD::CodeObjects::BUILTIN_MODULES.each {|y| bench_eval(y) }} }
+  b.report("builtins ANY") { TIMES.times {YARD::CodeObjects::BUILTIN_CLASSES.each {|y| bench_builtins(y) } } }
+  b.report("eval ANY") { TIMES.times {YARD::CodeObjects::BUILTIN_CLASSES.each {|y| bench_eval(y) }} }
+end

data/benchmarks/erb_vs_erubis.rb

@@ -0,0 +1,53 @@
+require 'rubygems'
+require 'erubis'
+require 'erubis/tiny'
+require 'erb'
+require "benchmark"
+require File.join(File.dirname(__FILE__), '..', 'lib', 'yard')
+
+def rungen
+  YARD::Registry.clear
+  YARD::CLI::Yardoc.run('--quiet', '--use-cache') 
+end
+
+Benchmark.bmbm do |x|
+  x.report("erubis") do
+    eval <<-eof
+      class YARD::Generators::Base
+        def erb(str) Erubis::Eruby.new(str) end
+      end
+    eof
+    
+    rungen
+  end
+
+  x.report("fast-erubis") do
+    eval <<-eof
+      class YARD::Generators::Base
+        def erb(str) Erubis::FastEruby.new(str) end
+      end
+    eof
+    
+    rungen
+  end
+
+  x.report("tiny-erubis") do
+    eval <<-eof
+      class YARD::Generators::Base
+        def erb(str) Erubis::TinyEruby.new(str) end
+      end
+    eof
+    
+    rungen
+  end
+
+  x.report("erb")  do
+    eval <<-eof
+      class YARD::Generators::Base
+        def erb(str) ERB.new(str, nil, '<>') end
+      end
+    eof
+    
+    rungen
+  end
+end

data/benchmarks/generation.rb

@@ -0,0 +1,37 @@
+require "benchmark"
+require File.join(File.dirname(__FILE__), '..', 'lib', 'yard')
+
+unless YARD::CodeObjects::Proxy.private_instance_methods.include?('to_obj')
+  raise "This benchmark is dependent on YARD::CodeObjects::Proxy#to_obj" 
+end
+
+def rungen
+  YARD::Registry.clear
+  YARD::CLI::Yardoc.run('--quiet', '--use-cache') 
+end
+
+def redef(lock = false)
+  eval <<-eof
+    class YARD::CodeObjects::Proxy; 
+      def to_obj
+        @obj #{lock ? '||' : ''}= YARD::Registry.resolve(@namespace, @name) 
+      end 
+    end
+  eof
+end
+
+Benchmark.bmbm do |x|
+  x.report("gen-w/o-locking")  { redef;       rungen }
+  x.report("gen-with-locking") { redef(true); rungen }
+end
+
+=begin Results from 2008-06-07
+Rehearsal ----------------------------------------------------
+gen-w/o-locking    9.650000   0.450000  10.100000 ( 10.150556)
+gen-with-locking   7.790000   0.400000   8.190000 (  8.373811)
+------------------------------------------ total: 18.290000sec
+
+                       user     system      total        real
+gen-w/o-locking    9.820000   0.430000  10.250000 ( 10.293283)
+gen-with-locking   7.820000   0.380000   8.200000 (  8.243326)
+=end

data/benchmarks/parsing.rb

@@ -0,0 +1,33 @@
+require "benchmark"
+require 'lib/yard'
+
+Benchmark.bmbm do |x|
+  x.report("parse in order") { YARD::Registry.clear; YARD.parse YARD::PATH_ORDER, Logger::ERROR } 
+  x.report("parse") { YARD::Registry.clear; YARD.parse 'lib/**/*.rb', Logger::ERROR } 
+end
+
+=begin
+load_order branch (2008-06-07):
+
+Rehearsal --------------------------------------------------
+parse in order   6.510000   0.050000   6.560000 (  6.563223)
+parse            6.300000   0.040000   6.340000 (  6.362272)
+---------------------------------------- total: 12.900000sec
+
+                     user     system      total        real
+parse in order   6.310000   0.060000   6.370000 (  6.390945)
+parse            6.300000   0.050000   6.350000 (  6.366709)
+
+
+api_changes branch before merge (2008-06-07)
+
+Rehearsal --------------------------------------------------
+parse in order   6.330000   0.050000   6.380000 (  6.397552)
+parse            6.380000   0.050000   6.430000 (  6.446954)
+---------------------------------------- total: 12.810000sec
+
+                     user     system      total        real
+parse in order   6.320000   0.040000   6.360000 (  6.394460)
+parse            6.040000   0.040000   6.080000 (  6.099738)
+=end
+

data/bin/view_generator

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+require File.dirname(__FILE__) + '/../lib/yard'
+
+log.level = Logger::DEBUG
+YARD::Registry.load
+gclass = eval("YARD::Generators::#{ARGV[0]}")
+sclass = ARGV[1] == "nil" ? nil : eval("YARD::Serializers::#{ARGV[1]}") 
+obj = ARGV[2] == "all" ? YARD::Registry.all(:module, :class) : P(ARGV[2])
+format = ARGV[3].to_sym
+
+if sclass
+  sclass = sclass.new 
+else
+  sclass = YARD::Serializers::StdoutSerializer.new(80)
+end
+verifier = lambda {|gen, obj| return false if gen.respond_to?(:visibility) && [:protected, :private].include?(gen.visibility) }
+gclass.new(:format => format, :template => :default, :serializer => sclass, :verifier => verifier).generate(obj)

data/bin/yard-graph

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require File.dirname(__FILE__) + '/../lib/yard'
+
+YARD::CLI::YardGraph.run(*ARGV)

data/bin/yardoc

@@ -1,96 +1,4 @@
 #!/usr/bin/env ruby
 require File.dirname(__FILE__) + '/../lib/yard'
-include YARD
 
-if ARGV[0] == "-h"
-  puts "yardoc #{VERSION}"
-  return
-end
-
-Dir.mkdir("doc") unless FileTest.directory?("doc")
-Namespace.load(Namespace::DEFAULT_YARDOC_FILE, true)
-ac = File.open("doc/all-classes.html", "w") 
-ac.puts <<-eof
-<html>
-  <head>
-    <base target="main" />
-  </head>
-  <body>
-  <h3>All Classes</h3>
-eof
-am = File.open("doc/all-modules.html", "w") 
-am.puts <<-eof
-<html>
-  <head>
-    <base target="main" />
-  </head>
-  <body>
-  <h3>All Modules</h3>
-eof
-meths = []
-Namespace.all.sort.each do |path|
-  object = Namespace.at(path)
-  if object.is_a?(MethodObject) && object.visibility == :public
-    meths << [object.name, object]
-  end
-  
-  indexfile = nil
-
-  case object
-  when ClassObject
-    indexfile = ac
-  when ModuleObject
-    indexfile = am
-  else
-    next
-  end
-  
-  indexfile.puts "<a href='" + path.gsub("::","_") + ".html'>" + path + "</a><br />"
-  puts "Generating " + (docfile = "doc/#{path.gsub('::','_')}.html") + "..."
-  File.open(docfile, "w") {|f| f.write(object.to_s) }
-end
-ac.puts "</body></html>"
-ac.close
-am.puts "</body></html>"
-am.close
-
-File.open("doc/all-methods.html", "w") do |f|
-  f.puts <<-eof
-    <html>
-      <head>
-        <base target="main" />
-      </head>
-      <body>
-      <h3>All Methods</h3>
-  eof
-  meths.sort {|a,b| a.first <=> b.first }.each do |name, object|
-    f.puts "<a href='" + object.parent.path.gsub("::", "_") + ".html##{object.scope}_method-#{name}'>#{name}</a><br />"
-  end
-end
-
-if ARGV[0]
-  main_page = ARGV[0]
-else
-  main_page = Namespace.all.sort.find {|name| Namespace.at(name).is_a? YARD::ClassObject }
-end
-main_page = main_page.gsub("::", "_") + ".html"
-File.open("doc/index.html", "w") do |f|
-  f.puts <<-eof
-  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
-    "http://www.w3.org/TR/html4/loose.dtd">
-  <html>
-    <head>
-      <meta http-equiv="Content-type" content="text/html; charset=utf-8">
-      <title>Ruby Classes</title>
-    </head>
-    <frameset cols="250,*">
-      <frameset rows="40%,40%,20%">
-        <frame src="all-classes.html">
-        <frame src="all-modules.html">
-        <frame src="all-methods.html">
-      </frameset>
-      <frame name="main" src="#{main_page}">
-    </frameset>
-  </html>
-eof
-end
+YARD::CLI::Yardoc.run(*ARGV)