Test attributes deserve their own section

Author: Havvy

src/attributes.md

@@ -121,11 +121,6 @@ names have meaning.
 
 ## Function-only attributes
 
-- `test` - indicates that this function is a test function, to only be compiled
-  in case of `--test`.
-  - `ignore` - indicates that this test function is disabled.
-- `should_panic` - indicates that this test function should panic, inverting the
-  success condition.
 - `cold` - The function is unlikely to be executed, so optimize it (and calls
   to it) differently.
 
@@ -228,6 +223,42 @@ are transformed into `doc` attributes.
 
 See [The Rustdoc Book] for reference material on this attribute.
 
+### Testing
+
+The compiler comes with a default test framework. It works by attributing
+functions with the `test` attribute. These functions are only compiled when
+compiling with the test harness. Like [main], functions annotated with this
+attribute must take no arguments, must not declare any
+[trait or lifetime bounds], must not have any [where clauses], and its return
+type must be one of the following:
+
+* `()`
+<!-- * `!` -->
+* `Result<(), E> where E: Error`
+<!-- * Result<!, E> where E: Error` -->
+
+> Note: The implementation of which return types are allowed is determined by
+> the unstable [`Termination`] trait.
+
+<!-- If the previous section needs updating (from "must take no arguments"
+  onwards, also update it in the crates-and-source-files.md file -->
+
+> Note: The test harness is ran by passing the `--test` argument to `rustc` or
+> using `cargo test`.
+
+Tests that return `()` pass as long as they terminate do not panic. Tests that
+return a `Result` pass as long as they return `Ok(())`. Tests that do not
+terminate neither pass nor fail.
+
+A function annotated with the `test` attribute can also be annotated with the
+`ignore` attribute. The *`ignore` attribute* tells the test harness to not
+execute that function as a test. It will still only be compiled when compiling
+with the test harness.
+
+A function annotated with the `test` attribute that returns `()` can also be
+annotated with the `should_panic` attribute. The *`should_panic` attribute*
+makes the test only pass if it actually panics.
+
 ### Conditional compilation
 
 Sometimes one wants to have different compiler outputs from the same code,
@@ -570,4 +601,8 @@ You can implement `derive` for your own type through [procedural macros].
 [modules]: items/modules.html
 [statements]: statements.html
 [match expressions]: expressions/match-expr.html
-[external blocks]: items/external-blocks.html
+[external blocks]: items/external-blocks.html
+[main]: crates-and-source-files.html
+[`Termination`]: ../std/process/trait.Termination.html
+[where clause]: items/where-clauses.html
+[trait or lifetime bounds]: trait-bounds.html

src/crates-and-source-files.md

@@ -68,16 +68,20 @@ apply to the crate as a whole.
 
 A crate that contains a `main` [function] can be compiled to an executable. If a
 `main` function is present, it must take no arguments, must not declare any
-[trait or lifetime bounds], must not have any [where clauses], and  its return
+[trait or lifetime bounds], must not have any [where clauses], and its return
 type must  be one of the following:
 
 * `()`
 <!-- * `!` -->
-* `Result<T, E> where T: on this list, E: Error`
+* `Result<(), E> where E: Error`
+<!-- * Result<!, E> where E: Error` -->
 
 > Note: The implementation of which return types are allowed is determined by
 > the unstable [`Termination`] trait.
 
+<!-- If the previous section needs updating (from "must take no arguments"
+  onwards, also update it in the attributes.md file, testing section -->
+
 The optional [_UTF8 byte order mark_] (UTF8BOM production) indicates that the
 file is encoded in UTF8. It can only occur at the beginning of the file and
 is ignored by the compiler.