diff --git a/Library/Homebrew/dev-cmd/bump-formula-pr.rb b/Library/Homebrew/dev-cmd/bump-formula-pr.rb
index 57f9edad798336728e6c02737ca970b9d6961cde..bd27a569c29f766df1119d69ab4c5c95a1c53424 100644
--- a/Library/Homebrew/dev-cmd/bump-formula-pr.rb
+++ b/Library/Homebrew/dev-cmd/bump-formula-pr.rb
@@ -1,16 +1,23 @@
-# Creates a pull request with the new version of a formula.
-#
-# Usage: brew bump [options...] <formula-name>
-#
-# Requires either `--url` and `--sha256` or `--tag` and `--revision`.
-#
-# Options:
-#   --dry-run:  Print what would be done rather than doing it.
-#   --devel:    Bump a `devel` rather than `stable` version.
-#   --url:      The new formula URL.
-#   --sha256:   The new formula SHA-256.
-#   --tag:      The new formula's `tag`
-#   --revision: The new formula's `revision`.
+#:  * `bump-formula-pr` [`--devel`] [`--dry-run`] `--url=`<url> `--sha256=`<sha-256> <formula>:
+#:  * `bump-formula-pr` [`--devel`] [`--dry-run`] `--tag=`<tag> `--revision=`<revision> <formula>:
+#:
+#:    Creates a pull request to update the formula with a new url or a new tag.
+#:
+#:    If a <url> is specified, the <sha-256> checksum of the new download must
+#:    also be specified.
+#:
+#:    If a <tag> is specified, the git commit <revision> corresponding to that
+#:    tag must also be specified.
+#:
+#:    If `--devel` is passed, bump the development rather than stable version.
+#:    The development spec must already exist.
+#:
+#:    If `--dry-run` is passed, print what would be done rather than doing it.
+#:
+#:    Note that this command cannot be used to transition a formula from a
+#:    url-and-sha256 style specification into a tag-and-revision style
+#:    specification, nor vice versa. It must use whichever style specification
+#:    the preexisting formula already uses.
 
 require "formula"