Add `--help` to all developer commands.

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

7 files changed, 61 insertions, 27 deletions

diff --git a/Library/Homebrew/cmd/bottle.rb b/Library/Homebrew/cmd/bottle.rb
index 138e482e0..1980fbe9d 100644
--- a/Library/Homebrew/cmd/bottle.rb
+++ b/Library/Homebrew/cmd/bottle.rb
@@ -1,3 +1,10 @@
+#: @hide_from_man_page
+#:  * `bottle` [`--verbose`] [`--no-rebuild`] [`--keep-old`] [`--skip-relocation`] [`--root-url=<root_url>`]:
+#:  * `bottle` `--merge` [`--no-commit`] [`--keep-old`] [`--write`]:
+#:
+#:    Generate a bottle (binary package) from a formula installed with
+#:    `--build-bottle`.
+
 require "formula"
 require "utils/bottles"
 require "tab"
diff --git a/Library/Homebrew/cmd/man.rb b/Library/Homebrew/cmd/man.rb
index c873e7568..6754a15f2 100644
--- a/Library/Homebrew/cmd/man.rb
+++ b/Library/Homebrew/cmd/man.rb
@@ -1,3 +1,7 @@
+#: @hide_from_man_page
+#:  * `man`:
+#:    Generate Homebrew's manpages.
+
 require "formula"
 require "erb"
 require "ostruct"
diff --git a/Library/Homebrew/cmd/postinstall.rb b/Library/Homebrew/cmd/postinstall.rb
index 325916d86..71b71b3f5 100644
--- a/Library/Homebrew/cmd/postinstall.rb
+++ b/Library/Homebrew/cmd/postinstall.rb
@@ -1,3 +1,6 @@
+#:  * `postinstall` <formula>:
+#:    Rerun the post-install steps for <formula>.
+
 require "sandbox"
 
 module Homebrew
diff --git a/Library/Homebrew/cmd/pull.rb b/Library/Homebrew/cmd/pull.rb
index a40ff170e..341eed34a 100644
--- a/Library/Homebrew/cmd/pull.rb
+++ b/Library/Homebrew/cmd/pull.rb
@@ -1,26 +1,35 @@
-# Gets a patch from a GitHub commit or pull request and applies it to Homebrew.
-# Optionally, installs the formulae changed by the patch.
-#
-# Usage: brew pull [options...] <patch-source> [<patch-source> ...]
-#
-# Each <patch-source> may be one of:
-#   * The ID number of a PR (Pull Request) in the homebrew/core GitHub repo
-#   * The URL of a PR on GitHub, using either the web page or API URL
-#       formats. In this form, the PR may be on homebrew/brew, homebrew/core, or
-#       any tap.
-#   * The URL of a commit on GitHub
-#   * A "brew.sh/job/..." string specifying a testing job ID
-#
-# Options:
-#   --bottle:      Handle bottles, pulling the bottle-update commit and publishing files on Bintray
-#   --bump:        For one-formula PRs, automatically reword commit message to our preferred format
-#   --clean:       Do not rewrite or otherwise modify the commits found in the pulled PR
-#   --ignore-whitespace: Silently ignore whitespace discrepancies when applying diffs
-#   --resolve:     When a patch fails to apply, leave in progress and allow user to
-#                  resolve, instead of aborting
-#   --branch-okay: Do not warn if pulling to a branch besides master (useful for testing)
-#   --no-pbcopy:   Do not copy anything to the system clipboard
-#   --no-publish:  Do not publish bottles to Bintray
+#: @hide_from_man_page
+#: `pull` [`--bottle`] [`--bump`] [`--clean`] [`--ignore-whitespace`] [`--resolve`] [`--branch-okay`] [`--no-pbcopy`] [`--no-publish`] <patch-source> [<patch-source>]
+#:
+#:    Gets a patch from a GitHub commit or pull request and applies it to Homebrew.
+#:    Optionally, installs the formulae changed by the patch.
+#:
+#:
+#:    Each <patch-source> may be one of:
+#:      * The ID number of a PR (Pull Request) in the homebrew/core GitHub
+#:        repository
+#:      * The URL of a PR on GitHub, using either the web page or API URL
+#:        formats. In this form, the PR may be on Homebrew/brew,
+#:        Homebrew/homebrew-core or any tap.
+#:      * The URL of a commit on GitHub
+#:      * A "http://bot.brew.sh/job/..." string specifying a testing job ID
+#:
+#:   If `--bottle` was passed, handle bottles, pulling the bottle-update
+#:   commit and publishing files on Bintray.
+#:   If `--bump` was passed, for one-formula PRs, automatically reword
+#:   commit message to our preferred format.
+#:   If `--clean` was passed, do not rewrite or otherwise modify the
+#:   commits found in the pulled PR.
+#:   If `--ignore-whitespace` was passed, silently ignore whitespace
+#:   discrepancies when applying diffs.
+#:   If `--resolve` was passed, when a patch fails to apply, leave in
+#:   progress and allow user to
+#:                  resolve, instead of aborting.
+#:   If `--branch-okay` was passed, do not warn if pulling to a branch
+#:   besides master (useful for testing).
+#:   If `--no-pbcopy` was passed, do not copy anything to the system
+#    clipboard.
+#:   If `--no-publish` was passed, do not publish bottles to Bintray.
 
 require "net/http"
 require "net/https"
diff --git a/Library/Homebrew/cmd/readall.rb b/Library/Homebrew/cmd/readall.rb
index 62cdfa5d4..132472b70 100644
--- a/Library/Homebrew/cmd/readall.rb
+++ b/Library/Homebrew/cmd/readall.rb
@@ -1,7 +1,10 @@
-# `brew readall` tries to import all formulae one-by-one.
-# This can be useful for debugging issues across all formulae
-# when making significant changes to formula.rb,
-# or to determine if any current formulae have Ruby issues
+#: @hide_from_man_page
+#:  * `readall` [tap]:
+#:    Import all formulae in a tap (defaults to core tap).
+#:
+#:    This can be useful for debugging issues across all formulae
+#:    when making significant changes to `formula.rb`,
+#:    or to determine if any current formulae have Ruby issues
 
 require "readall"
 
diff --git a/Library/Homebrew/cmd/tap-readme.rb b/Library/Homebrew/cmd/tap-readme.rb
index 032ec2b79..ad115a53e 100644
--- a/Library/Homebrew/cmd/tap-readme.rb
+++ b/Library/Homebrew/cmd/tap-readme.rb
@@ -1,3 +1,7 @@
+#: @hide_from_man_page
+#:  * `tap_readme` [`-v`] <name>:
+#:    Generate the README.md file for a new tap.
+
 module Homebrew
   def tap_readme
     name = ARGV.first
diff --git a/Library/Homebrew/cmd/update-report.rb b/Library/Homebrew/cmd/update-report.rb
index 45d9f4f4a..8baae878c 100644
--- a/Library/Homebrew/cmd/update-report.rb
+++ b/Library/Homebrew/cmd/update-report.rb
@@ -1,3 +1,7 @@
+#: @hide_from_man_page
+#:  * `update_report`:
+#:    The Ruby implementation of `brew update`. Never called manually.
+
 require "formula_versions"
 require "migrator"
 require "formulary"