Clarify add_formatter API.

- Officially support passing an `output` argument. Previously, it was
  not part of the public API, as the note in the doc made clear.
  However, the method is called `add_formatter` because users can add
  multiple formatters, but that mostly only makes sense when they are
  directing different formatters to different output streams. For
  example, the progress formatter to `$stdout` and the HTML formatter
  to `specs.html`.
- Do not support multiple `output` stream args. Officially, formatters
  all need to accept exactly one `output` arg in their initalizers. We
  have one special case (the deprecation formatter) which is used
  internally, which relied upon this (and only the specs relied upon
  this).
- Flesh out docs to describe the args better.

lib/rspec/core/configuration.rb

@@ -850,19 +850,22 @@ def full_description
       end
 
       # @overload add_formatter(formatter)
-      #
-      # Adds a formatter to the formatters collection. `formatter` can be a
-      # string representing any of the built-in formatters (see
-      # `built_in_formatter`), or a custom formatter class.
-      #
-      # ### Note
-      #
-      # For internal purposes, `add_formatter` also accepts the name of a class
-      # and paths to use for output streams, but you should consider that a
-      # private api that may change at any time without notice.
-      def add_formatter(formatter_to_use, *paths)
-        paths << output_stream if paths.empty?
-        formatter_loader.add formatter_to_use, *paths
+      # @overload add_formatter(formatter, output)
+      #
+      # @param formatter [Class, String] formatter to use. Can be any of the
+      #   string values supported from the CLI (`p`/`progress`,
+      #   `d`/`doc`/`documentation`, `h`/`html`, or `j`/`json`) or any
+      #   class that implements the formatter protocol and has registered
+      #   itself with RSpec as a formatter.
+      # @param output [String, IO] where the formatter will write its output.
+      #   Can be an IO object or a string path to a file. If not provided,
+      #   the configured `output_stream` (`$stdout`, by default) will be used.
+      #
+      # Adds a formatter to the set RSpec will use for this run.
+      #
+      # @see RSpec::Core::Formatters::Protocol
+      def add_formatter(formatter, output=output_stream)
+        formatter_loader.add(formatter, output)
       end
       alias_method :formatter=, :add_formatter
 

spec/support/formatter_support.rb

@@ -213,7 +213,8 @@ def reporter
   end
 
   def setup_reporter(*streams)
-    config.add_formatter described_class, *streams
+    streams << config.output_stream if streams.empty?
+    config.formatter_loader.add described_class, *streams
     @formatter = config.formatters.first
     @reporter = config.reporter
   end