10 files changed, 14 insertions, 15 deletions
diff --git a/Library/Homebrew/cmd/cleanup.rb b/Library/Homebrew/cmd/cleanup.rb
index 5b46e0872..126309579 100644
--- a/Library/Homebrew/cmd/cleanup.rb
+++ b/Library/Homebrew/cmd/cleanup.rb
@@ -7,7 +7,7 @@
 #:    If `--dry-run` or `-n` is passed, show what would be removed, but do not
 #:    actually remove anything.
 #:
-#:    If `-s` is passed, scrubs the cache, removing downloads for even the latest
+#:    If `-s` is passed, scrub the cache, removing downloads for even the latest
 #:    versions of formulae. Note downloads for any installed formulae will still not be
 #:    deleted. If you want to delete those too: `rm -rf $(brew --cache)`
 
diff --git a/Library/Homebrew/cmd/desc.rb b/Library/Homebrew/cmd/desc.rb
index 3ef02288b..53291602e 100644
--- a/Library/Homebrew/cmd/desc.rb
+++ b/Library/Homebrew/cmd/desc.rb
@@ -1,11 +1,10 @@
 #:  * `desc` <formula>:
 #:    Display <formula>'s name and one-line description.
 #:
-#:  * `desc` [`-s`|`-n`|`-d`] <pattern>:
+#:  * `desc` [`-s`|`-n`|`-d`] (<text>|`/`<text>`/`):
 #:    Search both name and description (`-s`), just the names (`-n`), or just  the
-#:    descriptions (`-d`) for `<pattern>`. `<pattern>` is by default interpreted
-#:    as a literal string; if flanked by slashes, it is instead interpreted as a
-#:    regular expression. Formula descriptions are cached; the cache is created on
+#:    descriptions (`-d`) for <text>. If <text> is flanked by slashes, it is interpreted
+#:    as a regular expression. Formula descriptions are cached; the cache is created on
 #:    the first search, making that search slower than subsequent ones.
 
 require "descriptions"
diff --git a/Library/Homebrew/cmd/info.rb b/Library/Homebrew/cmd/info.rb
index 1850ae003..b06d99466 100644
--- a/Library/Homebrew/cmd/info.rb
+++ b/Library/Homebrew/cmd/info.rb
@@ -4,7 +4,7 @@
 #:  * `info` `--github` <formula>:
 #:    Open a browser to the GitHub History page for formula <formula>.
 #:
-#:    To view formula history locally: `brew log -p <formula>`.
+#:    To view formula history locally: `brew log -p <formula>`
 #:
 #:  * `info` `--json=`<version> (`--all`|`--installed`|<formulae>):
 #:    Print a JSON representation of <formulae>. Currently the only accepted value
@@ -13,7 +13,7 @@
 #:    Pass `--all` to get information on all formulae, or `--installed` to get
 #:    information on all installed formulae.
 #:
-#:    See the docs for examples of using the JSON:
+#:    See the docs for examples of using the JSON output:
 #:    <http://docs.brew.sh/Querying-Brew.html>
 
 require "blacklist"
diff --git a/Library/Homebrew/cmd/outdated.rb b/Library/Homebrew/cmd/outdated.rb
index 9ed7a0f79..a18f4e399 100644
--- a/Library/Homebrew/cmd/outdated.rb
+++ b/Library/Homebrew/cmd/outdated.rb
@@ -1,4 +1,4 @@
-#:  * `outdated` [`--quiet`|`--verbose`|`--json=v1`] [`--fetch-HEAD`]:
+#:  * `outdated` [`--quiet`|`--verbose`|`--json=`<version>] [`--fetch-HEAD`]:
 #:    Show formulae that have an updated version available.
 #:
 #:    By default, version information is displayed in interactive shells, and
diff --git a/Library/Homebrew/cmd/readall.rb b/Library/Homebrew/cmd/readall.rb
index 7c1a085c9..3591e0c09 100644
--- a/Library/Homebrew/cmd/readall.rb
+++ b/Library/Homebrew/cmd/readall.rb
@@ -4,7 +4,7 @@
 #:
 #:    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
+#:    or to determine if any current formulae have Ruby issues.
 
 require "readall"
 
diff --git a/Library/Homebrew/cmd/search.rb b/Library/Homebrew/cmd/search.rb
index d69164eb9..e834a00b5 100644
--- a/Library/Homebrew/cmd/search.rb
+++ b/Library/Homebrew/cmd/search.rb
@@ -2,7 +2,7 @@
 #:    Display all locally available formulae for brewing (including tapped ones).
 #:    No online search is performed if called without arguments.
 #:
-#:  * `search` [`--desc`] <text>|`/`<text>`/`:
+#:  * `search` [`--desc`] (<text>|`/`<text>`/`):
 #:    Perform a substring search of formula names for <text>. If <text> is
 #:    surrounded with slashes, then it is interpreted as a regular expression.
 #:    The search for <text> is extended online to some popular taps.
diff --git a/Library/Homebrew/cmd/tap-info.rb b/Library/Homebrew/cmd/tap-info.rb
index b46de30c1..225b70097 100644
--- a/Library/Homebrew/cmd/tap-info.rb
+++ b/Library/Homebrew/cmd/tap-info.rb
@@ -12,7 +12,7 @@
 #:
 #:    Pass `--installed` to get information on installed taps.
 #:
-#:    See the docs for examples of using the JSON:
+#:    See the docs for examples of using the JSON output:
 #:    <http://docs.brew.sh/Querying-Brew.html>
 
 require "tap"
diff --git a/Library/Homebrew/cmd/unlink.rb b/Library/Homebrew/cmd/unlink.rb
index a105f9c56..3f858b2c4 100644
--- a/Library/Homebrew/cmd/unlink.rb
+++ b/Library/Homebrew/cmd/unlink.rb
@@ -1,7 +1,7 @@
 #:  * `unlink` [`--dry-run`] <formula>:
 #:    Remove symlinks for <formula> from the Homebrew prefix. This can be useful
 #:    for temporarily disabling a formula:
-#:    `brew unlink foo && commands && brew link foo`.
+#:    `brew unlink <formula> && <commands> && brew link <formula>`
 #:
 #:    If `--dry-run` or `-n` is passed, Homebrew will list all files which would
 #:    be unlinked, but will not actually unlink or delete any files.
diff --git a/Library/Homebrew/cmd/unpack.rb b/Library/Homebrew/cmd/unpack.rb
index 4e6584e70..60d796d9f 100644
--- a/Library/Homebrew/cmd/unpack.rb
+++ b/Library/Homebrew/cmd/unpack.rb
@@ -1,7 +1,7 @@
 #:  * `unpack` [`--git`|`--patch`] [`--destdir=`<path>] <formulae>:
 #:    Unpack the source files for <formulae> into subdirectories of the current
 #:    working directory. If `--destdir=`<path> is given, the subdirectories will
-#:    be created in the directory named by `<path>` instead.
+#:    be created in the directory named by <path> instead.
 #:
 #:    If `--patch` is passed, patches for <formulae> will be applied to the
 #:    unpacked source.
diff --git a/Library/Homebrew/cmd/uses.rb b/Library/Homebrew/cmd/uses.rb
index 5f6611dfc..b1122c90a 100644
--- a/Library/Homebrew/cmd/uses.rb
+++ b/Library/Homebrew/cmd/uses.rb
@@ -12,8 +12,8 @@
 #:    `--include-build`. Similarly, pass `--include-optional` to include `:optional`
 #:    dependencies. To skip `:recommended` type dependencies, pass `--skip-recommended`.
 #:
-#:    By default, `uses` shows usages of `formula` by stable builds. To find
-#:    cases where `formula` is used by development or HEAD build, pass
+#:    By default, `uses` shows usages of <formulae> by stable builds. To find
+#:    cases where <formulae> is used by development or HEAD build, pass
 #:    `--devel` or `--HEAD`.
 
 require "formula"