Add `--help` to all developer commands.

Also, flag those that we never want to be in a manpage.

6 files changed, 116 insertions, 64 deletions

diff --git a/Library/Homebrew/dev-cmd/aspell-dictionaries.rb b/Library/Homebrew/dev-cmd/aspell-dictionaries.rb
index 754b6614e..16ec91835 100644
--- a/Library/Homebrew/dev-cmd/aspell-dictionaries.rb
+++ b/Library/Homebrew/dev-cmd/aspell-dictionaries.rb
@@ -1,3 +1,7 @@
+#: @hide_from_man_page
+#:  * `aspell_dictionaries`:
+#:    Generates the new dictionaries for the `aspell` formula.
+
 require "open-uri"
 require "resource"
 require "formula"
diff --git a/Library/Homebrew/dev-cmd/boneyard-formula-pr.rb b/Library/Homebrew/dev-cmd/boneyard-formula-pr.rb
index b478be609..890c9c4a0 100644
--- a/Library/Homebrew/dev-cmd/boneyard-formula-pr.rb
+++ b/Library/Homebrew/dev-cmd/boneyard-formula-pr.rb
@@ -1,10 +1,10 @@
-# Creates a pull request to boneyard a formula.
-#
-# Usage: brew boneyard-formula-pr [options...] <formula-name>
-#
-# Options:
-#   --dry-run:  Print what would be done rather than doing it.
-#   --local:    Perform only local operations (don't push and don't create PR).
+#: @hide_from_man_page
+#:  * `boneyard-formula-pr` [`--dry-run`] [`--local`]  <formula-name>:
+#:    Creates a pull request to boneyard a formula.
+#:
+#:    If `--dry-run` is passed, print what would be done rather than doing it.
+#:
+#:    If `--local` is passed, perform only local operations (i.e. don't push or create PR).
 
 require "formula"
 require "utils/json"
diff --git a/Library/Homebrew/dev-cmd/linkage.rb b/Library/Homebrew/dev-cmd/linkage.rb
index 8ee0e87df..993420c02 100644
--- a/Library/Homebrew/dev-cmd/linkage.rb
+++ b/Library/Homebrew/dev-cmd/linkage.rb
@@ -1,16 +1,14 @@
-#
-# Description: check linkage of installed keg
-# Usage:
-#   brew linkage <formulae>
-#
-# Only works on installed formulae. An error is raised if it is run on uninstalled
-# formulae.
-#
-# Options:
-#  --test      - testing version: only display broken libs; exit non-zero if any
-#                breakage was found.
-#  --reverse   - For each dylib the keg references, print the dylib followed by the
-#                binaries which link to it.
+#:  * `linkage` [`--test`] [`--reverse`]  <formula-name>:
+#:    Checks the library links of an installed formula.
+#:
+#:    Only works on installed formulae. An error is raised if it is run on
+#:    uninstalled formulae.
+#:
+#:    If `--test` is passed, only display missing libraries and exit with a
+#:    non-zero exit code if any missing libraries were found.
+#:
+#:    If `--reverse` is passed, print the dylib followed by the binaries
+#:    which link to it for each library the keg references.
 
 require "os/mac/linkage_checker"
 
diff --git a/Library/Homebrew/dev-cmd/mirror.rb b/Library/Homebrew/dev-cmd/mirror.rb
index 5ffaa7607..162008123 100644
--- a/Library/Homebrew/dev-cmd/mirror.rb
+++ b/Library/Homebrew/dev-cmd/mirror.rb
@@ -1,6 +1,6 @@
-# Mirrors the stable URL for a formula on Bintray.
-#
-# Usage: brew mirror <formula> [<formula> ...]
+#: @hide_from_man_page
+#:  * `mirror` [`--test`] <formula-name> [<formula-name> ...]:
+#:    Reuploads the stable URL for a formula to Bintray to use it as a mirror.
 
 module Homebrew
   def mirror
diff --git a/Library/Homebrew/dev-cmd/test-bot.rb b/Library/Homebrew/dev-cmd/test-bot.rb
index a3bd2d4a5..154ac5958 100644
--- a/Library/Homebrew/dev-cmd/test-bot.rb
+++ b/Library/Homebrew/dev-cmd/test-bot.rb
@@ -1,37 +1,81 @@
-# Comprehensively test a formula or pull request.
+#: @hide_from_man_page
+#:  * `test-bot` [options]  <url|formula>:
+#:    Creates a pull request to boneyard a formula.
+#:
+#:    If `--dry-run` is passed, print what would be done rather than doing
+#:    it.
+#:
+#:    If `--local` is passed, perform only local operations (i.e. don't
+#:    push or create PR).
+#:
+#:    If `--keep-logs` is passed, write and keep log files under
+#:    `./brewbot/`.
+#:
+#:    If `--cleanup` is passed, clean all state from the Homebrew
+#:    directory. Use with care!
+#:
+#:    If `--clean-cache` is passed, remove all cached downloads. Use with
+#:    care!
+#:
+#:    If `--skip-setup` is passed, don't check the local system is setup
+#:    correctly.
+#:
+#:    If `--skip-homebrew` is passed, don't check Homebrew's files and
+#:    tests are all valid.
+#:
+#:    If `--junit` is passed, generate a JUnit XML test results file.
+#:
+#:    If `--no-bottle` is passed, run `brew install` without
+#:    `--build-bottle`.
+#:
+#:    If `--keep-old` is passed, run `brew bottle --keep-old` to build new
+#:    bottles for a single platform.
+#:
+#:    If `--skip-relocation` is passed, run
+#:   `brew bottle --skip-relocation` to build new bottles that don't
+#:    require relocation.
+#:
+#:    If `--HEAD` is passed, run `brew install` with `--HEAD`.
+#:
+#:    If `--local` is passed, ask Homebrew to write verbose logs under
+#:    `./logs/` and set `$HOME` to `./home/`.
+#:
+#:    If `--tap=<tap>` is passed, use the `git` repository of the given
+#:    tap.
+#:
+#:    If `--dry-run` is passed, just print commands, don't run them.
+#:
+#:    If `--fail-fast` is passed, immediately exit on a failing step.
+#:
+#:    If `--verbose` is passed, print test step output in real time. Has
+#:    the side effect of passing output as raw bytes instead of
+#:    re-encoding in UTF-8.
+#:
+#:    If `--fast` is passed, don't install any packages, but run e.g.
+#:    `brew audit` anyway.
+#:
+#:    If `--keep-tmp` is passed, keep temporary files written by main
+#:    installs and tests that are run.
+#:
+#:    If `--no-pull` is passed, don't use `brew pull` when possible.
+#:
+#:    If `--coverage` is passed, generate coverage report and send it to
+#:    Coveralls.
+#:
+#:    If `--ci-master` is passed, use the Homebrew master branch CI
+#:    options.
+#:
+#:    If `--ci-pr` is passed, use the Homebrew pull request CI options.
+#:
+#:    If `--ci-testing` is passed, use the Homebrew testing CI options.
+#:
+#:    If `--ci-upload` is passed, use the Homebrew CI bottle upload
+#:    options.
+#:
 #
-# Usage: brew test-bot [options...] <pull-request|formula>
-#
-# Options:
-# --keep-logs:           Write and keep log files under ./brewbot/.
-# --cleanup:             Clean the Homebrew directory. Very dangerous. Use with care.
-# --clean-cache:         Remove all cached downloads. Use with care.
-# --skip-setup:          Don't check the local system is setup correctly.
-# --skip-homebrew:       Don't check Homebrew's files and tests are all valid.
-# --junit:               Generate a JUnit XML test results file.
-# --no-bottle:           Run brew install without --build-bottle.
-# --keep-old:            Run brew bottle --keep-old to build new bottles for a single platform.
-# --skip-relocation:     Run brew bottle --skip-relocation to build new bottles for homebrew/portable.
-# --HEAD:                Run brew install with --HEAD.
-# --local:               Ask Homebrew to write verbose logs under ./logs/ and set HOME to ./home/.
-# --tap=<tap>:           Use the git repository of the given tap.
-# --dry-run:             Just print commands, don't run them.
-# --fail-fast:           Immediately exit on a failing step.
-# --verbose:             Print test step output in realtime. Has the side effect of passing output
-#                        as raw bytes instead of re-encoding in UTF-8.
-# --fast:                Don't install any packages, but run e.g. audit anyway.
-# --keep-tmp:            Keep temporary files written by main installs and tests that are run.
-# --no-pull:             Don't use `brew pull` when possible.
-# --coverage:            Generate coverage report and send it to Coveralls.
-#
-# --ci-master:           Shortcut for Homebrew master branch CI options.
-# --ci-pr:               Shortcut for Homebrew pull request CI options.
-# --ci-testing:          Shortcut for Homebrew testing CI options.
-# --ci-upload:           Homebrew CI bottle upload.
-#
-# Influential environment variables include:
-# TRAVIS_REPO_SLUG: same as --tap
-# GIT_URL: if set to URL of a tap remote, same as --tap
+#:    Influential environment variables include:
+#:    `TRAVIS_REPO_SLUG`: same as `--tap`
+#:    `GIT_URL`: if set to URL of a tap remote, same as `--tap`
 
 require "formula"
 require "utils"
diff --git a/Library/Homebrew/dev-cmd/update-test.rb b/Library/Homebrew/dev-cmd/update-test.rb
index cb2120216..1f8d0510b 100644
--- a/Library/Homebrew/dev-cmd/update-test.rb
+++ b/Library/Homebrew/dev-cmd/update-test.rb
@@ -1,12 +1,18 @@
+#: @hide_from_man_page
+#:  * `update-test` [`--commit=<sha1>`] [`--before=<date>`] [`--keep-tmp`]:
+#:    Runs a test of `brew update` with a new repository clone.
+#:
+#:    If no arguments are passed, use `origin/master` as the start commit.
+#:
+#:    If `--commit=<sha1>` is passed, use `<sha1>` as the start commit.
+#:
+#:    If `--before=<date>` is passed, use the commit at `<date>` as the
+#:    start commit.
+#:
+#:    If `--keep-tmp` is passed, retain the temporary directory containing
+#:    the new repository clone.
+
 module Homebrew
-  #
-  # Usage:
-  #    brew update-test                 # using origin/master as start commit
-  #    brew update-test --commit=<sha1> # using <sha1> as start commit
-  #    brew update-test --before=<date> # using commit at <date> as start commit
-  #
-  # Options:
-  #   --keep-tmp      Retain temporary directory containing the new clone
   def update_test
     cd HOMEBREW_REPOSITORY
     start_sha1 = if commit = ARGV.value("commit")