Auto merge of #8552 - icorbrey:test-name-filtering-docs, r=ehuss

Clarify test name filter usage

I set aside the description of the usage example in the top description section and added a more concise example in the example section at the bottom of the man page. I also changed the wording of the usage example up top a bit to be more search-friendly since "filter" is a common keyword to search for.

Resolves #8282

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

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">

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