From 465098a233412a04164092608d15bfbd9e01206a Mon Sep 17 00:00:00 2001 From: Greggory Rothmeier Date: Tue, 16 Oct 2012 10:44:02 -0400 Subject: [PATCH] update documentation for Formatters::BaseFormatter fixes #673 --- lib/rspec/core/formatters/base_formatter.rb | 89 ++++++++++++++++++--- 1 file changed, 80 insertions(+), 9 deletions(-) diff --git a/lib/rspec/core/formatters/base_formatter.rb b/lib/rspec/core/formatters/base_formatter.rb index 11e50cb7ad..970cdfff1b 100644 --- a/lib/rspec/core/formatters/base_formatter.rb +++ b/lib/rspec/core/formatters/base_formatter.rb @@ -8,6 +8,22 @@ module Formatters # but the BaseTextFormatter documents all of the methods needed to be implemented by a formatter, # as they are called from the reporter. # + # * {#start start(example_count)} + # * zero or more of the following + # * {#example_group_started example_group_started(group)} + # * {#example_started example_started(example)} + # * {#example_passed example_passed(example)} + # * {#example_failed example_failed(example)} + # * {#example_pending example_pending(example)} + # * {#message message(string)} + # * {#stop stop} + # * {#start_dump start_dump} + # * {#dump_pending dump_pending} + # * {#dump_failures dump_failures} + # * {#dump_summary dump_summary(duration, example_count, failure_count, pending_count)} + # * {#seed seed(value)} + # * {#close close} + # # @see RSpec::Core::Formatters::BaseTextFormatter # @see RSpec::Core::Reporter class BaseFormatter @@ -17,6 +33,9 @@ class BaseFormatter 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 +45,14 @@ def initialize(output) @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 +60,40 @@ def start(example_count) @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 +103,64 @@ def example_passed(example) # 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 + # set to an instance variable. + # + # @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 +168,11 @@ def dump_summary(duration, example_count, failure_count, pending_count) @pending_count = pending_count end - # Invoked after the summary if option is set to do so. + # @api public + # + # This gets invoked after the summary if option is set to do so. + # + # @return [nil] def dump_pending end @@ -111,6 +180,8 @@ def dump_pending 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