yard 0.2.2 → 0.2.3

data/LICENSE

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

data/README.markdown

@@ -0,0 +1,200 @@
+YARD Release 0.2.3 (June 7th 2009) 
+===================================
+
+**Homepage**:  [http://yard.rubyforge.org](http://yard.rubyforge.org)   
+**IRC**:       **Join us on IRC in #yard on irc.freenode.net!**   
+**Git**:       [http://github.com/lsegal/yard](http://github.com/lsegal/yard)   
+**Author**:    Loren Segal   
+**Copyright**: 2007-2009    
+**License**:   MIT License
+
+
+SYNOPSIS
+--------
+
+YARD is a documentation generation tool for the Ruby programming language.

+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. RDoc/SimpleMarkup Formatting Compatibility**: 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. Yardoc Meta-tag Formatting Like Python, Java, Objective-C and other languages**:

+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. You can find a list
+of tags in the {file:GETTING_STARTED.markdown#taglist GETTING_STARTED.markdown} file.
+
+YARD also supports an 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. Custom Constructs and Extensibility of YARD**: 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. Raw Data Output**: 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 `yardoc --help` 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 `--use-cache` (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 `--protected` or
+`--private` to the option switches.
+
+You can also add extra informative files with the `--files` switch,
+for example:
+
+    $ yardoc --files FAQ,LICENSE
+
+Note that the README file is 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.
+
+**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
+`lib/**/*.rb` and `options` will represents any options you might want
+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'
+                                                                              
+**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 `--full`
+option, methods and attributes will be listed. There is also a `--dependencies`
+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 `yard-graph --help`, but here is an example:
+
+    $ yard-graph --protected --full --dependencies
+
+
+CHANGELOG
+---------
+
+- **Jun.07.09**: 0.2.3 release. See the {file:WHATSNEW.markdown} file for a 
+  list of important new features.
+
+- **Jun.16.08**: 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.
+
+- **Feb.20.08**: 0.2.1 release. 
+
+- **Feb.24.07**: 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 &copy; 2007-2009 by [Loren Segal](mailto:lsegal@soen.ca). Licensed under the MIT 
+license. Please see the {file:LICENSE} for more information.

data/Rakefile

@@ -19,6 +19,7 @@ end
 desc "Install the gem locally"
 task :install => :package do 
   sh "#{SUDO} gem install pkg/#{SPEC.name}-#{SPEC.version}.gem --local"
+  sh "rm -rf pkg/yard-#{SPEC.version}" unless ENV['KEEP_FILES']
 end
 
 desc "Run all specs"
@@ -26,6 +27,10 @@ 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
+  # t.rcov = true
+  t.rcov_opts = ['-x', '_spec\.rb$,spec_helper\.rb$']
 end
 
-YARD::Rake::YardocTask.new
+YARD::Rake::YardocTask.new do |t|
+  t.after = lambda { `cp -R docs/images/ doc/images/` }
+end

data/benchmarks/format_args.rb

@@ -0,0 +1,46 @@
+require "benchmark"
+require 'lib/yard'
+
+def format_args_regex(object)
+  if object.signature
+    object.signature[/#{Regexp.quote object.name.to_s}\s*(.*)/, 1]
+  else
+    ""
+  end
+end
+
+def format_args_parameters(object)
+  if !object.parameters.empty?
+    args = object.parameters.map {|n, v| v ? "#{n} = #{v}" : n.to_s }.join(", ")
+    "(#{args})"
+  else
+    ""
+  end
+end
+
+YARD::Registry.load
+$object = YARD::Registry.at('YARD::Generators::Base#G')
+
+puts "regex:  " + format_args_regex($object)
+puts "params: " + format_args_parameters($object)
+puts
+
+TIMES = 100_000
+Benchmark.bmbm do |x|
+  x.report("regex")      { TIMES.times { format_args_regex($object) } }
+  x.report("parameters") { TIMES.times { format_args_parameters($object) } }
+end
+
+=begin LAST RUN Jun 23 2008
+regex:  (generator, opts = {})
+params: (generator, opts = {})
+
+Rehearsal ----------------------------------------------
+regex        1.270000   0.020000   1.290000 (  1.294558)
+parameters   0.690000   0.000000   0.690000 (  0.693324)
+------------------------------------- total: 1.980000sec
+
+                 user     system      total        real
+regex        1.260000   0.010000   1.270000 (  1.268214)
+parameters   0.670000   0.000000   0.670000 (  0.679114)
+=end

data/benchmarks/parsing.rb

@@ -1,8 +1,20 @@
 require "benchmark"
 require 'lib/yard'
 
+PATH_ORDER = [
+  'lib/yard/autoload.rb',
+  'lib/yard/code_objects/base.rb',
+  'lib/yard/code_objects/namespace_object.rb',
+  'lib/yard/handlers/base.rb',
+  'lib/yard/generators/helpers/*.rb',
+  'lib/yard/generators/base.rb',
+  'lib/yard/generators/method_listing_generator.rb',
+  'lib/yard/serializers/base.rb',
+  'lib/**/*.rb'
+]
+
 Benchmark.bmbm do |x|
-  x.report("parse in order") { YARD::Registry.clear; YARD.parse YARD::PATH_ORDER, 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
 

data/benchmarks/rdoc_vs_yardoc.rb

@@ -0,0 +1,10 @@
+require "benchmark"
+
+files = Dir.glob(File.dirname(__FILE__) + '/../lib/**/*.rb').join(" ")
+Benchmark.bmbm do |x|
+  x.report("rdoc") { `rm -rf rdoc && rdoc -q -o rdoc #{files} && rm -rf rdoc` }
+  x.report("yardoc") { `rm -rf yard && ./bin/yardoc -q -o yard #{files} && rm -rf yard` }
+  x.report("yardoc-cached") { `rm -rf yard && ./bin/yardoc -c -q -o yard #{files} && rm -rf yard` }
+  x.report("yardoc-legacy") { `rm -rf yard && ./bin/yardoc --legacy -q -o yard #{files} && rm -rf yard` }
+  x.report("yardoc-legacy-cached") { `rm -rf yard && ./bin/yardoc --legacy -c -q -o yard #{files} && rm -rf yard` }
+end

data/benchmarks/ripper_parser.rb

@@ -0,0 +1,12 @@
+# encoding: utf-8
+require 'benchmark'
+require File.dirname(__FILE__) + '/../lib/yard'
+
+$files = Dir[File.dirname(__FILE__) + '/../lib/**/*.rb'].map {|f| File.read(f) }
+$files_rip = Dir[File.dirname(__FILE__) + '/../lib/**/*.rb'].map {|f| [File.read(f), f] }
+
+TIMES = 2
+Benchmark.bmbm do |x|
+  x.report("rip-parser") { TIMES.times { $files_rip.each {|f| YARD::Parser::Ruby::RubyParser.parse(*f) } } }
+  x.report("yard-parser  ") { TIMES.times { $files.each {|f| YARD::Parser::Ruby::Legacy::StatementList.new(f) } } }
+end

data/docs/CODE_OBJECTS.markdown

@@ -0,0 +1,121 @@
+CodeObjects Architecture
+========================
+
+Code objects are Ruby objects that describe the code being documented. For instance,
+all classes, modules, methods, etc. are all extracted from the Ruby source as code
+objects. All of these code objects extend from the {YARD::CodeObjects::Base} class, which
+provides basic attributes like source location, source code, name and path.
+
+CodeObjects Organization
+------------------------
+
+Code objects are divided into two basic types. {YARD::CodeObjects::NamespaceObject NamespaceObjects}
+and non-namespace objects. A namespace object refers to any object in Ruby that can have
+other objects defined inside of it. In the context of Ruby, this specifically means
+modules and classes (both of which are subclasses of `NamespaceObject`). These objects
+act like tree structures, maintaining a list of all of their direct children. All non
+namespace objects are simply subclasses of the Base class. The {YARD::CodeObjects::RootObject RootObject} 
+is a special kind of `NamespaceObject` which refers to the top level namespace in Ruby.
+Methods that accept a namespace object as a parameter should also accept the symbol 
+`:root` as a shortcut for the root object.
+
+The following is an overview of the classes within the `CodeObjects` namespace:
+
+![CodeObjects Class Diagram](images/code-objects-class-diagram.png)
+
+Unique Path Representation
+--------------------------
+
+All CodeObjects are uniquely defined by their implementation of {YARD::CodeObjects::Base#path}.
+This path is used to locate or store a code object in the {YARD::Registry}. It is therefore
+essential that any Base subclass return a unique String value for #path so that the 
+object may co-exist with other objects in the Registry.
+
+In practice, a path is simply the conventional Ruby representation of a class,
+module, constant, class variable or method. For example, the following objects
+would have the following respective paths:
+
+* Class `Klass` inside module `Mod`: `Mod::Klass`
+* Instance method `bar` inside class `Foo`: `Foo#bar`
+* Class method `bar` inside class `Foo`: `Foo.bar`
+* Constant `VERSION` inside class `YARD`: `YARD::VERSION`
+* Class variable `@@abc` inside class `A`: `A::@@abc`
+
+Registry
+--------
+
+CodeObjects classes are coupled with the {YARD::Registry} class which keeps track of
+all instantiated code objects. This is an explicit design choice to allow objects
+to be fetched, cached, imported and exported from a centralized location. As mentioned
+above, this coupling is a result of the fact that each object is uniquely identified by
+its path, which is used to implement lookups. You can read more about the registry 
+in the {YARD::Registry} class.
+
+Identity Map
+------------
+
+Code objects are instantiated using an identity-map like implementation that guarantees
+only one unique Ruby object exists for an object described by a specific path. This
+allows developers to create a code object without checking if it already exists in
+the {YARD::Registry}. The following example will only create one object:
+
+    id = ClassObject.new(:root, "MyClass").object_id #=> 13352
+    ClassObject.new(:root, "MyClass").object_id #=> 13352 
+
+Proxy Objects
+-------------
+
+In addition to providing access to existing objects, a {YARD::CodeObjects::Proxy}
+class exists which can represent an object at a path that may or may not have been
+created. This is necessary to represent a reference to an object in code that is
+never defined in the same body of source code, or perhaps defined later. If any
+attributes of a proxy are accessed, it will immediately be resolved to the object
+at its declared path. In the case where such an object exists, it will act as
+a delegate to the object. However, if the object does not exist, a warning will
+be raised. Whenever arbitrary code objects are used, care should be taken in
+order to make sure attributes are not accessed on unresolvable proxies. An 
+unresolvable proxy will return a class name of `Proxy` and #type of `:proxy`, 
+for example:
+
+    P(:InvalidObject).type == :proxy  #=> true
+    P(:InvalidObject).is_a?(Proxy)    #=> true
+
+Adding Data to Code Objects
+---------------------------
+
+Code objects act as hash-like structures that allow any arbitrary value to be set.
+This allows easy extending of existing objects without creating custom subclasses.
+For instance, to add a timestamp to a method object (when it was modified, maybe),
+it is possible to simply do:
+
+    object = MethodObject.new(:root, "my_method")
+    object[:modified_at] = Time.now
+    
+This value can now be retrieved on this object both by the hash `[]` syntax as 
+well as like any other method:
+
+    object.modified_at #=> 2009-06-03 20:08:46 -0400
+
+Creating a Custom CodeObject
+----------------------------
+
+It should first be mentioned that creating a custom code object should not be
+necessary in most cases, except when functionality that cannot be represented
+by classical Ruby objects is added. A good example *might* be a test class,
+which although is technically a Ruby class, has a significantly different purpose
+in documentation and needs a different set of metadata, as well as its own
+representation in documentation.
+
+The {YARD::CodeObjects::Base#path} implementation is the most important part of the
+code object architecture. The first thing any custom code object must guarantee is
+that its path value is unique among all other objects. The recommended way to do this
+with custom objects is to add a descriptive prefix to the path. For example, the
+following is an implementation of the path for a hypothetical `FooObject`:
+
+    def path
+      "__FooPrefix" + sep + super
+    end
+
+Note that if our FooObject is a `NamespaceObject`, meaning if it can have child
+FooObjects defined inside of it, you may need to verify that the prefix is only 
+applied once.

data/docs/FAQ.markdown

@@ -0,0 +1,34 @@
+FAQ
+===
+
+(1) So, show me some cool stuff. What can YARD do?
+--------------------------------------------------
+
+- [Visualize with GraphViz][graphviz] Visualize your classes and methods with GraphViz
+- [Inline RSpecs][inline-rspecs] In your rspec files, call the following to refer 
+  back to and call the inline rspecs: `described_in_docs "String", "camelcase"`
+- [Inline doc testing][inline-doctest] Use the 'docspec' command line tool to 
+  run the above tests.  This is similar to [Ruby DocTest][rubydoctest]'s inline 
+  irb testing.
+  
+(2) Why did you pick the @-symbol tags for documentation?
+---------------------------------------------------------
+Java, C++, Python and many other languages have standard documentation tools 
+that use the @tag "standard".  This has been extended to the Ruby language, 
+and YARD takes advantage of this common style.
+
+(3) Can I tweak it to use some other documentation standard?
+------------------------------------------------------------
+  Yes. YARD is flexible enough to have other documentation syntaxes put into use. [TODO: Add information about customization here.]
+
+(4) Why don't you use ParseTree, or sydparse?  Why did you write your own parser?
+---------------------------------------------------------------------------------
+As of Ruby 1.9, YARD uses Ripper parser which is packaged with the standard library
+and maintained as such. The legacy parser is only being maintained for bug fixes, 
+but was written because no existing parser properly supported putting comments 
+into the parse tree and did not robustly support edge case scenarios.
+
+[graphviz]:http://gnuu.org/2008/02/29/generating-class-diagrams-with-yard-and-graphviz/
+[inline-rspecs]:http://github.com/lsegal/yard/tree/5b07d706eee6bc0d7f13d9ec1e6e0ab914d3679c/lib/yard/core_ext/string.rb
+[inline-doctest]:http://github.com/lsegal/yard/tree/master/lib/yard/handlers/base.rb#L350
+[rubydoctest]:http://github.com/tablatom/rubydoctest