yard 0.5.8 → 0.6.0

data/README.md

@@ -8,8 +8,8 @@ YARD: Yay! A Ruby Documentation Tool
 **Contributors**: See Contributors section below    
 **Copyright**:    2007-2010    
 **License**:      MIT License    
-**Latest Version**: 0.5.8 (codename "The Longest")    
-**Release Date**: June 22nd 2010    
+**Latest Version**: 0.6.0 (codename "The Cubic")    
+**Release Date**: August 29th 2010    
 
 Synopsis
 --------
@@ -37,7 +37,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:Tags.md#taglist Tags.md} file.
+of tags in the {file:docs/Tags.md#taglist Tags.md} file.
 
 YARD also supports an optional "types" declarations for certain tags.

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

@@ -63,26 +63,26 @@ 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:

+**3. Custom Constructs and Extensibility of YARD**: YARD is designed to example:
be 
+extended and customized by plugins. Take for instance the scenario where you 
+need to document the following code:

    
-    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"
+    class List
+      # Sets the publisher name for the list.
+      cattr_accessor :publisher
     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

+the developer to handle the `cattr_accessor` construct and automatically the required
create
+an attribute on the class with the associated documentation. This makes

 documenting external API's, especially dynamic ones, a lot more consistent for
 consumption by the users.

+
+YARD is also designed for extensibility everywhere else, allowing you to add
+support for new programming languages, new data structures and even where/how
+data is stored.
                                                                               
 **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

@@ -95,6 +95,13 @@ 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.

 
+**5. Local Documentation Server**: YARD can serve documentation for projects
+or installed gems (similar to `gem server`) with the added benefit of dynamic
+searching, as well as live reloading. Using the live reload feature, you can
+document your code and immediately preview the results by refreshing the page; 
+YARD will do all the work in re-generating the HTML. This makes writing 
+documentation a much faster process.
+
 
 Installing
 ----------
@@ -119,21 +126,32 @@ 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.
+second is the Rake task. 
+
+**1. yard Command-line Tool**
+
+YARD comes packaged with a executable named `yard` which can control the many
+functions of YARD, including generating documentation, graphs running the
+YARD server, and so on. To view a list of available YARD commands, type:
+
+    $ yard --help
+    
+Plugins can also add commands to the `yard` executable to provide extra
+functionality.
+
+#### Generating Documentation
 
-**1. yardoc Command-line Tool**
+<span class="note">The `yardoc` executable is a shortcut for `yard doc`.</span>
 
-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
+The most common command you will probably use is `yard doc`, or `yardoc`. 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) 
@@ -164,7 +182,7 @@ 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>
+#### Queries
 
 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
@@ -220,12 +238,40 @@ separator. Only modules, classes and constants should use "::".
 You can also do lookups on any installed gems. Just make sure to build the
 .yardoc databases for installed gems with:
 
-    $ sudo yardoc --build-gems
+    $ sudo yard gems
     
 If you don't have sudo access, it will write these files to your `~/.yard`
 directory. `yri` will also cache lookups there.
 
-**4. `yard-graph` Graphviz Generator**
+**4. `yard server` Documentation Server**
+
+The `yard server` command serves documentation for a local project or all installed
+RubyGems. To serve documentation for a project you are working on, simply run:
+
+    $ yard server
+    
+And the project inside the current directory will be parsed (if the source has
+not yet been scanned by YARD) and served at [http://localhost:8808](http://localhost:8808).
+
+#### Live Reloading
+
+If you want to serve documentation on a project while you document it so that
+you can preview the results, simply pass `--reload` (`-r`) to the above command
+and YARD will reload any changed files on each request. This will allow you to
+change any documentation in the source and refresh to see the new contents.
+
+#### Serving Gems
+
+To serve documentation for all installed gems, call:
+
+    $ yard server --gems
+    
+This will also automatically build documentation for any gems that have not
+been previously scanned. Note that in this case there will be a slight delay
+between the first request of a newly parsed gem.
+
+
+**5. `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
@@ -236,12 +282,25 @@ option to show mixin inclusions. You can output to stdout or a file, or pipe dir
 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
+    $ yard graph --protected --full --dependencies
 
 
 Changelog
 ---------
 
+- **August.28.10**: 0.6.0 release
+    - Added dynamic local documentation server
+    - Added @group/@endgroup declarations to organize methods into groups
+    - Added `yard` executable to serve as main CLI tool with pluggable commands
+    - Added `--asset` switch to `yardoc` to copy files/dirs to output dir
+    - Added ability to register/manipulate tags via CLI (`--tag`, etc.)
+    - Added `yard diff` command
+    - Added statistics to `yardoc` output (and `yard stats` command)
+    - Added Javascript generated Table of Contents to file pages
+    - Updated various APIs
+    - Removed `yard-graph` executable
+    - See more changes in the {file:docs/WhatsNew.md what's new document}
+
 - **June.22.10**: 0.5.8 release
     - Merge fix from 0.6 branch for --no-private visibility checking
 
@@ -254,7 +313,7 @@ Changelog
 
 - **June.12.10**: 0.5.6 release
     - Bug fixes for RubyGems plugin, `has_rdoc=false` should now work
-    - New API for registering custom parsers. See {file:WhatsNew.md}
+    - New API for registering custom parsers. See {file:docs/WhatsNew.md}
 
 - **May.22.10**: 0.5.5 release
     - Various bug fixes
@@ -281,7 +340,7 @@ Changelog
     - Added plugin support
     - New `@abstract` and `@private` tags
     - Changed default rake task to `rake yard`
-    - Read about changes in {file:WhatsNew.md}
+    - Read about changes in {file:docs/WhatsNew.md}
 
 - **August.13.09**: 0.2.3.5 release
     - Minor bug fixes.
@@ -310,7 +369,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.md} file for a 
+- **Jun.07.09**: 0.2.3 release. See the {file:docs/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 
@@ -330,20 +389,22 @@ Contributors
 
 Special thanks to the following people for submitting patches:
 
-* Aman Gupta
-* Benjamin Bock
-* Denis Defreyne
+* Nathan Weizenbaum
+* Nick Plante
+* Michael Edgar
+* Yehuda Katz
 * Duane Johnson
+* Postmodern
+* Pieter van de Bruggen
+* Leonid Borisenko
+* Jeff Rafter
 * Elliottcable
 * James Rosen
-* Jeff Rafter
-* Leonid Borisenko
-* Loren Segal
-* Michael Edgar
-* Nathan Weizenbaum
-* Postmodern
-* Yehuda Katz
-
+* Jake Kerr
+* Gabriel Horner
+* Denis Defreyne
+* Benjamin Bock
+* Aman Gupta
 
 Copyright
 ---------

data/Rakefile

@@ -1,6 +1,7 @@
 require File.dirname(__FILE__) + '/lib/yard'
 require 'rbconfig'
 
+YARD::VERSION.replace(ENV['YARD_VERSION']) if ENV['YARD_VERSION']
 WINDOWS = (Config::CONFIG['host_os'] =~ /mingw|win32|cygwin/ ? true : false) rescue false
 SUDO = WINDOWS ? '' : 'sudo'
 
@@ -8,7 +9,8 @@ task :default => :specs
 
 desc "Builds the gem"
 task :gem do
-  sh "gem build yard.gemspec"
+  load 'yard.gemspec'
+  Gem::Builder.new(SPEC).build
 end
 
 desc "Installs the gem"
@@ -42,5 +44,4 @@ end
 
 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/parsing.rb

@@ -1,5 +1,6 @@
 require "benchmark"
-require 'lib/yard'
+require 'yard'
+require 'logger'
 
 PATH_ORDER = [
   'lib/yard/autoload.rb',

data/bin/yard

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

data/bin/yard-graph

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

data/bin/yard-server

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

data/docs/GettingStarted.md

@@ -113,7 +113,7 @@ Symbols:
 List of Tags
 ------------
     
-A list of tags can be found in {file:Tags.md#taglist}
+A list of tags can be found in {file:docs/Tags.md#taglist}
         
 Other Extended Syntax
 ---------------------
@@ -123,7 +123,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.md#reftags Tags} file.
+syntax is found in the {file:docs/Tags.md#reftags Tags} file.
 
 **Inter-Document Links**
 
@@ -152,22 +152,22 @@ 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.md} document.
+found in the {file:docs/Overview.md} document.
 
-For information on adding support for Ruby DSLs, see the {file:Handlers.md}
-and {file:Parser.md} architecture documents.
+For information on adding support for Ruby DSLs, see the {file:docs/Handlers.md}
+and {file:docs/Parser.md} architecture documents.
 
-For information on adding extra tags, see {file:Tags.md}.
+For information on adding extra tags, see {file:docs/Tags.md}.
 
 For information on accessing the data YARD stores about your documentation,
-look at the {file:CodeObjects.md} architecture document.
+look at the {file:docs/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:Templates.md} architecture
+information after extending it. The {file:docs/Templates.md} architecture
 document covers the basics of how YARD's templating system works.
 
 <a name="plugins"></a>

data/docs/Handlers.md

@@ -4,14 +4,14 @@ Handlers Architecture
 Handlers allow the processing of parsed source code. Handling is done after
 parsing to abstract away the implementation details of lexical and semantic
 analysis on source and to only deal with the logic regarding recognizing
-source statements as {file:CodeObjects.md code objects}.
+source statements as {file:docs/CodeObjects.md code objects}.
 
 ![Handlers Architecture Class Diagram](images/handlers-class-diagram.png)
 
 The Pipeline
 ------------
 
-After the {file:Parser.md parser component} finishes analyzing the
+After the {file:docs/Parser.md parser component} finishes analyzing the
 source, it is handed off for post-processing to the {YARD::Handlers::Processor}
 class, which is responsible for traversing the set of statements given by
 the parser and delegating them to matching handlers. Handlers match when the
@@ -51,7 +51,7 @@ class method. A very simple handler that handles a module definition would be:
     end
     
 For details on what nodes are, and what node types are, see the 
-{file:Parser.md parser architecture document}.
+{file:docs/Parser.md parser architecture document}.
 
 In this case the node type being handled is the `:module` type. More than one
 node type or `handles` declarations may describe a single handler, for instance,
@@ -89,7 +89,7 @@ Creating a new Code Object
 --------------------------
 
 Usually (but not always) handling is performed to create new code objects to add
-to the registry (for information about code objects, see {file:CodeObjects.md this document}).
+to the registry (for information about code objects, see {file:docs/CodeObjects.md this document}).
 Code objects should simply be created and added to the existing `namespace`. This
 will be enough to add them to the registry. There is also a convenience 
 {YARD::Handlers::Base#register register} method which quickly sets standard attributed
@@ -132,7 +132,7 @@ Because the legacy handler uses the legacy parser and therefore a different kind
 of AST, there are subtle differences in the handler API. Most importantly, the
 `handles` method usually deals with either lexical tokens or source code as a string
 or RegExp object. The statement object, similarly, is made up of lexical tokens instead
-of semantically parsed nodes (this is described in the {file:Parser.md parser document}). 
+of semantically parsed nodes (this is described in the {file:docs/Parser.md parser document}). 
 
 The module example above can be rewritten as a legacy handler as follows:
 

data/docs/Overview.md

@@ -30,10 +30,10 @@ This component is made up of four sub-components, each of which have separate
 tasks during the data gathering process (*note: the tag architecture is not*
 *shown in the class diagram*). These sub-components are:
 
-  * {file:Parser.md Parser Architecture}
-  * {file:Handlers.md Handler Architecture}
-  * {file:CodeObjects.md Code Object Architecture}
-  * {file:Tags.md Tag Architecture}
+  * {file:docs/Parser.md Parser Architecture}
+  * {file:docs/Handlers.md Handler Architecture}
+  * {file:docs/CodeObjects.md Code Object Architecture}
+  * {file:docs/Tags.md Tag Architecture}
 
 The parser component reads source files and converts it into a set of statements
 which the handlers then process, creating code objects which in turn create tags 
@@ -57,4 +57,4 @@ Post Processing & Templating System
 This component handles processing of objects from the registry through a templating
 engine that allows output to a variety of formats. Practically speaking, this is
 where templates can be implemented to change the design, output or structure of
-the data. See {file:Templates.md Templates Architecture} for a complete overview.
+the data. See {file:docs/Templates.md Templates Architecture} for a complete overview.

data/docs/Parser.md

@@ -3,7 +3,7 @@ Parser Architecture
 
 The parser component of YARD is the first component in the data processing pipeline
 that runs before any handling is done on the source. The parser is meant to translate
-the source into a set of statements that can be understood by the {file:Handlers.md Handlers}
+the source into a set of statements that can be understood by the {file:docs/Handlers.md Handlers}
 that run immediately afterwards.
 
 The important classes are described in the class diagram of the entire parser 

data/docs/Tags.md

@@ -259,7 +259,7 @@ Programmatic API
 Accessing Tag Information
 -------------------------
 
-Tag metadata is added when a {YARD::Docstring} is added to a {file:CodeObjects.md code object}
+Tag metadata is added when a {YARD::Docstring} is added to a {file:docs/CodeObjects.md code object}
 using the {YARD::CodeObjects::Base#docstring=} attribute. In addition to adding
 conventional comments, tags are parsed and associated with the object. The easiest
 way to access tags on an object is to use the {YARD::CodeObjects::Base#tag} and `#tags`

data/docs/Templates.md

@@ -223,8 +223,8 @@ For instance, the first line in `default/class/html/setup.rb` is:
 This includes the 'default/module/html', which means it also includes 'default/module'
 by extension. This allows class to make use of any of module's erb files.
 
-Inserting Sections
-------------------
+Inserting and Traversing Sections
+---------------------------------
 
 The ability to insert sections was mentioned above. The class template, for
 instance, will modify the #init method to insert class specific sections:
@@ -238,10 +238,31 @@ instance, will modify the #init method to insert class specific sections:
     
 Observe how sections has been modified after the super method was called (the
 super method would have been defined in `default/module/setup.rb`). The
-custom method {Array#place} is added by YARD to allow sections to be inserted
-before or after another section by it's given name rather than index. This
-allows the overriding of templates in a way that does not depend on where
-the section is located (since it may have been overriden by another module).
+`sections` object is of the {YARD::Templates::Section} class and allows sections to be inserted
+before or after another section using {Array#place} by it's given name rather 
+than index. This allows the overriding of templates in a way that does not
+depend on where the section is located (since it may have been overriden by 
+another module).
+
+You can also use `sections[:name]` to find the first child section named `:name`.
+For instance, with the following sections declaration:
+
+    sections :a, [:b, :c, [:d]]
+    
+You can get to the :d section with:
+
+    sections[:a][:c][:d]
+    
+You can use this to insert a section inside a nested set without using indexed
+access. The following command would result in `[:a, [:b, :c, [:d, :e]]]`:
+
+    sections[:a][:c].place(:e).after(:d)
+    
+There are also two methods, {Insertion#before_any} and {Insertion#after_any},
+which allow you to insert sections before or after the first matching section name
+recursively. The above example could simply be rewritten as:
+
+    sections.place(:e).after_any(:d)
 
 Overriding Templates by Registering a Template Path
 ---------------------------------------------------