33 files changed, 118 insertions, 5 deletions
diff --git a/ChangeLog b/ChangeLog
index 1213644718..5f26018721 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,40 @@
+Sun Jul  3 05:25:46 2016  Eric Wong  <e@80x24.org>
+
+	* tool/asm_parse.rb: add description
+	* tool/change_maker.rb: ditto
+	* tool/downloader.rb: ditto
+	* tool/eval.rb: ditto
+	* tool/expand-config.rb: ditto
+	* tool/extlibs.rb: ditto
+	* tool/fake.rb: ditto
+	* tool/file2lastrev.rb: ditto
+	* tool/gem-unpack.rb: ditto
+	* tool/gen_dummy_probes.rb: ditto
+	* tool/gen_ruby_tapset.rb: ditto
+	* tool/generic_erb.rb: ditto
+	* tool/id2token.rb: ditto
+	* tool/ifchange: ditto
+	* tool/insns2vm.rb: ditto
+	* tool/instruction.rb: ditto
+	* tool/jisx0208.rb: ditto
+	* tool/merger.rb: ditto
+	* tool/mkrunnable.rb: ditto
+	* tool/node_name.rb: ditto
+	* tool/parse.rb: ditto
+	* tool/rbinstall.rb: ditto
+	* tool/rbuninstall.rb: ditto
+	* tool/rmdirs: ditto
+	* tool/runruby.rb: ditto
+	* tool/strip-rdoc.rb: ditto
+	* tool/vcs.rb: ditto
+	* tool/vtlh.rb: ditto
+	* tool/ytab.sed: ditto
+	* tool/enc-unicode.rb: fix typo
+	* tool/mk_call_iseq_optimized.rb: ditto
+	* tool/update-deps: ditto
+	  [ruby-core:76215] [Bug #12539]
+	  by Noah Gibbs <the.codefolio.guy@gmail.com>
+
 Sat Jul  2 18:04:24 2016  NARUSE, Yui  <naruse@ruby-lang.org>
 
 	* lib/uri/mailto.rb (initialize): RFC3986_Parser#split sets opaque
diff --git a/tool/asm_parse.rb b/tool/asm_parse.rb
index e39580c1a1..32882be3ad 100644
--- a/tool/asm_parse.rb
+++ b/tool/asm_parse.rb
@@ -1,3 +1,5 @@
+# YARV tool to parse assembly output.
+
 stat = {}
 
 while line = ARGF.gets
diff --git a/tool/change_maker.rb b/tool/change_maker.rb
index f7b7650a51..395bd34990 100755
--- a/tool/change_maker.rb
+++ b/tool/change_maker.rb
@@ -1,5 +1,8 @@
 #! ./miniruby
 
+# Used by "make change" to generate a list of files for a Changelog entry.
+# Run it via "make change" in the Ruby root directory.
+
 $:.unshift(File.expand_path("../../lib", __FILE__))
 require File.expand_path("../vcs", __FILE__)
 
diff --git a/tool/downloader.rb b/tool/downloader.rb
index 74ff309637..aa5490f96f 100644
--- a/tool/downloader.rb
+++ b/tool/downloader.rb
@@ -1,3 +1,6 @@
+# Used by configure and make to download or update mirrored Ruby and GCC
+# files. This will use HTTPS if possible, falling back to HTTP.
+
 require 'open-uri'
 begin
   require 'net/https'
diff --git a/tool/enc-unicode.rb b/tool/enc-unicode.rb
index bebd47f39d..a8075a34a6 100755
--- a/tool/enc-unicode.rb
+++ b/tool/enc-unicode.rb
@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 
-# Creates the data structures needed by Onigurma to map Unicode codepoints to
+# Creates the data structures needed by Oniguruma to map Unicode codepoints to
 # property names and POSIX character classes
 #
 # To use this, get UnicodeData.txt, Scripts.txt, PropList.txt,
diff --git a/tool/eval.rb b/tool/eval.rb
index 18e645a314..981f72733b 100644
--- a/tool/eval.rb
+++ b/tool/eval.rb
@@ -1,3 +1,4 @@
+# VM checking and benchmarking code
 
 require './rbconfig'
 require 'fileutils'
diff --git a/tool/expand-config.rb b/tool/expand-config.rb
index bb88865709..d34f29f586 100755
--- a/tool/expand-config.rb
+++ b/tool/expand-config.rb
@@ -1,5 +1,7 @@
 #!./miniruby -s
 
+# Used to expand Ruby config entries for Win32 Makefiles.
+
 config = File.read(conffile = $config)
 config.sub!(/^(\s*)RUBY_VERSION\b.*(\sor\s*)$/, '\1true\2')
 rbconfig = Module.new {module_eval(config, conffile)}::RbConfig
diff --git a/tool/extlibs.rb b/tool/extlibs.rb
index 710d8433b5..ee4fd72a16 100755
--- a/tool/extlibs.rb
+++ b/tool/extlibs.rb
@@ -1,4 +1,8 @@
 #!/usr/bin/ruby
+
+# Used to download, extract and patch extension libraries (extlibs)
+# for Ruby. See common.mk for Ruby's usage.
+
 require 'fileutils'
 require 'digest'
 require_relative 'downloader'
diff --git a/tool/fake.rb b/tool/fake.rb
index 03d2e4dd3f..99fc24e775 100644
--- a/tool/fake.rb
+++ b/tool/fake.rb
@@ -1,3 +1,6 @@
+# Used by Makefile and configure for building Ruby.
+# See common.mk and Makefile.in for details.
+
 class File
   sep = ("\\" if RUBY_PLATFORM =~ /mswin|bccwin|mingw/)
   if sep != ALT_SEPARATOR
diff --git a/tool/file2lastrev.rb b/tool/file2lastrev.rb
index 79e6c655ac..ee615a5060 100755
--- a/tool/file2lastrev.rb
+++ b/tool/file2lastrev.rb
@@ -1,5 +1,8 @@
 #!/usr/bin/env ruby
 
+# Gets the most recent revision of a file in a VCS-agnostic way.
+# Used by Doxygen, Makefiles and merger.rb.
+
 require 'optparse'
 
 # this file run with BASERUBY, which may be older than 1.9, so no
diff --git a/tool/gem-unpack.rb b/tool/gem-unpack.rb
index 7f84126677..f069d144ec 100755
--- a/tool/gem-unpack.rb
+++ b/tool/gem-unpack.rb
@@ -1,6 +1,9 @@
 require 'rubygems'
 require 'rubygems/package'
 
+# This library is used by "make extract-gems" to
+# unpack bundled gem files.
+
 def Gem.unpack(file, dir = nil)
   policy = Gem::Security::LowSecurity
   (policy = policy.dup).ui = Gem::SilentUI.new
diff --git a/tool/gen_dummy_probes.rb b/tool/gen_dummy_probes.rb
index 05e724fed8..7d63cdfa3e 100755
--- a/tool/gen_dummy_probes.rb
+++ b/tool/gen_dummy_probes.rb
@@ -1,6 +1,9 @@
 #!/usr/bin/ruby
 # -*- coding: us-ascii -*-
 
+# Used to create dummy probes (as for systemtap and DTrace) by Makefiles.
+# See common.mk.
+
 text = ARGF.read
 
 # remove comments
diff --git a/tool/gen_ruby_tapset.rb b/tool/gen_ruby_tapset.rb
index c34fb88611..ca4b09905a 100755
--- a/tool/gen_ruby_tapset.rb
+++ b/tool/gen_ruby_tapset.rb
@@ -1,5 +1,6 @@
 #!/usr/bin/ruby
 # -*- coding: us-ascii -*-
+# Create a tapset for systemtap and DTrace
 # usage: ./ruby gen_ruby_tapset.rb --ruby-path=/path/to/ruby probes.d > output
 
 require "optparse"
diff --git a/tool/generic_erb.rb b/tool/generic_erb.rb
index 5d44738297..0664056651 100644
--- a/tool/generic_erb.rb
+++ b/tool/generic_erb.rb
@@ -1,4 +1,8 @@
 # -*- coding: us-ascii -*-
+
+# Used to expand Ruby template files by common.mk, uncommon.mk and
+# some Ruby extension libraries.
+
 require 'erb'
 require 'optparse'
 require 'fileutils'
diff --git a/tool/id2token.rb b/tool/id2token.rb
index 191b872c5f..706154ecfb 100755
--- a/tool/id2token.rb
+++ b/tool/id2token.rb
@@ -1,5 +1,8 @@
 #! /usr/bin/ruby -p
 # -*- coding: us-ascii -*-
+
+# Used to build the Ruby parsing code in common.mk and Ripper.
+
 BEGIN {
   require 'optparse'
   $:.unshift(File.dirname(__FILE__))
diff --git a/tool/ifchange b/tool/ifchange
index cc630b0c99..8571cf8049 100755
--- a/tool/ifchange
+++ b/tool/ifchange
@@ -1,6 +1,8 @@
 #!/bin/sh
 # usage: ifchange target temporary
 
+# Used in generating revision.h via Makefiles.
+
 set -e
 timestamp=
 keepsuffix=
diff --git a/tool/insns2vm.rb b/tool/insns2vm.rb
index f518707f11..ecbbb52643 100755
--- a/tool/insns2vm.rb
+++ b/tool/insns2vm.rb
@@ -1,5 +1,8 @@
 #!ruby
 
+# This is used by Makefile.in to generate .inc files.
+# See Makefile.in for details.
+
 require 'optparse'
 
 Version = %w$Revision: 11626 $[1..-1]
diff --git a/tool/instruction.rb b/tool/instruction.rb
index 45117950cf..57dc923005 100755
--- a/tool/instruction.rb
+++ b/tool/instruction.rb
@@ -1,7 +1,8 @@
 #!./miniruby
 # -*- coding: us-ascii -*-
 #
-#
+# This library is used by insns2vm.rb as part of autogenerating
+# instruction files with .inc extensions like insns.inc and vm.inc.
 
 require 'erb'
 $:.unshift(File.dirname(__FILE__))
diff --git a/tool/jisx0208.rb b/tool/jisx0208.rb
index 921f574816..30185fb81b 100644
--- a/tool/jisx0208.rb
+++ b/tool/jisx0208.rb
@@ -1,3 +1,5 @@
+# Library used by tools/enc-emoji-citrus-gen.rb
+
 module JISX0208
   class Char
     class << self
diff --git a/tool/merger.rb b/tool/merger.rb
index cfc3d58831..2faf86634f 100755
--- a/tool/merger.rb
+++ b/tool/merger.rb
@@ -3,7 +3,8 @@
 exec "${RUBY-ruby}" "-x" "$0" "$@" && [ ] if false
 #!ruby
 # This needs ruby 1.9 and subversion.
-# run this in a repository to commit.
+# As a Ruby committer, run this in an SVN repository
+# to commit a change.
 
 require 'fileutils'
 require 'tempfile'
diff --git a/tool/mk_call_iseq_optimized.rb b/tool/mk_call_iseq_optimized.rb
index 0af637b17d..7df36eb850 100644
--- a/tool/mk_call_iseq_optimized.rb
+++ b/tool/mk_call_iseq_optimized.rb
@@ -4,7 +4,7 @@ puts <<EOS
 
 /* DO NOT EDIT THIS FILE DIRECTLY
  *
- * This file is enerated by tool/mkcall_iseq.rb
+ * This file is generated by tool/mkcall_iseq.rb
  */
 
 EOS
diff --git a/tool/mkrunnable.rb b/tool/mkrunnable.rb
index 4e73771485..fbfc76047a 100755
--- a/tool/mkrunnable.rb
+++ b/tool/mkrunnable.rb
@@ -1,6 +1,9 @@
 #!./miniruby
 # -*- coding: us-ascii -*-
 
+# Used by "make runnable" target, to make symbolic links from a build
+# directory.
+
 require './rbconfig'
 require 'fileutils'
 
diff --git a/tool/node_name.rb b/tool/node_name.rb
index fef7720a5a..5c67d7ccd5 100755
--- a/tool/node_name.rb
+++ b/tool/node_name.rb
@@ -1,4 +1,8 @@
 #! ./miniruby
+
+# Used when making Ruby to generate node_name.inc.
+# See common.mk for details.
+
 while gets
   if ~/enum node_type \{/..~/^\};/
     ~/(NODE_.+),/ and puts("      case #{$1}:\n\treturn \"#{$1}\";")
diff --git a/tool/parse.rb b/tool/parse.rb
index 6243d7aa8e..93ae3e43cb 100644
--- a/tool/parse.rb
+++ b/tool/parse.rb
@@ -1,3 +1,6 @@
+# Used as part of the "make parse" Makefile target.
+# See common.mk for details.
+
 $file = ARGV[0]
 $str  = ARGF.read.sub(/^__END__.*\z/m, '')
 puts '# ' + '-' * 70
diff --git a/tool/rbinstall.rb b/tool/rbinstall.rb
index 72cca6c18c..104d5ff98f 100755
--- a/tool/rbinstall.rb
+++ b/tool/rbinstall.rb
@@ -1,5 +1,8 @@
 #!./miniruby
 
+# Used by the "make install" target to install Ruby.
+# See common.mk for more details.
+
 begin
   load "./rbconfig.rb"
 rescue LoadError
diff --git a/tool/rbuninstall.rb b/tool/rbuninstall.rb
index 1a11766790..eb324c966e 100755
--- a/tool/rbuninstall.rb
+++ b/tool/rbuninstall.rb
@@ -1,4 +1,8 @@
 #! /usr/bin/ruby -nl
+
+# Used by the "make uninstall" target to uninstall Ruby.
+# See common.mk for more details.
+
 BEGIN {
   $dryrun = false
   $tty = STDOUT.tty?
diff --git a/tool/rmdirs b/tool/rmdirs
index 6dcf984df6..76c4a39cb1 100755
--- a/tool/rmdirs
+++ b/tool/rmdirs
@@ -1,4 +1,7 @@
 #!/bin/sh
+
+# Script used by configure to delete directories recursively.
+
 for dir do
     while rmdir "$dir" >/dev/null 2>&1 &&
           parent=`expr "$dir" : '\(.*\)/[^/][^/]*'`; do
diff --git a/tool/runruby.rb b/tool/runruby.rb
index c316ff2d47..9329ef72b6 100755
--- a/tool/runruby.rb
+++ b/tool/runruby.rb
@@ -1,5 +1,8 @@
 #!./miniruby
 
+# Used by "make runruby", configure, and by hand to run a locally-built Ruby
+# with correct environment variables and arguments.
+
 show = false
 precommand = []
 while arg = ARGV[0]
diff --git a/tool/strip-rdoc.rb b/tool/strip-rdoc.rb
index 1902cb538c..0ac9c39323 100755
--- a/tool/strip-rdoc.rb
+++ b/tool/strip-rdoc.rb
@@ -1,5 +1,8 @@
 #!ruby
 
+# Filter for preventing Doxygen from processing RDoc comments.
+# Used by the Doxygen template.
+
 ARGF.binmode
 source = ARGF.read
 source = source.gsub(%r{/\*([!*])((?!\*/).+?)\*/}m) do |comment|
diff --git a/tool/update-deps b/tool/update-deps
index 4c20052263..e0067c8ac2 100755
--- a/tool/update-deps
+++ b/tool/update-deps
@@ -28,7 +28,7 @@ require 'pathname'
 require 'open3'
 require 'pp'
 
-# When out-of-place bulid, files may be built in source directory or
+# When out-of-place build, files may be built in source directory or
 # build directory.
 # Some files are always built in the source directory.
 # Some files are always built in the build directory.
diff --git a/tool/vcs.rb b/tool/vcs.rb
index 0f20c6e35a..9d0a276937 100644
--- a/tool/vcs.rb
+++ b/tool/vcs.rb
@@ -1,6 +1,9 @@
 # vcs
 require 'fileutils'
 
+# This library is used by several other tools/ scripts to detect the current
+# VCS in use (e.g. SVN, Git) or to interact with that VCS.
+
 ENV.delete('PWD')
 
 unless File.respond_to? :realpath
diff --git a/tool/vtlh.rb b/tool/vtlh.rb
index fcd3630821..2e1faf2ce8 100644
--- a/tool/vtlh.rb
+++ b/tool/vtlh.rb
@@ -1,3 +1,5 @@
+# Convert addresses to line numbers for MiniRuby.
+
 # ARGF = open('ha')
 cd = `pwd`.chomp + '/'
 ARGF.each{|line|
diff --git a/tool/ytab.sed b/tool/ytab.sed
index 706cf75a9a..a9599ce0ed 100755
--- a/tool/ytab.sed
+++ b/tool/ytab.sed
@@ -1,4 +1,5 @@
 #!/bin/sed -f
+# This file is used when generating code for the Ruby parser.
 /^int yydebug;/{
 i\
 #ifndef yydebug