diff --git a/src/attributes/testing.md b/src/attributes/testing.md index e0181b1c3..63df999ad 100644 --- a/src/attributes/testing.md +++ b/src/attributes/testing.md @@ -9,16 +9,12 @@ enables the [`test` conditional compilation option]. The *`test` attribute* marks a function to be executed as a test. These functions are only compiled when in test mode. Test functions must be free, -monomorphic functions that take no arguments, and the return type must be one -of the following: +monomorphic functions that take no arguments, and the return type must implement the [`Termination`] trait, for example: * `()` -* `Result<(), E> where E: Error` - - - -> Note: The implementation of which return types are allowed is determined by -> the unstable [`Termination`] trait. +* `Result<(), E> where E: Debug` +* `!` + @@ -26,9 +22,12 @@ of the following: > Note: The test mode is enabled by passing the `--test` argument to `rustc` > or using `cargo test`. -Tests that return `()` pass as long as they terminate and do not panic. Tests -that return a `Result<(), E>` pass as long as they return `Ok(())`. Tests that -do not terminate neither pass nor fail. +The test harness calls the returned value's [`report`] method, and classifies the test as passed or failed depending on whether the resulting [`ExitCode`] represents successful termination. +In particular: +* Tests that return `()` pass as long as they terminate and do not panic. +* Tests that return a `Result<(), E>` pass as long as they return `Ok(())`. +* Tests that return `ExitCode::SUCCESS` pass, and tests that return `ExitCode::FAILURE` fail. +* Tests that do not terminate neither pass nor fail. ```rust # use std::io; @@ -85,5 +84,7 @@ fn mytest() { [_MetaListNameValueStr_]: ../attributes.md#meta-item-attribute-syntax [_MetaNameValueStr_]: ../attributes.md#meta-item-attribute-syntax [`Termination`]: ../../std/process/trait.Termination.html +[`report`]: ../../std/process/trait.Termination.html#tymethod.report [`test` conditional compilation option]: ../conditional-compilation.md#test [attributes]: ../attributes.md +[`ExitCode`]: ../../std/process/struct.ExitCode.html diff --git a/src/crates-and-source-files.md b/src/crates-and-source-files.md index 494e4543e..6922b0ee3 100644 --- a/src/crates-and-source-files.md +++ b/src/crates-and-source-files.md @@ -103,15 +103,30 @@ This section has been moved to the [Preludes chapter](names/preludes.md). 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 -type must be one of the following: +type must implement the [`Termination`] trait. -* `()` -* `Result<(), E> where E: Error` - - +```rust +fn main() {} +``` +```rust +fn main() -> ! { + std::process::exit(0); +} +``` +```rust +fn main() -> impl std::process::Termination { + std::process::ExitCode::SUCCESS +} +``` -> Note: The implementation of which return types are allowed is determined by -> the unstable [`Termination`] trait. +> **Note**: Types with implementations of [`Termination`] in the standard library include: +> +> * `()` +> * [`!`] +> * [`ExitCode`] +> * `Result<(), E> where E: Debug` +> * `Result where E: Debug` + @@ -143,11 +158,13 @@ or `_` (U+005F) characters. in the Owens and Flatt module system, or a *configuration* in Mesa. [Unicode alphanumeric]: ../std/primitive.char.html#method.is_alphanumeric +[`!`]: types/never.md [_InnerAttribute_]: attributes.md [_Item_]: items.md [_MetaNameValueStr_]: attributes.md#meta-item-attribute-syntax [_shebang_]: https://en.wikipedia.org/wiki/Shebang_(Unix) [_utf8 byte order mark_]: https://en.wikipedia.org/wiki/Byte_order_mark#UTF-8 +[`ExitCode`]: ../std/process/struct.ExitCode.html [`Termination`]: ../std/process/trait.Termination.html [attribute]: attributes.md [attributes]: attributes.md diff --git a/src/special-types-and-traits.md b/src/special-types-and-traits.md index 4bb4e6599..ca53b3c9a 100644 --- a/src/special-types-and-traits.md +++ b/src/special-types-and-traits.md @@ -92,6 +92,10 @@ The [`Sync`] trait indicates that a value of this type is safe to share between multiple threads. This trait must be implemented for all types used in immutable [`static` items]. +## `Termination` + +The [`Termination`] trait indicates the acceptable return types for the [main function] and [test functions]. + ## Auto traits The [`Send`], [`Sync`], [`Unpin`], [`UnwindSafe`], and [`RefUnwindSafe`] traits are _auto @@ -151,6 +155,7 @@ These implicit `Sized` bounds may be relaxed by using the special `?Sized` bound [`std::cmp`]: ../std/cmp/index.html [`std::marker::PhantomData`]: ../std/marker/struct.PhantomData.html [`std::ops`]: ../std/ops/index.html +[`Termination`]: ../std/process/trait.Termination.html [`UnwindSafe`]: ../std/panic/trait.UnwindSafe.html [`Sync`]: ../std/marker/trait.Sync.html [`Unpin`]: ../std/marker/trait.Unpin.html @@ -168,11 +173,13 @@ These implicit `Sized` bounds may be relaxed by using the special `?Sized` bound [implementation items]: items/implementations.md [indexing expressions]: expressions/array-expr.md#array-and-slice-indexing-expressions [interior mutability]: interior-mutability.md +[main function]: crates-and-source-files.md#main-functions [Methods]: items/associated-items.md#associated-functions-and-methods [method resolution]: expressions/method-call-expr.md [operators]: expressions/operator-expr.md [orphan rules]: items/implementations.md#trait-implementation-coherence [`static` items]: items/static-items.md +[test functions]: attributes/testing.md#the-test-attribute [the standard library]: ../std/index.html [trait object]: types/trait-object.md [Tuples]: types/tuple.md