From e996422d3ae2b2b8d68adb1598a18fee22ef8fae Mon Sep 17 00:00:00 2001
From: Isaac Corbrey <icorbrey@apterainc.com>
Date: Tue, 28 Jul 2020 05:19:58 -0900
Subject: [PATCH 1/2] fix: Clarify test name filter usage

Set aside description of the usage example in the top description section and added a more consise example in the example section at the bottom of the man page.
---
 src/doc/man/cargo-test.adoc | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/src/doc/man/cargo-test.adoc b/src/doc/man/cargo-test.adoc
index 32aa5ff6688..ba338b12bfb 100644
--- a/src/doc/man/cargo-test.adoc
+++ b/src/doc/man/cargo-test.adoc
@@ -21,8 +21,10 @@ dashes (`--`) are passed to the test binaries and thus to _libtest_ (rustc's
 built in unit-test and micro-benchmarking framework).  If you're passing
 arguments to both Cargo and the binary, the ones after `--` go to the binary,
 the ones before go to Cargo.  For details about libtest's arguments see the
-output of `cargo test \-- --help`.  As an example, this will run all tests with
-`foo` in their name on 3 threads in parallel:
+output of `cargo test \-- --help`.
+
+As an example, this will filter for tests with `foo` in their name and run them
+on 3 threads in parallel:
 
     cargo test foo -- --test-threads 3
 
@@ -152,6 +154,10 @@ include::section-exit-status.adoc[]
 
     cargo test
 
+. Run only tests whose names match against a filter string:
+
+    cargo test name_filter
+
 . Run only a specific test within a specific integration test:
 
     cargo test --test int_test_name -- modname::test_name

From c666342acadd6f9b3c7e77b90ec6bee9bb8e2cee Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Tue, 28 Jul 2020 11:18:02 -0700
Subject: [PATCH 2/2] Rebuild generated man pages.

---
 src/doc/man/generated/cargo-test.html | 15 +++++++++++++--
 src/etc/man/cargo-test.1              | 27 +++++++++++++++++++++++----
 2 files changed, 36 insertions(+), 6 deletions(-)

diff --git a/src/doc/man/generated/cargo-test.html b/src/doc/man/generated/cargo-test.html
index aefe8d37ff0..ee87f3cba85 100644
--- a/src/doc/man/generated/cargo-test.html
+++ b/src/doc/man/generated/cargo-test.html
@@ -22,8 +22,11 @@ <h2 id="cargo_test_description">DESCRIPTION</h2>
 built in unit-test and micro-benchmarking framework).  If you&#8217;re passing
 arguments to both Cargo and the binary, the ones after <code>--</code> go to the binary,
 the ones before go to Cargo.  For details about libtest&#8217;s arguments see the
-output of <code>cargo test -- --help</code>.  As an example, this will run all tests with
-<code>foo</code> in their name on 3 threads in parallel:</p>
+output of <code>cargo test -- --help</code>.</p>
+</div>
+<div class="paragraph">
+<p>As an example, this will filter for tests with <code>foo</code> in their name and run them
+on 3 threads in parallel:</p>
 </div>
 <div class="literalblock">
 <div class="content">
@@ -581,6 +584,14 @@ <h2 id="cargo_test_examples">EXAMPLES</h2>
 </div>
 </li>
 <li>
+<p>Run only tests whose names match against a filter string:</p>
+<div class="literalblock">
+<div class="content">
+<pre>cargo test name_filter</pre>
+</div>
+</div>
+</li>
+<li>
 <p>Run only a specific test within a specific integration test:</p>
 <div class="literalblock">
 <div class="content">
diff --git a/src/etc/man/cargo-test.1 b/src/etc/man/cargo-test.1
index 0f967958fc7..bbcc99186ca 100644
--- a/src/etc/man/cargo-test.1
+++ b/src/etc/man/cargo-test.1
@@ -2,12 +2,12 @@
 .\"     Title: cargo-test
 .\"    Author: [see the "AUTHOR(S)" section]
 .\" Generator: Asciidoctor 2.0.10
-.\"      Date: 2020-06-25
+.\"      Date: 2020-07-28
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "CARGO\-TEST" "1" "2020-06-25" "\ \&" "\ \&"
+.TH "CARGO\-TEST" "1" "2020-07-28" "\ \&" "\ \&"
 .ie \n(.g .ds Aq \(aq
 .el       .ds Aq '
 .ss \n[.ss] 0
@@ -41,8 +41,10 @@ dashes (\fB\-\-\fP) are passed to the test binaries and thus to \fIlibtest\fP (r
 built in unit\-test and micro\-benchmarking framework).  If you\(cqre passing
 arguments to both Cargo and the binary, the ones after \fB\-\-\fP go to the binary,
 the ones before go to Cargo.  For details about libtest\(cqs arguments see the
-output of \fBcargo test \-\- \-\-help\fP.  As an example, this will run all tests with
-\fBfoo\fP in their name on 3 threads in parallel:
+output of \fBcargo test \-\- \-\-help\fP.
+.sp
+As an example, this will filter for tests with \fBfoo\fP in their name and run them
+on 3 threads in parallel:
 .sp
 .if n .RS 4
 .nf
@@ -678,6 +680,23 @@ cargo test
 .  sp -1
 .  IP " 2." 4.2
 .\}
+Run only tests whose names match against a filter string:
+.sp
+.if n .RS 4
+.nf
+cargo test name_filter
+.fi
+.if n .RE
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 3.\h'+01'\c
+.\}
+.el \{\
+.  sp -1
+.  IP " 3." 4.2
+.\}
 Run only a specific test within a specific integration test:
 .sp
 .if n .RS 4