tool: add descriptions and fix typos

* 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>

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@55564 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

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

tool/asm_parse.rb

@@ -1,3 +1,5 @@
+# YARV tool to parse assembly output.
+
 stat = {}
 
 while line = ARGF.gets

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__)
 

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'

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,

tool/eval.rb

@@ -1,3 +1,4 @@
+# VM checking and benchmarking code
 
 require './rbconfig'
 require 'fileutils'

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

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'

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

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

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

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

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"

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'

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__))

tool/ifchange

@@ -1,6 +1,8 @@
 #!/bin/sh
 # usage: ifchange target temporary
 
+# Used in generating revision.h via Makefiles.
+
 set -e
 timestamp=
 keepsuffix=

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]

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__))

tool/jisx0208.rb

@@ -1,3 +1,5 @@
+# Library used by tools/enc-emoji-citrus-gen.rb
+
 module JISX0208
   class Char
     class << self

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'

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

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'
 

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}\";")

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

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

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?

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

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]

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|

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.

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

tool/vtlh.rb

@@ -1,3 +1,5 @@
+# Convert addresses to line numbers for MiniRuby.
+
 # ARGF = open('ha')
 cd = `pwd`.chomp + '/'
 ARGF.each{|line|

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