Revise editorially

The test functions within our code blocks will not actually be run in
any case, so let's mark these tests as `no_run`.

In the examples, let's demonstrate the behavior that the expected
string must be a substring of the panic message.

Let's also tighten up some wording.

Author: traviscross

src/attributes/testing.md

@@ -13,9 +13,8 @@ r[attributes.testing.test.intro]
 The *`test` [attribute][attributes]* marks a function to be executed as a test.
 
 > [!EXAMPLE]
-> ```rust
+> ```rust,no_run
 > # pub fn add(left: u64, right: u64) -> u64 { left + right }
->
 > #[test]
 > fn it_works() {
 >     let result = add(2, 2);
@@ -60,7 +59,7 @@ In particular:
 * Tests that do not terminate neither pass nor fail.
 
 > [!EXAMPLE]
-> ```rust
+> ```rust,no_run
 > # use std::io;
 > # fn setup_the_thing() -> io::Result<i32> { Ok(1) }
 > # fn do_the_thing(s: &i32) -> io::Result<()> { Ok(()) }
@@ -79,7 +78,7 @@ r[attributes.testing.ignore.intro]
 The *`ignore` [attribute][attributes]* can be used with the [`test` attribute][attributes.testing.test] to tell the test harness to not execute that function as a test.
 
 > [!EXAMPLE]
-> ```rust
+> ```rust,no_run
 > #[test]
 > #[ignore]
 > fn check_thing() {
@@ -124,10 +123,10 @@ r[attributes.testing.should_panic]
 ## The `should_panic` attribute
 
 r[attributes.testing.should_panic.intro]
-The *`should_panic` [attribute][attributes]* changes a [test function][attributes.testing.test] so that it passes only if it panics.
+The *`should_panic` [attribute][attributes]* causes a test to pass only if the [test function][attributes.testing.test] to which the attribute is applied panics.
 
 > [!EXAMPLE]
-> ```rust
+> ```rust,no_run
 > #[test]
 > #[should_panic(expected = "values don't match")]
 > fn mytest() {
@@ -136,46 +135,46 @@ The *`should_panic` [attribute][attributes]* changes a [test function][attribute
 > ```
 
 r[attributes.testing.should_panic.syntax]
-The `should_panic` attribute is specified with one of the following forms:
+The `should_panic` attribute has one of the following forms:
 
 - [MetaWord]
   > [!EXAMPLE]
-  > ```rust
+  > ```rust,no_run
   > #[test]
   > #[should_panic]
-  > fn mytest() { panic!("some message"); }
+  > fn mytest() { panic!("error: some message, and more"); }
   > ```
 
-- [MetaNameValueStr] --- This indicates that the given string should appear within the panic message.
+- [MetaNameValueStr] --- The given string must appear within the panic message for the test to pass.
   > [!EXAMPLE]
-  > ```rust
+  > ```rust,no_run
   > #[test]
   > #[should_panic = "some message"]
-  > fn mytest() { panic!("some message"); }
+  > fn mytest() { panic!("error: some message, and more"); }
   > ```
 
-- [MetaListNameValueStr] --- Specified with the key `expected`. Same behavior as [MetaNameValueStr], just with an explicit key.
+- [MetaListNameValueStr] --- As with the [MetaNameValueStr] syntax, the given string must appear within the panic message.
   > [!EXAMPLE]
-  > ```rust
+  > ```rust,no_run
   > #[test]
   > #[should_panic(expected = "some message")]
-  > fn mytest() { panic!("some message"); }
+  > fn mytest() { panic!("error: some message, and more"); }
   > ```
 
 r[attributes.testing.should_panic.allowed-positions]
-The `should_panic` attribute may be applied to functions annotated with the `test` attribute.
+The `should_panic` attribute may only be applied to functions annotated with the `test` attribute.
 
 > [!NOTE]
-> `rustc` currently warns in some other positions. This may become a hard error in the future.
+> `rustc` currently accepts this attribute in other positions with a warning. This may become a hard error in the future.
 
 r[attributes.testing.should_panic.duplicates]
-Only the first instance of `should_panic` on a function is honored. Subsequent `should_panic` attributes are ignored.
+Only the first instance of `should_panic` on a function is honored.
 
 > [!NOTE]
-> `rustc` currently ignores subsequent duplicate `should_panic` attributes. This may become an error in the future.
+> `rustc` currently ignores subsequent `should_panic` attributes and emits a future-compatibility warning. This may become a hard error in the future.
 
 r[attributes.testing.should_panic.expected]
-The string specified with the [MetaNameValueStr] form or the `expected` key in [MetaListNameValueStr] indicates that the string must appear somewhere within the panic message. If the string is not found in the message, then the test will fail.
+When the [MetaNameValueStr] form or the [MetaListNameValueStr] form with the `expected` key is used, the given string must appear somewhere within the panic message for the test to pass.
 
 r[attributes.testing.should_panic.return]
 The return type of the test function must be `()`.