document the scripts

script/console

@@ -1,4 +1,7 @@
 #!/usr/bin/env ruby
+# Usage: script/console
+# Starts an IRB console with this library loaded.
+
 require 'rubygems'
 require 'irb'
 require File.expand_path("../ruby", __FILE__)

script/gem

@@ -1,4 +1,7 @@
 #!/usr/bin/env ruby
+# Usage: script/gem
+# Updates the gemspec and builds a new gem in the pkg directory.
+
 require File.expand_path("../ruby", __FILE__)
 require 'fileutils'
 

script/gemspec

@@ -1,4 +1,7 @@
 #!/usr/bin/env ruby
+# Usage: script/gemspec
+# Updates the gemspec's name, version, and file manifest.
+
 require File.expand_path("../ruby", __FILE__)
 
 def replace_header(head, header_name)

script/generate_certs

@@ -1,4 +1,7 @@
 #!/usr/bin/env ruby
+# Usage: generate_certs
+# Generate test certs for testing Faraday with SSL
+
 require File.expand_path("../ruby", __FILE__)
 require 'openssl'
 require 'fileutils'

script/release

@@ -1,4 +1,7 @@
 #!/usr/bin/env ruby
+# Usage: script/release
+# Build the gem, tag a commit, push to origin, and push the gem to Rubyforge.
+
 require File.expand_path("../ruby", __FILE__)
 
 puts `script/gem`

script/ruby.rb

@@ -1,3 +1,17 @@
+# Opinionated module that picks out a ruby library's name and version based on
+# some conventions:
+#
+# * #{lib_name}.gemspec
+# * A VERSION constant defined in lib/#{lib_name}.rb
+#
+# Example:
+#
+#   # foo.gemspec
+#   # lib/foo.rb
+#   module Foo
+#     VERSION = "0.1"
+#   end
+
 module MakeScript
   extend self
 

script/test

@@ -1,15 +1,18 @@
 #!/usr/bin/env ruby
+# Usage: script/test [file] [adapter]... -- [test/unit options]
 # Runs the test suite against a local server spawned automatically in a
 # thread. After tests are done, the server is shut down.
 #
 # If filename arguments are given, only those files are run. If arguments given
 # are not filenames, they are taken as words that filter the list of files to run.
 #
-# Examples
+# Examples:
 #
 #   $ script/test
 #   $ script/test test/env_test.rb
 #   $ script/test excon typhoeus
+#
+#   # Run only tests matching /ssl/ for the net_http adapter, with SSL enabled.
 #   $ SSL=yes script/test net_http -- -n /ssl/
 
 require 'rubygems'