yard 0.6.3 → 0.6.4

data/ChangeLog

@@ -1,3 +1,109 @@
+2010-12-21  Loren Segal <lsegal@soen.ca>
+
+  * ChangeLog, README.md, lib/yard.rb, yard.gemspec: Bump to version 0.6.4
+
+  * spec/server/rack_adapter_spec.rb: Fix RackMiddleware tests for 1.8.x
+
+  * lib/yard/server/commands/base.rb,
+  lib/yard/server/commands/library_command.rb: Move #render back to
+  Commands::Base, since another class depends on it
+
+  * lib/yard/autoload.rb, lib/yard/server/adapter.rb,
+  lib/yard/server/commands/base.rb,
+  lib/yard/server/commands/display_file_command.rb,
+  lib/yard/server/commands/display_object_command.rb,
+  lib/yard/server/commands/frames_command.rb,
+  lib/yard/server/commands/library_command.rb,
+  lib/yard/server/commands/list_command.rb,
+  lib/yard/server/doc_server_helper.rb,
+  lib/yard/server/doc_server_serializer.rb, lib/yard/server/library_version.rb,
+  lib/yard/server/rack_adapter.rb, lib/yard/server/router.rb,
+  lib/yard/server/static_caching.rb, lib/yard/server/webrick_adapter.rb: Beef
+  up YARD::Server* documentation
+
+2010-12-20  Loren Segal <lsegal@soen.ca>
+
+  * docs/GettingStarted.md: Extra information about type specifications, fix
+  tools section
+
+  * docs/GettingStarted.md: Improve getting started documentation, add more
+  syntax documentation
+
+  * lib/yard/code_objects/base.rb, lib/yard/code_objects/method_object.rb,
+  lib/yard/code_objects/root_object.rb: Cache CodeObjects::Base#path to
+  significantly improve performance
+
+  * lib/yard/templates/engine.rb: Fix broken documentation reference
+
+2010-12-19  Loren Segal <lsegal@soen.ca>
+
+  * lib/yard/parser/ruby/ruby_parser.rb,
+  spec/parser/ruby/legacy/statement_list_spec.rb,
+  spec/parser/ruby/ruby_parser_spec.rb: Fix ordering of heredoc tokens  Closes
+  gh-209
+
+  * lib/yard/parser/ruby/ruby_parser.rb, spec/parser/ruby/ruby_parser_spec.rb:
+  Fix listing of heredoc source in 1.9.x
+
+  * lib/yard/parser/ruby/ast_node.rb, lib/yard/parser/ruby/ruby_parser.rb,
+  spec/handlers/class_handler_spec.rb,
+  spec/handlers/examples/class_handler_001.rb.txt,
+  spec/parser/ruby/ruby_parser_spec.rb: Fix Derived < ::Base inheriting wrong
+  Base (not top level)  Closes gh-216
+
+2010-12-17  Loren Segal <lsegal@soen.ca>
+
+  * Rakefile, spec/spec_helper.rb, spec/templates/helpers/html_helper_spec.rb,
+  spec/templates/module_spec.rb: Make rakefile backwards compatible for rspec
+  1.x users
+
+  * Rakefile, spec/cli/diff_spec.rb, spec/cli/stats_spec.rb,
+  spec/cli/yardoc_spec.rb, spec/templates/engine_spec.rb: Add compatibility
+  with rspec2
+
+2010-12-15  Loren Segal <lsegal@soen.ca>
+
+  * spec/templates/spec_helper.rb: Can't use example() with rspec2
+
+2010-12-12  Gioele Barabucci <gioele@svario.it>
+
+  * Rakefile, spec/spec_helper.rb: Minimal update to RSpec 2
+
+2010-12-15  Loren Segal <lsegal@soen.ca>
+
+  * spec/cli/yri_spec.rb: Add sanity check tests to YRI specs
+
+2010-12-15  Lee Jarvis <lee@jarvis.co>
+
+  * lib/yard/cli/yri.rb: prepend :: to adhere to rubys class lookup rules for
+  Config::CONFIG
+
+2010-11-24  Loren Segal <lsegal@soen.ca>
+
+  * lib/yard/templates/helpers/markup_helper.rb,
+  spec/templates/helpers/markup_helper_spec.rb: Fix automatic loading of markup
+  providers by properly caching provider information.  Closes gh-206
+
+  * lib/yard/templates/helpers/markup_helper.rb,
+  spec/templates/helpers/markup_helper_spec.rb: Initial fix for automatic
+  markup provider searching
+
+2010-11-21  Loren Segal <lsegal@soen.ca>
+
+  * lib/yard/server/rack_adapter.rb, spec/server/rack_adapter_spec.rb:
+  RackMiddleware should now pass 404 responses up to the next middleware in the
+  stack
+
+2010-11-21  srawlins <sam.rawlins@gmail.com>
+
+  * templates/default/fulldoc/html/css/style.css: Typos. Tested. Now this patch
+  looks goooood.
+
+  * spec/parser/c_parser_spec.rb: Fixed newline
+
+  * templates/default/fulldoc/html/css/style.css: Fixed wrapping in Firefox,
+  clipping in Chrome
+
 2010-11-21  Loren Segal <lsegal@soen.ca>
 
   * ChangeLog, README.md, lib/yard.rb, yard.gemspec: Bump to version 0.6.3
@@ -6,6 +112,13 @@
   spec/templates/helpers/markup_helper_spec.rb: Fix regression where markup
   loading fails when generating HTML
 
+2010-11-17  Franklin Webber <franklin.webber@gmail.com>
+
+  * templates/default/fulldoc/html/js/app.js: Minor Javascript Fix - Keyboard
+  Shortcuts  List link shortcuts checked to see if the original Target of the
+  event was a INPUT or TEXTARA.  However, if the orignal Target was undefined
+  an error was raised.  Checking for undefined.
+
 2010-11-15  Loren Segal <lsegal@soen.ca>
 
   * ChangeLog, README.md, lib/yard.rb, yard.gemspec: Bump to version 0.6.2
@@ -266,6 +379,12 @@
   * lib/yard/cli/gems.rb: Replace #each_slice with 1.8.6 compatible iteration. 
   Closes gh-178
 
+2010-09-27  srawlins <sam.rawlins@gmail.com>
+
+  * lib/yard/parser/c_parser.rb, spec/parser/c_parser_spec.rb,
+  spec/parser/examples/override.c.txt: Added
+  Parser::CParser#find_override_comment, almost straight from RDoc
+
 2010-09-25  Loren Segal <lsegal@soen.ca>
 
   * .../ruby/legacy/class_condition_handler.rb,

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.6.3 (codename "Better White Picket Fences")    
-**Release Date**: November 21st 2010    
+**Latest Version**: 0.6.4 (codename "Snowy White Picket Fences")    
+**Release Date**: December 21st 2010    
 
 Synopsis
 --------
@@ -289,6 +289,17 @@ More options can be seen by typing `yard-graph --help`, but here is an example:
 Changelog
 ---------
 
+- **December.21.10**: 0.6.4 release
+    - Fix yri tool crashing with new Config class (gh-217)
+    - Fix support for ::TopLevelConstants (gh-216)
+    - YARD's test suite is now RSpec2 compatible (gh-215)
+    - Improved documentation for YARD::Server features (gh-207)
+    - Fix displaying of collaped method summary lists (gh-204)
+    - Fix automatic loading of markup providers (gh-206)
+    - Fix keyboard shortcuts for Chrome (gh-203)
+    - Disallow `extend self` inside of a class (gh-202)
+    - Constants now recognized in C extensions (gh-201)
+
 - **November.21.10**: 0.6.3 release
     - Fixed regression that caused `yardoc --markup` to silently exit
 
@@ -428,6 +439,8 @@ Special thanks to the following people for submitting patches:
 * Arthur Schreiber
 * Robert Wahler
 * Mark Evans
+* Lee Jarvis
+* Franklin Webber
 * David Turnbull
 * Anthony Thibault
 * Sam Rawlins
@@ -435,6 +448,7 @@ Special thanks to the following people for submitting patches:
 * Elliottcable
 * James Rosen
 * Jake Kerr
+* Gioele Barabucci
 * Gabriel Horner
 * Denis Defreyne
 * Benjamin Bock

data/Rakefile

@@ -19,27 +19,46 @@ task :install => :gem do
 end
 
 begin
-  require 'spec'
-  require 'spec/rake/spectask'
+  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
+
+  require 'rspec'
+  require 'rspec/core/rake_task'
 
   desc "Run all specs"
-  Spec::Rake::SpecTask.new("specs") do |t|
+  RSpec::Core::RakeTask.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.rspec_opts = ["--colour", "--format", "documentation"]
+    t.rspec_opts += ["--require", File.join(File.dirname(__FILE__), 'spec', 'spec_helper')]
+    t.pattern = "spec/**/*_spec.rb"
   
     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."
+  begin # Try for rspec 1.x
+    require 'spec'
+    require 'spec/rake/spectask'
+    
+    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.pattern = "spec/**/*_spec.rb"
+
+      if ENV['RCOV']
+        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
 end
 
 YARD::Rake::YardocTask.new do |t|

data/docs/GettingStarted.md

@@ -60,6 +60,17 @@ Using tags we can add semantic metadata to our code without worrying about
 presentation. YARD will handle presentation for us when we decide to generate
 documentation later.
 
+Which Markup Format?
+--------------------
+
+YARD does not impose a specific markup. The above example uses standard RDoc
+markup formatting, but YARD also supports textile and markdown via the 
+command-line switch or `.yardopts` file (see below). This means that you are
+free to use whatever formatting you like. This guide is actually written
+using markdown. YARD, however, does add a few important syntaxes that are 
+processed no matter which markup formatting you use, such as tag support 
+and inter-document linking. These syntaxes are discussed below.
+
 Adding Tags to Documentation
 ----------------------------
 
@@ -79,6 +90,64 @@ lines following a tag as part of the tag data. For example:
     #   The new method accepts the same parameters.
     def mymethod
     end
+    
+### List of Tags
+
+A list of tags can be found in {file:docs/Tags.md#taglist}    
+    
+### Reference Tags
+
+To reduce the amount of duplication in writing documentation for repetitive
+code, YARD introduces "reference tags", which are not quite tags, but not
+quite docstrings either. In a sense, they are tag (and docstring) modifiers.
+Basically, any docstring (or tag) that begins with "(see OTHEROBJECT)" will
+implicitly link the docstring or tag to the "OTHEROBJECT", copying any data
+from that docstring/tag into your current object. Consider the example:
+
+    class MyWebServer
+      # Handles a request
+      # @param [Request] request the request object
+      # @return [String] the resulting webpage
+      def get(request) "hello" end
+
+      # (see #get)
+      def post(request) "hello" end
+    end
+    
+The above `#post` method takes the docstring and all tags (`param` and `return`)
+of the `#get` method. When you generate HTML documentation, you will see this
+duplication automatically, so you don't have to manually type it out. We can
+also add our own custom docstring information below the "see" reference, and
+whatever we write will be appended to the docstring:
+
+    # (see #get)
+    # @note This method may modify our application state!
+    def post(request) self.state += 1; "hello" end
+    
+Here we added another tag, but we could have also added plain text. The
+text must be appended *after* the `(see ...)` statement, preferably on
+a separate line.
+
+Note that we don't have to "refer" the whole docstring. We can also link 
+individual tags instead. Since "get" and "post" actually have different 
+descriptions, a more accurate example would be to only refer our parameter 
+and return tags:
+
+    class MyWebServer
+      # Handles a GET request
+      # @param [Request] request the request object
+      # @return [String] the resulting webpage
+      def get(request) "hello" end
+      
+      # Handles a POST request
+      # @note This method may modify our application state!
+      # @param (see #get)
+      # @return (see #get)
+      def post(request) self.state += 1; "hello" end
+    end
+    
+The above copies all of the param and return tags from `#get`. Note that you
+cannot copy individual tags of a specific type with this syntax.
 
 Declaring Types
 ---------------
@@ -110,57 +179,139 @@ For instance, consider the following Array that holds a set of Strings and
 Symbols:
   
     # @param [Array<String, Symbol>] list the list of strings and symbols.
+    
+We mentioned that these type fields are "mostly" free-form. In truth, they
+are defined "by convention". To view samples of common type specifications
+and recommended conventions for writing type specifications, see 
+{http://yardoc.org/types.html}. Note that these conventions may change every now 
+and then, although we are working on a more "formal" type specification proposal.
+
+Inter-document Linking
+----------------------
+
+YARD supports a special syntax to link to other code objects, URLs, files,
+or embed docstrings between documents. This syntax has the general form
+of `{Name OptionalTitle}` (where `OptionalTitle` can have spaces, but `Name`
+cannot).
+
+### Linking Objects
+
+To link another "object" (class, method, module, etc.), use the format:
+
+    {ObjectName#method OPTIONAL_TITLE}
+    {Class::CONSTANT My constant's title}
+    {#method_inside_current_namespace}
+    
+Without an explicit title, YARD will use the relative path to the object as
+the link name. Note that you can also use relative paths inside the object
+path to refer to an object inside the same namespace as your current docstring.
+
+Note that the `@see` tag automatically links its data. You should not use
+the link syntax in this tag:
+
+    # @see #methodname   <- Correct.
+    # @see {#methodname} <- Incorrect.
+    
+### Linking URLs
 
-List of Tags
-------------
+URLs are also linked using this `{...}` syntax:
+
+    {http://example.com Optional Title}
+    {mailto:email@example.com}
+
+### Linking Files
+
+Files can also be linked using this same syntax but by adding the `file:`
+prefix to the object name. Files refer to extra readme files you added
+via the command-line. Consider the following examples:
+
+    {file:docs/GettingStarted.md Getting Started}
+    {file:mypage.html Name#anchor}
     
-A list of tags can be found in {file:docs/Tags.md#taglist}
-        
-Other Extended Syntax
----------------------
+As shown, you can also add an optional `#anchor` if the page is an HTML link.
+
+### Embedding Docstrings
 
-**Reference Tags**
+We saw the `(see ...)` syntax above, which allowed us to link an entire docstring
+with another. Sometimes, however, we just want to copy docstring text without
+tags. Using the same `{...}` syntax, but using the `include:` prefix, we can
+embed a docstring (minus tags) at a specific point in the text.
 
-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:docs/Tags.md#reftags Tags} file.
+    # This class is cool
+    # @abstract
+    class Foo; end
+    
+    # This is another class. {include:Foo} too!
+    class Bar; end
+    
+The docstring for Bar becomes: 
 
-**Inter-Document Links**
+    "This is another class. This class is cool too!"
 
-YARD supports a special syntax to link to other code objects or files.
-The syntax is `{ObjectName#method OPTIONAL_TITLE}`. This syntax is acceptable
-anywhere in documentation with the exception of the @see tag, which 
-automatically links its data.
+Note that this prefix currently only works for objects.
 
 <a name="using"></a>
 Using YARD to Generate Documentation
 ====================================
 
-YARD ships with a number of tools you will want to integrate into your
-development process.
+`yard` Executable
+-----------------
+
+YARD ships with a single executable aptly named `yard`. In addition to
+generating standard documentation for your project, you would use this tool 
+if you wanted to: 
+
+* Document all installed gems
+* Run a local documentation server
+* Generate UML diagrams using [Graphviz][graphviz]
+* View `ri`-style documentation
+* Diff your documentation
+* Analyze documentation statistics.
+
+The following commands are available in YARD 0.6.x (see `yard help` for a 
+full list):
 
-`yardoc`
---------
-Obviously, since YARD is a documentation tool, one of its primary goals is
-to generate documentation for a variety of formats, most commonly HTML. The
-`yardoc` tool that is installed with YARD allows you to quickly export code
-documentation to HTML document files. 
+    Usage: yard <command> [options]
+
+    Commands:
+    config   Views or edits current global configuration
+    diff     Returns the object diff of two gems or .yardoc files
+    doc      Generates documentation
+    gems     Builds YARD index for gems
+    graph    Graphs class diagram using Graphviz
+    help     Retrieves help for a command
+    ri       A tool to view documentation in the console like `ri`
+    server   Runs a local documentation server
+    stats    Prints documentation statistics on a set of files
+
+Note that `yardoc` is an alias for `yard doc`, and `yri` is an alias for
+`yard ri`. These commands are maintained for backwards compatibility.
+
+`.yardopts` Options File
+------------------------
 
-`.yardopts`
------------
 Unless your documentation is very small, you'll end up needing to run `yardoc`
 with many options.  The `yardoc` tool will use the options found in this file.
 It is recommended to check this in to your repository and distribute it with
-your source.  Options for `yardoc` are discussed in the {file:README.md README}.
-A full overview of the `.yardopts` file can be found in {YARD::CLI::Yardoc}.
-
-`yard`
-------
-The `yard` tool will interface your YARD-based documentation with other resources.
-You can use this if you want to document all installed gems, run a local
-documentation server, generate UML using [Graphviz][graphviz], view `ri`-style
-documentation, diff documentation, or analyze statistics.
+your source. This file is placed at the root of your project (in the directory
+you run `yardoc` from) and contains all of arguments you would otherwise pass
+to the command-line tool. For instance, if you often type:
+
+    yardoc --no-private --protected app/**/*.rb - README LEGAL COPYING
+    
+You can place the following into your `.yardopts`:
+
+    --no-private --protected app/**/*.rb - README LEGAL COPYING
+    
+This way, you only need to type:
+
+    yardoc
+
+Any extra switches passed to the command-line now will be appended to your
+`.yardopts` options.
+
+Note that options for `yardoc` are discussed in the {file:README.md README}, 
+and a full overview of the `.yardopts` file can be found in {YARD::CLI::Yardoc}.
 
 <a name="docing"></a>
 Configuring YARD