From 01672e4ed0e3eb034f426a585c9af5365e9ec646 Mon Sep 17 00:00:00 2001
From: Steve Klabnik <steve@steveklabnik.com>
Date: Sat, 17 Aug 2013 14:05:46 -0400
Subject: [PATCH] Bring Test/Unit up to 100% documentation.

Add a notice to the top level of Test/Unit to discuss its legacy status,
as well as nodoc the rest of it, since it's now private.
---
 lib/test/unit.rb            |  139 +++++++++++++++++++++++--------------------
 lib/test/unit/assertions.rb |    2 +-
 lib/test/unit/parallel.rb   |   18 +++---
 lib/test/unit/testcase.rb   |    8 +--
 4 files changed, 90 insertions(+), 77 deletions(-)

diff --git a/lib/test/unit.rb b/lib/test/unit.rb
index b96dece..f0001fa 100644
--- a/lib/test/unit.rb
+++ b/lib/test/unit.rb
@@ -1,27 +1,33 @@
-# test/unit compatibility layer using minitest.
-
 require 'minitest/unit'
 require 'test/unit/assertions'
 require 'test/unit/testcase'
 require 'optparse'
 
 module Test
+  ##
+  # = Test/Unit
+  #
+  # Test/Unit is an implementation of the xUnit testing framework for Ruby.
+  #
+  # If you are writing new test code, please use MiniTest instead of Test/Unit.
+  # Test/Unit has been left in the standard library to support legacy test
+  # suites.
   module Unit
-    TEST_UNIT_IMPLEMENTATION = 'test/unit compatibility layer using minitest'
+    TEST_UNIT_IMPLEMENTATION = 'test/unit compatibility layer using minitest' # :nodoc:
 
     module RunCount
       @@run_count = 0
 
-      def self.have_run?
+      def self.have_run? # :nodoc:
         @@run_count.nonzero?
       end
 
-      def run(*)
+      def run(*) # :nodoc:
         @@run_count += 1
         super
       end
 
-      def run_once
+      def run_once # :nodoc:
         return if have_run?
         return if $! # don't run if there was an exception
         yield
@@ -30,17 +36,17 @@ module Test
     end
 
     module Options
-      def initialize(*, &block)
+      def initialize(*, &block) # :nodoc:
         @init_hook = block
         @options = nil
         super(&nil)
       end
 
-      def option_parser
+      def option_parser # :nodoc:
         @option_parser ||= OptionParser.new
       end
 
-      def process_args(args = [])
+      def process_args(args = []) # :nodoc:
         return @options if @options
         orig_args = args.dup
         options = {}
@@ -154,7 +160,7 @@ module Test
     module GlobOption
       @@testfile_prefix = "test"
 
-      def setup_options(parser, options)
+      def setup_options(parser, options) # :nodoc:
         super
         parser.on '-b', '--basedir=DIR', 'Base directory of test suites.' do |dir|
           options[:base_directory] = dir
@@ -164,7 +170,7 @@ module Test
         end
       end
 
-      def non_options(files, options)
+      def non_options(files, options) # :nodoc:
         paths = [options.delete(:base_directory), nil].uniq
         if reject = options.delete(:reject)
           reject_pat = Regexp.union(reject.map {|r| /#{r}/ })
@@ -198,7 +204,7 @@ module Test
     end
 
     module LoadPathOption
-      def setup_options(parser, options)
+      def setup_options(parser, options) # :nodoc:
         super
         parser.on '-Idirectory', 'Add library load path' do |dirs|
           dirs.split(':').each { |d| $LOAD_PATH.unshift d }
@@ -207,14 +213,14 @@ module Test
     end
 
     module GCStressOption
-      def setup_options(parser, options)
+      def setup_options(parser, options) # :nodoc:
         super
         parser.on '--[no-]gc-stress', 'Set GC.stress as true' do |flag|
           options[:gc_stress] = flag
         end
       end
 
-      def non_options(files, options)
+      def non_options(files, options) # :nodoc:
         if options.delete(:gc_stress)
           MiniTest::Unit::TestCase.class_eval do
             oldrun = instance_method(:run)
@@ -233,7 +239,7 @@ module Test
     end
 
     module RequireFiles
-      def non_options(files, options)
+      def non_options(files, options) # :nodoc:
         return false if !super
         result = false
         files.each {|f|
@@ -260,16 +266,16 @@ module Test
       include Test::Unit::RunCount
 
       class Worker
-        def self.launch(ruby,args=[])
+        def self.launch(ruby,args=[]) # :nodoc:
           io = IO.popen([*ruby,
                         "#{File.dirname(__FILE__)}/unit/parallel.rb",
                         *args], "rb+")
           new(io, io.pid, :waiting)
         end
 
-        attr_reader :quit_called
+        attr_reader :quit_called # :nodoc:
 
-        def initialize(io, pid, status)
+        def initialize(io, pid, status) # :nodoc:
           @io = io
           @pid = pid
           @status = status
@@ -280,11 +286,11 @@ module Test
           @quit_called = false
         end
 
-        def puts(*args)
+        def puts(*args) # :nodoc:
           @io.puts(*args)
         end
 
-        def run(task,type)
+        def run(task,type) # :nodoc:
           @file = File.basename(task, ".rb")
           @real_file = task
           begin
@@ -300,43 +306,43 @@ module Test
           end
         end
 
-        def hook(id,&block)
+        def hook(id,&block) # :nodoc:
           @hooks[id] ||= []
           @hooks[id] << block
           self
         end
 
-        def read
+        def read # :nodoc:
           res = (@status == :quit) ? @io.read : @io.gets
           res && res.chomp
         end
 
-        def close
+        def close # :nodoc:
           @io.close unless @io.closed?
           self
         rescue IOError
         end
 
-        def quit
+        def quit # :nodoc:
           return if @io.closed?
           @quit_called = true
           @io.puts "quit"
           @io.close
         end
 
-        def kill
+        def kill # :nodoc:
           Process.kill(:KILL, @pid)
         rescue Errno::ESRCH
         end
 
-        def died(*additional)
+        def died(*additional) # :nodoc:
           @status = :quit
           @io.close
 
           call_hook(:dead,*additional)
         end
 
-        def to_s
+        def to_s # :nodoc:
           if @file
             "#{@pid}=#{@file}"
           else
@@ -344,8 +350,8 @@ module Test
           end
         end
 
-        attr_reader :io, :pid
-        attr_accessor :status, :file, :real_file, :loadpath
+        attr_reader :io, :pid # :nodoc:
+        attr_accessor :status, :file, :real_file, :loadpath # :nodoc:
 
         private
 
@@ -360,7 +366,7 @@ module Test
       class << self; undef autorun; end
 
       @@stop_auto_run = false
-      def self.autorun
+      def self.autorun # :nodoc:
         at_exit {
           Test::Unit::RunCount.run_once {
             exit(Test::Unit::Runner.new.run(ARGV) || true)
@@ -369,7 +375,7 @@ module Test
         @@installed_at_exit = true
       end
 
-      def after_worker_down(worker, e=nil, c=false)
+      def after_worker_down(worker, e=nil, c=false) # :nodoc:
         return unless @options[:parallel]
         return if @interrupt
         warn e if e
@@ -383,7 +389,7 @@ module Test
         exit c
       end
 
-      def terminal_width
+      def terminal_width # :nodoc:
         unless @terminal_width ||= nil
           begin
             require 'io/console'
@@ -397,7 +403,7 @@ module Test
         @terminal_width
       end
 
-      def del_status_line
+      def del_status_line # :nodoc:
         @status_line_size ||= 0
         unless @options[:job_status] == :replace
           $stdout.puts
@@ -408,7 +414,7 @@ module Test
         @status_line_size = 0
       end
 
-      def put_status(line)
+      def put_status(line) # :nodoc:
         unless @options[:job_status] == :replace
           print(line)
           return
@@ -422,7 +428,7 @@ module Test
         @status_line_size = line.size
       end
 
-      def add_status(line)
+      def add_status(line) # :nodoc:
         unless @options[:job_status] == :replace
           print(line)
           return
@@ -434,19 +440,19 @@ module Test
         @status_line_size += line.size
       end
 
-      def jobs_status
+      def jobs_status # :nodoc:
         return unless @options[:job_status]
         puts "" unless @options[:verbose] or @options[:job_status] == :replace
         status_line = @workers.map(&:to_s).join(" ")
         update_status(status_line) or (puts; nil)
       end
 
-      def del_jobs_status
+      def del_jobs_status # :nodoc:
         return unless @options[:job_status] == :replace && @status_line_size.nonzero?
         del_status_line
       end
 
-      def after_worker_quit(worker)
+      def after_worker_quit(worker) # :nodoc:
         return unless @options[:parallel]
         return if @interrupt
         @workers.delete(worker)
@@ -454,7 +460,7 @@ module Test
         @ios = @workers.map(&:io)
       end
 
-      def launch_worker
+      def launch_worker # :nodoc:
         begin
           worker = Worker.launch(@options[:ruby],@args)
         rescue => e
@@ -470,13 +476,13 @@ module Test
         worker
       end
 
-      def delete_worker(worker)
+      def delete_worker(worker) # :nodoc:
         @workers_hash.delete worker.io
         @workers.delete worker
         @ios.delete worker.io
       end
 
-      def quit_workers
+      def quit_workers # :nodoc:
         return if @workers.empty?
         @workers.reject! do |worker|
           begin
@@ -502,7 +508,7 @@ module Test
         end
       end
 
-      def start_watchdog
+      def start_watchdog # :nodoc:
         Thread.new do
           while stat = Process.wait2
             break if @interrupt # Break when interrupt
@@ -518,7 +524,7 @@ module Test
         end
       end
 
-      def deal(io, type, result, rep, shutting_down = false)
+      def deal(io, type, result, rep, shutting_down = false) # :nodoc:
         worker = @workers_hash[io]
         case worker.read
         when /^okay$/
@@ -561,7 +567,7 @@ module Test
         return false
       end
 
-      def _run_parallel suites, type, result
+      def _run_parallel suites, type, result # :nodoc:
         if @options[:parallel] < 1
           warn "Error: parameter of -j option should be greater than 0."
           return
@@ -644,7 +650,7 @@ module Test
         end
       end
 
-      def _run_suites suites, type
+      def _run_suites suites, type # :nodoc:
         _prepare_run(suites, type)
         @interrupt = nil
         result = []
@@ -669,11 +675,11 @@ module Test
 
       alias mini_run_suite _run_suite
 
-      def output
+      def output # :nodoc:
         (@output ||= nil) || super
       end
 
-      def _prepare_run(suites, type)
+      def _prepare_run(suites, type) # :nodoc:
         options[:job_status] ||= :replace if @tty && !@verbose
         case options[:color]
         when :always
@@ -710,18 +716,18 @@ module Test
         @total_tests = total.to_s(10)
       end
 
-      def new_test(s)
+      def new_test(s) # :nodoc:
         @test_count += 1
         update_status(s)
       end
 
-      def update_status(s)
+      def update_status(s) # :nodoc:
         count = @test_count.to_s(10).rjust(@total_tests.size)
         put_status("#{@passed_color}[#{count}/#{@total_tests}]#{@reset_color} #{s}")
       end
 
-      def _print(s); $stdout.print(s); end
-      def succeed; del_status_line; end
+      def _print(s); $stdout.print(s); end # :nodoc:
+      def succeed; del_status_line; end # :nodoc:
 
       def failed(s)
         sep = "\n"
@@ -778,11 +784,11 @@ module Test
     end
 
     class StatusLineOutput < Struct.new(:runner)
-      def puts(*a) $stdout.puts(*a) unless a.empty? end
-      def respond_to_missing?(*a) $stdout.respond_to?(*a) end
-      def method_missing(*a, &b) $stdout.__send__(*a, &b) end
+      def puts(*a) $stdout.puts(*a) unless a.empty? end # :nodoc:
+      def respond_to_missing?(*a) $stdout.respond_to?(*a) end # :nodoc:
+      def method_missing(*a, &b) $stdout.__send__(*a, &b) end # :nodoc:
 
-      def print(s)
+      def print(s) # :nodoc:
         case s
         when /\A(.*\#.*) = \z/
           runner.new_test($1)
@@ -803,9 +809,9 @@ module Test
         include Test::Unit::RequireFiles
       end
 
-      attr_accessor :to_run, :options
+      attr_accessor :to_run, :options # :nodoc:
 
-      def initialize(force_standalone = false, default_dir = nil, argv = ARGV)
+      def initialize(force_standalone = false, default_dir = nil, argv = ARGV) # :nodoc:
         @force_standalone = force_standalone
         @runner = Runner.new do |files, options|
           options[:base_directory] ||= default_dir
@@ -822,38 +828,43 @@ module Test
         @argv = argv
       end
 
-      def process_args(*args)
+      def process_args(*args) # :nodoc:
         @runner.process_args(*args)
         !@to_run.empty?
       end
 
-      def run
+      def run # :nodoc:
         if @force_standalone and not process_args(@argv)
           abort @options.banner
         end
         @runner.run(@argv) || true
       end
 
-      def self.run(*args)
+      def self.run(*args) # :nodoc:
         new(*args).run
       end
     end
 
     class ProxyError < StandardError
-      def initialize(ex)
+      def initialize(ex) # :nodoc:
         @message = ex.message
         @backtrace = ex.backtrace
       end
 
-      attr_accessor :message, :backtrace
+      attr_accessor :message, :backtrace # :nodoc:
     end
   end
 end
 
+module MiniTest # :nodoc:
+  module Unit # :nodoc:
+  end
+end
+
 class MiniTest::Unit::TestCase
   undef run_test
-  RUN_TEST_TRACE = "#{__FILE__}:#{__LINE__+3}:in `run_test'".freeze
-  def run_test(name)
+  RUN_TEST_TRACE = "#{__FILE__}:#{__LINE__+3}:in `run_test'".freeze # :nodoc:
+  def run_test(name) # :nodoc:
     progname, $0 = $0, "#{$0}: #{self.class}##{name}"
     self.__send__(name)
   ensure
diff --git a/lib/test/unit/assertions.rb b/lib/test/unit/assertions.rb
index bc8530e..3d8a698 100644
--- a/lib/test/unit/assertions.rb
+++ b/lib/test/unit/assertions.rb
@@ -358,7 +358,7 @@ EOT
         template.gsub(/\G((?:[^\\]|\\.)*?)(\\)?\?/) { $1 + ($2 ? "?" : mu_pp(arguments.shift)) }
       end
 
-      def message(msg = nil, *args, &default)
+      def message(msg = nil, *args, &default) # :nodoc:
         if Proc === msg
           super(nil, *args) do
             [msg.call, (default.call if default)].compact.reject(&:empty?).join(".\n")
diff --git a/lib/test/unit/parallel.rb b/lib/test/unit/parallel.rb
index d189183..d34bb02 100644
--- a/lib/test/unit/parallel.rb
+++ b/lib/test/unit/parallel.rb
@@ -2,7 +2,7 @@ require 'test/unit'
 
 module Test
   module Unit
-    class Worker < Runner
+    class Worker < Runner # :nodoc:
       class << self
         undef autorun
       end
@@ -12,19 +12,19 @@ module Test
       undef _run_suites
       undef run
 
-      def increment_io(orig)
+      def increment_io(orig) # :nodoc:
         *rest, io = 32.times.inject([orig.dup]){|ios, | ios << ios.last.dup }
         rest.each(&:close)
         io
       end
 
-      def _run_suites(suites, type)
+      def _run_suites(suites, type) # :nodoc:
         suites.map do |suite|
           _run_suite(suite, type)
         end
       end
 
-      def _run_suite(suite, type)
+      def _run_suite(suite, type) # :nodoc:
         @partial_report = []
         orig_testout = MiniTest::Unit.output
         i,o = IO.pipe
@@ -81,7 +81,7 @@ module Test
         i.close if i && !i.closed?
       end
 
-      def run(args = [])
+      def run(args = []) # :nodoc:
         process_args args
         @@stop_auto_run = true
         @opts = @options.dup
@@ -149,12 +149,12 @@ module Test
         end
       end
 
-      def _report(res, *args)
+      def _report(res, *args) # :nodoc:
         res = "#{res} #{args.pack("m0")}" unless args.empty?
         @stdout.puts(res)
       end
 
-      def puke(klass, meth, e)
+      def puke(klass, meth, e) # :nodoc:
         @partial_report << [klass.name, meth, e.is_a?(MiniTest::Assertion) ? e : ProxyError.new(e)]
         super
       end
@@ -167,13 +167,15 @@ if $0 == __FILE__
     module Unit
       class TestCase < MiniTest::Unit::TestCase
         undef on_parallel_worker?
-        def on_parallel_worker?
+        def on_parallel_worker? # :nodoc:
           true
         end
       end
     end
   end
   require 'rubygems'
+  module Gem # :nodoc
+  end
   class Gem::TestCase < MiniTest::Unit::TestCase
     @@project_dir = File.expand_path('../../../..', __FILE__)
   end
diff --git a/lib/test/unit/testcase.rb b/lib/test/unit/testcase.rb
index 59637e1..7f32ba4 100644
--- a/lib/test/unit/testcase.rb
+++ b/lib/test/unit/testcase.rb
@@ -8,20 +8,20 @@ module Test
     class TestCase < MiniTest::Unit::TestCase
       include Assertions
 
-      def on_parallel_worker?
+      def on_parallel_worker? # :nodoc:
         false
       end
 
-      def run runner
+      def run runner # :nodoc:
         @options = runner.options
         super runner
       end
 
-      def self.test_order
+      def self.test_order # :nodoc:
         :sorted
       end
 
-      def self.method_added(name)
+      def self.method_added(name) # :nodoc:
         return unless name.to_s.start_with?("test_")
         @test_methods ||= {}
         if @test_methods[name]
-- 
1.7.10.4

