rspec-core 2.12.1 → 2.12.2

data/Changelog.md

@@ -1,3 +1,14 @@
+### 2.12.2 / 2012-12-13
+[full changelog](http://github.com/rspec/rspec-core/compare/v2.12.1...v2.12.2)
+
+Bug fixes
+
+* Fix `RSpec::Core::RakeTask` so that it is compatible with rake 0.8.7
+  on ruby 1.8.7. We had accidentally broke it in the 2.12 release
+  (Myron Marston).
+* Fix `RSpec::Core::RakeTask` so it is tolerant of the `Rspec` constant
+  for backwards compatibility (Patrick Van Stee)
+
 ### 2.12.1 / 2012-12-01
 [full changelog](http://github.com/rspec/rspec-core/compare/v2.12.0...v2.12.1)
 

data/lib/rspec/core/formatters/base_formatter.rb

@@ -17,6 +17,9 @@ module RSpec
         attr_reader :example_count, :pending_count, :failure_count
         attr_reader :failed_examples, :pending_examples
 
+        # @api public
+        #
+        # @param output
         def initialize(output)
           @output = output || StringIO.new
           @example_count = @pending_count = @failure_count = 0
@@ -26,9 +29,14 @@ module RSpec
           @example_group = nil
         end
 
-        # Invoked before any examples are run, right after they have all
-        # been collected. This can be useful for formatters that provide
-        # feedback on progress through a suite.
+        # @api public
+        #
+        # This method is invoked before any examples are run, right after
+        # they have all been collected. This can be useful for special
+        # formatters that need to provide progress on feedback (graphical ones).
+        #
+        # This will only be invoked once, and the next one to be invoked
+        # is {#example_group_started}.
         #
         # @param example_count
         def start(example_count)
@@ -36,28 +44,40 @@ module RSpec
           @example_count = example_count
         end
 
-        # Invoked at the beginning of the execution of each example
-        # group.
+        # @api public
+        #
+        # This method is invoked at the beginning of the execution of each example group.
         #
         # @param example_group subclass of `RSpec::Core::ExampleGroup`
+        #
+        # The next method to be invoked after this is {#example_passed},
+        # {#example_pending}, or {#example_group_finished}.
+        #
+        # @param example_group
         def example_group_started(example_group)
           @example_group = example_group
         end
 
+        # @api public
+        #
         # Invoked at the end of the execution of each example group.
         #
         # @param example_group subclass of `RSpec::Core::ExampleGroup`
         def example_group_finished(example_group)
         end
 
-
+        # @api public
+        #
         # Invoked at the beginning of the execution of each example.
         #
         # @param example instance of subclass of `RSpec::Core::ExampleGroup`
+        # @return [Array]
         def example_started(example)
           examples << example
         end
 
+        # @api public
+        #
         # Invoked when an example passes.
         #
         # @param example instance of subclass of `RSpec::Core::ExampleGroup`
@@ -67,35 +87,64 @@ module RSpec
         # Invoked when an example is pending.
         #
         # @param example instance of subclass of `RSpec::Core::ExampleGroup`
+        # @return [Array]
         def example_pending(example)
           @pending_examples << example
         end
 
+        # @api public
+        #
         # Invoked when an example fails.
         #
         # @param example instance of subclass of `RSpec::Core::ExampleGroup`
+        # @return [Array]
         def example_failed(example)
           @failed_examples << example
         end
 
+        # @api public
+        #
         # Used by the reporter to send messages to the output stream.
+        # 
         # @param [String] message
         def message(message)
         end
 
+        # @api public
+        #
         # Invoked after all examples have executed, before dumping post-run reports.
+        #
+        # @return [nil]
         def stop
         end
 
-        # Invoked after all of the examples have executed (after `stop`).
+        # @api public
+        #
+        # This method is invoked after all of the examples have executed. The next method
+        # to be invoked after this one is {#dump_failures}
+        # (BaseTextFormatter then calls {#dump_failure} once for each failed example.)
+        #
+        # @return [nil]
         def start_dump
         end
 
+        # @api public
+        #
         # Dumps detailed information about each example failure.
+        #
+        # @return [nil]
         def dump_failures
         end
 
-        # Invoked after the dumping of examples and failures.
+        # @api public
+        #
+        # This method is invoked after the dumping of examples and failures. Each parameter
+        # is assigned to a corresponding attribute.
+        #
+        # @param duration
+        # @param example_count
+        # @param failure_count
+        # @param pending_count
         def dump_summary(duration, example_count, failure_count, pending_count)
           @duration = duration
           @example_count = example_count
@@ -103,7 +152,12 @@ module RSpec
           @pending_count = pending_count
         end
 
-        # Invoked after the summary if option is set to do so.
+        # @api public
+        #
+        # Outputs a report of pending examples.  This gets invoked
+        # after the summary if option is set to do so.
+        #
+        # @return [nil]
         def dump_pending
         end
 
@@ -111,6 +165,8 @@ module RSpec
         def seed(number)
         end
 
+        # @api public
+        #
         # Invoked at the very end, `close` allows the formatter to clean
         # up resources, e.g. open streams, etc.
         def close

data/lib/rspec/core/formatters/base_text_formatter.rb

@@ -25,6 +25,12 @@ module RSpec
           end
         end
 
+        # @api public
+        #
+        # Colorizes the output red for failure, yellow for
+        # pending, and green otherwise.
+        #
+        # @param [String] string
         def colorise_summary(summary)
           if failure_count > 0
             red(summary)
@@ -44,6 +50,10 @@ module RSpec
           dump_commands_to_rerun_failed_examples
         end
 
+        # @api public
+        #
+        # Outputs commands which can be used to re-run failed examples.
+        #
         def dump_commands_to_rerun_failed_examples
           return if failed_examples.empty?
           output.puts
@@ -55,6 +65,10 @@ module RSpec
           end
         end
 
+        # @api public
+        #
+        # Outputs the 10 slowest examples in a report when using `--profile`.
+        #
         def dump_profile
           sorted_examples = examples.sort_by {|example|
             example.execution_result[:run_time] }.reverse.first(10)
@@ -73,6 +87,10 @@ module RSpec
           end
         end
 
+        # @api public
+        #
+        # Outputs summary with number of examples, failures and pending.
+        #
         def summary_line(example_count, failure_count, pending_count)
           summary = pluralize(example_count, "example")
           summary << ", " << pluralize(failure_count, "failure")

data/lib/rspec/core/formatters/helpers.rb

@@ -32,6 +32,16 @@ module RSpec
         SUB_SECOND_PRECISION = 5
         DEFAULT_PRECISION = 2
 
+        # @api private
+        #
+        # Formats seconds into a human-readable string.
+        #
+        # @param [Float, Fixnum] duration in seconds
+        # @return [String] human-readable time
+        #
+        # @example
+        #    format_duration(1) #=>  "1 minute 1 second"
+        #    format_duration(135.14) #=> "2 minutes 15.14 seconds"
         def format_duration(duration)
           if duration > 60
             minutes = duration.to_i / 60
@@ -43,17 +53,46 @@ module RSpec
           end
         end
 
+        # @api private
+        #
+        # Formats seconds to have 5 digits of precision with trailing zeros removed if the number
+        # if less than 1 or with 2 digits of precision if the number is greater than zero.
+        #
+        # @param [Float] float
+        # @return [String] formatted float
+        #
+        # @example
+        #    format_seconds(0.000006) #=> "0.00001"
+        #    format_seconds(0.020000) #=> "0.02"
+        #    format_seconds(1.00000000001) #=> "1"
+        #
+        # The precision used is set in {Helpers::SUB_SECOND_PRECISION} and {Helpers::DEFAULT_PRECISION}.
+        #
+        # @see #strip_trailing_zeroes
         def format_seconds(float)
           precision ||= (float < 1) ? SUB_SECOND_PRECISION : DEFAULT_PRECISION
           formatted = sprintf("%.#{precision}f", float)
           strip_trailing_zeroes(formatted)
         end
 
+        # @api private
+        #
+        # Remove trailing zeros from a string.
+        #
+        # @param [String] string string with trailing zeros
+        # @return [String] string with trailing zeros removed
         def strip_trailing_zeroes(string)
           stripped = string.sub(/[^1-9]+$/, '')
           stripped.empty? ? "0" : stripped
         end
 
+        # @api private
+        #
+        # Pluralize a word based on a count.
+        #
+        # @param [Fixnum] count number of objects
+        # @param [String] string word to be pluralized
+        # @return [String] pluralized word
         def pluralize(count, string)
           "#{count} #{string}#{'s' unless count.to_f == 1}"
         end

data/lib/rspec/core/formatters/snippet_extractor.rb

@@ -1,7 +1,9 @@
 module RSpec
   module Core
     module Formatters
-      # This class extracts code snippets by looking at the backtrace of the passed error
+      # @api private
+      #
+      # Extracts code snippets by looking at the backtrace of the passed error and applies synax highlighting and line numbers using html.
       class SnippetExtractor
         class NullConverter; def convert(code, pre); code; end; end
 
@@ -12,6 +14,14 @@ module RSpec
           @@converter = NullConverter.new
         end
 
+        # @api private
+        #
+        # Extract lines of code corresponding to  a backtrace.
+        #
+        # @param [String] backtrace the backtrace from a test failure
+        # @return [String] highlighted code snippet indicating where the test failure occured
+        #
+        # @see #post_process
         def snippet(backtrace)
           raw_code, line = snippet_for(backtrace[0])
           highlighted = @@converter.convert(raw_code, false)
@@ -19,6 +29,14 @@ module RSpec
           post_process(highlighted, line)
         end
 
+        # @api private
+        #
+        # Create a snippet from a line of code.
+        #
+        # @param [String] error_line file name with line number (i.e. 'foo_spec.rb:12')
+        # @return [String] lines around the target line within the file
+        #
+        # @see #lines_around
         def snippet_for(error_line)
           if error_line =~ /(.*):(\d+)/
             file = $1
@@ -29,6 +47,13 @@ module RSpec
           end
         end
 
+        # @api private
+        #
+        # Extract lines of code centered around a particular line within a source file.
+        #
+        # @param [String] file filename
+        # @param [Fixnum] line line number
+        # @return [String] lines around the target line within the file (2 above and 1 below).
         def lines_around(file, line)
           if File.file?(file)
             lines = File.read(file).split("\n")
@@ -44,6 +69,13 @@ module RSpec
           "# Couldn't get snippet for #{file}"
         end
 
+        # @api private
+        #
+        # Adds line numbers to all lines and highlights the line where the failure occurred using html `span` tags.
+        #
+        # @param [String] highlighted syntax-highlighted snippet surrounding the offending line of code
+        # @param [Fixnum] offending_line line where failure occured
+        # @return [String] completed snippet
         def post_process(highlighted, offending_line)
           new_lines = []
           highlighted.split("\n").each_with_index do |line, i|

data/lib/rspec/core/rake_task.rb

@@ -1,6 +1,8 @@
+require 'rspec/core/backward_compatibility'
 require 'rspec/core/deprecation'
 require 'rake'
 require 'rake/tasklib'
+require 'shellwords'
 
 module RSpec
   module Core
@@ -157,13 +159,13 @@ module RSpec
 
     private
 
-      if RUBY_VERSION == '1.8.6'
+      if "".respond_to?(:shellescape)
         def shellescape(string)
-          string.gsub(/"/, '\"').gsub(/'/, "\\\\'")
+          string.shellescape
         end
-      else
+      else # 1.8.6's shellwords doesn't provide shellescape :(.
         def shellescape(string)
-          string.shellescape
+          string.gsub(/"/, '\"').gsub(/'/, "\\\\'")
         end
       end
 

data/lib/rspec/core/version.rb

@@ -1,7 +1,7 @@
 module RSpec
   module Core
     module Version
-      STRING = '2.12.1'
+      STRING = '2.12.2'
     end
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: rspec-core
 version: !ruby/object:Gem::Version 
-  hash: 61
+  hash: 59
   prerelease: 
   segments: 
   - 2
   - 12
-  - 1
-  version: 2.12.1
+  - 2
+  version: 2.12.2
 platform: ruby
 authors: 
 - Steven Baker
@@ -17,7 +17,7 @@ autorequire:
 bindir: exe
 cert_chain: []
 
-date: 2012-12-01 00:00:00 Z
+date: 2012-12-14 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   version_requirements: &id001 !ruby/object:Gem::Requirement 
@@ -389,7 +389,7 @@ rubyforge_project: rspec
 rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
-summary: rspec-core-2.12.1
+summary: rspec-core-2.12.2
 test_files: 
 - features/Autotest.md
 - features/README.md