yard 0.7.2 → 0.7.3

data/ChangeLog

@@ -1,5 +1,210 @@
+2011-10-15  Loren Segal <lsegal@soen.ca>
+
+  * ChangeLog, README.md, lib/yard.rb: Update README, ChangeLog and bump to
+  0.7.3 for release
+
+  * Rakefile: Add ruby193 to suite
+
+  * spec/config_spec.rb: Remove unnecessary file? stub, fixes JRuby spec
+
+  * lib/yard/parser/c_parser.rb, spec/parser/c_parser_spec.rb: Support
+  rb_define_attr in CRuby code  Allows for commented /* rb_define_attr */ block
+  to define an attribute silently when attribute methods are defined through
+  rb_define_method.  Closes #362
+
+  * docs/GettingStarted.md: Fix reference to changed method name in Getting
+  Started documentation
+
+2011-10-14  Loren Segal <lsegal@soen.ca>
+
+  * lib/yard/parser/ruby/ruby_parser.rb, spec/parser/ruby/ruby_parser_spec.rb:
+  Fix tokenizing of heredoc source  Closes #366
+
+  * lib/yard/code_objects/macro_object.rb: Fix escaping of {}
+
+  * lib/yard/templates/helpers/html_helper.rb,
+  spec/templates/helpers/html_helper_spec.rb: Use ! to escape {} syntax
+
+  * spec/cli/server_spec.rb, spec/handlers/constant_handler_spec.rb: Make tests
+  more Windows friendly
+
+  * lib/yard/parser/ruby/ruby_parser.rb: Fix parsing of %w{} and %w() when
+  ended by a newline
+
+  * README.md: Sentence rewording
+
+  * README.md: Get rid of those unicode characters in README
+
+  * templates/default/fulldoc/html/css/style.css,
+  templates/guide/fulldoc/html/css/style.css: Add styling for RDoc definition
+  lists (default and guide templates)  Fixes #359
+
+2011-10-14  Dirkjan Bussink <d.bussink@gmail.com>
+
+  * lib/yard/verifier.rb: Use remove_method instead of undef_method 
+  undef_method has very different semantics. It prevents the class from
+  responding to the named method. This means that also original methods on
+  super classes won't be called. This for example results in weird behavior on
+  Rubinius since the original method_missing method can't be called which
+  normally throws the NoMethodError.  Also see:
+  http://www.nach-vorne.de/2008/2/28/undef_method-remove_method/index.html
+
+2011-10-07  Loren Segal <lsegal@soen.ca>
+
+  * lib/yard/parser/ruby/ruby_parser.rb, spec/parser/ruby/ruby_parser_spec.rb:
+  Clean up array AST node handling
+
+2011-10-05  Loren Segal <lsegal@soen.ca>
+
+  * templates/default/fulldoc/html/css/full_list.css,
+  templates/default/fulldoc/html/js/full_list.js: Force items to show in list
+  search when parent lists are collapsed.  Fixes #392
+
+  * templates/default/fulldoc/html/js/full_list.js: Improve JS searching
+  capabilities by adding minimal fuzzy finding behaviour. Toggle case sensitive
+  searching when capital letters are used
+
+2011-10-04  Grégory Karékinian <greg@karekinian.com>
+
+  * docs/GettingStarted.md: Added information about escaping curly braces
+
+2011-10-01  Loren Segal <lsegal@soen.ca>
+
+  * lib/yard/parser/ruby/ruby_parser.rb, spec/parser/ruby/ruby_parser_spec.rb:
+  Fix displaying of source for unary operator nodes in the AST  Closes #371
+
+  * lib/yard/templates/helpers/markup_helper.rb: Print proper missing gem error
+  message for files with auto-detected markups that are different from default
+  markup format.  Closes #373
+
+  * lib/yard/parser/source_parser.rb: Display backtraces on parser errors in
+  debugging mode
+
+  * lib/yard/parser/ruby/ruby_parser.rb, spec/parser/ruby/ruby_parser_spec.rb:
+  Fixes "Bad value for range" error in 1.9.2-p290 and 1.9.3 when using %w{}
+  syntax (changes to ripper API).  Fixes #370
+
+2011-07-12  Tobias Koch <tobias@tobijk.de>
+
+  * lib/yard/parser/c_parser.rb: More flexible return type guessing in c-parser
+   * handle keyword (un)signed for Integers * handle class names as return
+  types * recognize C++ 'bool' * treat return types starting with 'char' as
+  String 
+
+  * lib/yard/parser/c_parser.rb: Find override comment for C constructor 
+
+2011-10-01  Loren Segal <lsegal@soen.ca>
+
+  * lib/yard/parser/ruby/ruby_parser.rb, spec/parser/ruby/ruby_parser_spec.rb:
+  Fix broken ruby parser specs
+
+2011-09-07  Loren Segal <lsegal@soen.ca>
+
+  * spec/code_objects/extra_file_object_spec.rb, spec/handlers/base_spec.rb,
+  spec/parser/source_parser_spec.rb,
+  spec/templates/helpers/html_helper_spec.rb: Fix various encoding and toplevel
+  class variable changes for 1.9.3 compatibility
+
+  * lib/yard/handlers/ruby/attribute_handler.rb,
+  lib/yard/handlers/ruby/base.rb, lib/yard/handlers/ruby/visibility_handler.rb,
+  lib/yard/parser/ruby/ast_node.rb, spec/handlers/ruby/base_spec.rb,
+  spec/parser/ruby/ast_node_spec.rb: Add support for new Ripper vcall AST node,
+  replaces var_ref for method calls  Closes #384
+
+  * lib/yard/handlers/base.rb, lib/yard/parser/source_parser.rb: LoadOrderError
+  should not stuff continuation inside of message (1.9.3 now calls to_s on
+  raise argument)
+
+  * Rakefile, lib/yard/cli/yri.rb: Remove depcrecated Config in favour of
+  RbConfig
+
+2011-08-18  Kouhei Sutou <kou@clear-code.com>
+
+  * lib/yard/templates/helpers/html_helper.rb: escape HTML meta characters in
+  text for HTML output.  Here is an example text file.  hello.txt:  Hello >_<! 
+  Here is a command to generate HTML:  % yardoc - hello.txt  It generates the
+  following HTML:  ... ...<pre>Hello >_<!</pre>... ...  We should escape ">",
+  "<" and so on in text to output valid HTML.
+
+2011-08-14  Loren Segal <lsegal@soen.ca>
+
+  * spec/templates/examples/method001.html: Fix broken spec from incomplete
+  merge on #372
+
+2011-08-07  Kouhei Sutou <kou@clear-code.com>
+
+  * templates/default/tags/html/option.erb: fix wrong close tag.
+
+2011-07-01  Rob Gleeson <rob@flowof.info>
+
+  * lib/yard/templates/helpers/html_helper.rb: Add support for GitHub
+  codeblocks when using RedCarpet.
+
+2011-07-07  Kouhei Sutou <kou@clear-code.com>
+
+  * .../default/fulldoc/html/full_list_methods.erb: [template][html] add
+  missing escape in object link label.  This problem can be reproducable by the
+  following steps:  1. Create the following script:  class Array def &(other)
+  end end  2. Genreate documents from the above script:  % yardoc array-amp.rb 
+  3. Find link markup in method_list.html:  % grep '#&' method_list.html <span
+  class='object_link'><a href="Array.html#%26-instance_method" title="Array#&
+  (method)">#&</a></span>  '>#&</a' should be '>#&amp;</a'.
+
+  * lib/yard/templates/helpers/html_helper.rb,
+  spec/templates/helpers/html_helper_spec.rb: [html] fix missing escape in
+  title.
+
+2011-06-22  Loren Segal <lsegal@soen.ca>
+
+  * lib/yard/handlers/ruby/exception_handler.rb,
+  lib/yard/handlers/ruby/legacy/exception_handler.rb,
+  spec/handlers/exception_handler_spec.rb: Ignore empty raise calls instead. It
+  is too ambiguous for YARD to guess at
+
+  * spec/parser/c_parser_spec.rb: Fix C parser spec
+
+  * lib/yard/parser/c_parser.rb, spec/parser/c_parser_spec.rb: Handle proper
+  filenames in C parser /* in FILE */ declarations  Closes #358
+
+  * spec/parser/c_parser_spec.rb: Refactor C parser specs
+
+2011-06-20  Sven Fuchs <svenfuchs@artweb-design.de>
+
+  * .travis.yml: Don't use bundler_args: --local in .travis.yml  This setting
+  only works on the current production worker because the gems all happen to be
+  installed already. The new worker setup will rollback changes after every
+  install and so tests will always fail with this setting.
+
+2011-06-19  Loren Segal <lsegal@soen.ca>
+
+  * lib/yard/rubygems/specification.rb: Support RubyGems 1.8.x in
+  rubygems_plugin.rb
+
+2011-06-15  Loren Segal <lsegal@soen.ca>
+
+  * lib/yard/handlers/ruby/exception_handler.rb,
+  lib/yard/handlers/ruby/legacy/exception_handler.rb,
+  .../handlers/examples/exception_handler_001.rb.txt,
+  spec/handlers/exception_handler_spec.rb: Handle empty raise statements as
+  raising Exception  Closes #356
+
 2011-06-14  Loren Segal <lsegal@soen.ca>
 
+  * README.md: Point contributors section to github's contributors page (easier
+  maintenance)
+
+  * .travis.yml: Only test for 1.8.6, 1.8.7 and ree on travis-ci.org
+
+  * .travis.yml: One more update for Travis CI
+
+  * Rakefile: Fix travis_ci task status exiting and legacy mode
+
+  * Gemfile: Remove ripper from Gemfile temporarily
+
+  * .travis.yml, Rakefile, spec/cli/yri_spec.rb: Add support for travis-ci.org
+
+  * Gemfile: Fix Gemfile to add ripper/rubygems sources
+
   * ChangeLog, README.md, lib/yard.rb: 0.7.2 release
 
   * lib/yard/templates/helpers/html_helper.rb,

data/README.md

@@ -8,43 +8,43 @@ YARD: Yay! A Ruby Documentation Tool
 **Contributors**: See Contributors section below    
 **Copyright**:    2007-2011    
 **License**:      MIT License    
-**Latest Version**: 0.7.2 (codename "Heroes")    
-**Release Date**: June 14th 2011    
+**Latest Version**: 0.7.3 (codename "Rhombus")    
+**Release Date**: October 15th 2011    
 
 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

+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

+**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 
+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
+consistently) organized
 during the output generation phase. You can find a list
 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

-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:

+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 method documented with YARD formatting:

 
      # Reverses the contents of a String or IO object. 
      # 
@@ -56,16 +56,16 @@ following Yardoc'd method:
      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.

+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**: YARD is designed to be 
 extended and customized by plugins. Take for instance the scenario where you 
-need to document the following code:

+need to document the following code:

    
     class List
       # Sets the publisher name for the list.
@@ -73,27 +73,27 @@ need to document the following code:
     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

+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 handle the `cattr_accessor` construct and automatically create
-an attribute on the class with the associated documentation. This makes

+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.

+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

-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

+**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

+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.

+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
@@ -289,6 +289,12 @@ More options can be seen by typing `yard-graph --help`, but here is an example:
 Changelog
 ---------
 
+- **October.15.11**: 0.7.3 release
+    - Improve support for parsing under Ruby 1.9.2p290 and 1.9.3 (#365, #370)
+    - Add support for SWIG generated CRuby code (#369)
+    - Add support for `rb_define_attr` calls in CRuby code (#362)
+    - Handle file pointers in CRuby code (#358)
+
 - **June.14.11**: 0.7.2 release
     - Fix `yard --help` not showing proper output
     - YARD now expands path to `.yardoc` file in daemon mode for server (#328)
@@ -482,37 +488,10 @@ Changelog
 Contributors
 ------------
 
-Special thanks to the following people for submitting patches:
-
-* Nathan Weizenbaum
-* Nick Plante
-* Michael Edgar
-* Sam Rawlins
-* Yehuda Katz
-* Duane Johnson
-* Hal Brodigan
-* Edward Muller
-* Pieter van de Bruggen
-* Leonid Borisenko
-* Arthur Schreiber
-* Robert Wahler
-* Mark Evans
-* Lee Jarvis
-* Franklin Webber
-* Dominik Honnef
-* David Turnbull
-* Bob Aman
-* Anthony Thibault
-* Philip Roberts
-* Jeff Rafter
-* Elliottcable
-* James Rosen
-* Jake Kerr
-* Gioele Barabucci
-* Gabriel Horner
-* Denis Defreyne
-* Benjamin Bock
-* Aman Gupta
+Special thanks to all contributors for submitting patches. A full list of
+contributors including their patches can be found at: 
+
+http://github.com/lsegal/yard/contributors
 
 Copyright
 ---------

data/Rakefile

@@ -3,7 +3,7 @@ require File.dirname(__FILE__) + '/lib/yard/rubygems/specification'
 require 'rbconfig'
 
 YARD::VERSION.replace(ENV['YARD_VERSION']) if ENV['YARD_VERSION']
-WINDOWS = (Config::CONFIG['host_os'] =~ /mingw|win32|cygwin/ ? true : false) rescue false
+WINDOWS = (RbConfig::CONFIG['host_os'] =~ /mingw|win32|cygwin/ ? true : false) rescue false
 SUDO = WINDOWS ? '' : 'sudo'
 
 task :default => :specs
@@ -20,7 +20,7 @@ end
 
 desc 'Run spec suite'
 task :suite do
-  ['ruby186', 'ruby18', 'ruby19', 'ruby192', 'jruby'].each do |ruby|
+  ['ruby186', 'ruby18', 'ruby19', 'ruby192', 'ruby193', 'jruby'].each do |ruby|
     2.times do |legacy|
       next if legacy == 1 && ruby =~ /^jruby|186/
       puts "Running specs with #{ruby}#{legacy == 1 ? ' (in legacy mode)' : ''}"
@@ -31,6 +31,21 @@ task :suite do
   end
 end
 
+task :travis_ci do
+  status = 0
+  ENV['SUITE'] = '1'
+  ENV['CI'] = '1'
+  system "bundle exec rake specs"
+  status = 1 if $?.to_i != 0
+  if RUBY_VERSION >= '1.9' && RUBY_PLATFORM != 'java'
+    puts ""
+    puts "Running specs with in legacy mode"
+    system "bundle exec rake specs LEGACY=1"
+    status = 1 if $?.to_i != 0
+  end
+  exit(status)
+end
+
 begin
   hide = '_spec\.rb$,spec_helper\.rb$,ruby_lex\.rb$,autoload\.rb$'
   if YARD::Parser::SourceParser.parser_type == :ruby

data/docs/GettingStarted.md

@@ -23,7 +23,7 @@ to express small bits of information in a structured and formal manner. While
 RDoc syntax expects you to describe your method in a completely free-form
 manner, YARD recommends declaring your parameters, return types, etc. with
 the `@tag` syntax, which makes outputting the documentation more consistent
-and easier to read. Consider the RDoc documentation for a method reverse:
+and easier to read. Consider the RDoc documentation for a method to_format:
 
     # Converts the object into textual markup given a specific `format` 
     # (defaults to `:html`)
@@ -324,7 +324,11 @@ the link syntax in this tag:
 
     # @see #methodname   <- Correct.
     # @see {#methodname} <- Incorrect.
-    
+
+If you want to use a Hash, prefix the first { with "!":
+
+   # !{ :some_key => 'value' }
+
 ### Linking URLs `{http://...}`
 
 URLs are also linked using this `{...}` syntax: