diff --git a/Library/Homebrew/cmd/bottle.rb b/Library/Homebrew/cmd/bottle.rb
index 138e482e0d..1980fbe9d4 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 c873e75680..6754a15f26 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 325916d864..71b71b3f5a 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 a40ff170ee..341eed34a8 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 62cdfa5d4d..132472b704 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 032ec2b79e..ad115a53e9 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 45d9f4f4af..8baae878c4 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"
diff --git a/Library/Homebrew/dev-cmd/aspell-dictionaries.rb b/Library/Homebrew/dev-cmd/aspell-dictionaries.rb
index 754b6614ed..16ec91835b 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 b478be6098..890c9c4a08 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 8ee0e87dfc..993420c024 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 5ffaa7607c..162008123c 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 a3bd2d4a58..154ac5958c 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 cb2120216c..1f8d0510ba 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")
diff --git a/Library/Homebrew/test/test_integration_cmds.rb b/Library/Homebrew/test/test_integration_cmds.rb
index c83d7522a1..9ea3053442 100644
--- a/Library/Homebrew/test/test_integration_cmds.rb
+++ b/Library/Homebrew/test/test_integration_cmds.rb
@@ -273,10 +273,8 @@ class IntegrationCommandTests < Homebrew::TestCase
                  cmd("help", "cat")) # Internal command (documented, Ruby).
     assert_match(/^brew update /,
                  cmd("help", "update")) # Internal command (documented, Shell).
-    if ARGV.homebrew_developer?
-      assert_match "Example usage:\n",
-                   cmd("help", "test-bot") # Internal developer command (undocumented).
-    end
+    assert_match(/^brew test-bot /,
+                 cmd("help", "test-bot")) # Internal developer command (documented, Ruby).
   end
 
   def test_config
diff --git a/share/doc/homebrew/brew.1.html b/share/doc/homebrew/brew.1.html
index 7716a5abc1..cd475a3132 100644
--- a/share/doc/homebrew/brew.1.html
+++ b/share/doc/homebrew/brew.1.html
@@ -317,6 +317,7 @@ repository's HEAD will be checked for updates when a new stable or devel
 version has been released.</p></dd>
 <dt><code>pin</code> <var>formulae</var></dt><dd><p>Pin the specified <var>formulae</var>, preventing them from being upgraded when
 issuing the <code>brew upgrade</code> command. See also <code>unpin</code>.</p></dd>
+<dt><code>postinstall</code> <var>formula</var></dt><dd><p>Rerun the post-install steps for <var>formula</var>.</p></dd>
 <dt><code>prune</code> [<code>--dry-run</code>]</dt><dd><p>Remove dead symlinks from the Homebrew prefix. This is generally not
 needed, but can be useful when doing DIY installations. Also remove broken
 app symlinks from <code>/Applications</code> and <code>~/Applications</code> that were previously
diff --git a/share/man/man1/brew-cask.1 b/share/man/man1/brew-cask.1
index 483feec5eb..dd2bc133c7 100644
--- a/share/man/man1/brew-cask.1
+++ b/share/man/man1/brew-cask.1
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "BREW\-CASK" "1" "August 2016" "Homebrew" "brew-cask"
+.TH "BREW\-CASK" "1" "September 2016" "Homebrew" "brew-cask"
 .
 .SH "NAME"
 \fBbrew\-cask\fR \- a friendly binary installer for macOS
diff --git a/share/man/man1/brew.1 b/share/man/man1/brew.1
index ddd1f23ce8..41ba07e6af 100644
--- a/share/man/man1/brew.1
+++ b/share/man/man1/brew.1
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "BREW" "1" "August 2016" "Homebrew" "brew"
+.TH "BREW" "1" "September 2016" "Homebrew" "brew"
 .
 .SH "NAME"
 \fBbrew\fR \- The missing package manager for OS X
@@ -421,6 +421,10 @@ If \fB\-\-fetch\-HEAD\fR is passed, fetch the upstream repository to detect if t
 Pin the specified \fIformulae\fR, preventing them from being upgraded when issuing the \fBbrew upgrade\fR command\. See also \fBunpin\fR\.
 .
 .TP
+\fBpostinstall\fR \fIformula\fR
+Rerun the post\-install steps for \fIformula\fR\.
+.
+.TP
 \fBprune\fR [\fB\-\-dry\-run\fR]
 Remove dead symlinks from the Homebrew prefix\. This is generally not needed, but can be useful when doing DIY installations\. Also remove broken app symlinks from \fB/Applications\fR and \fB~/Applications\fR that were previously created by \fBbrew linkapps\fR\.
 .