From f4d0a04c64e29184e0a92258618e5cbdd0937f86 Mon Sep 17 00:00:00 2001 From: Andre Bogus Date: Fri, 20 Dec 2019 07:46:29 +0100 Subject: [PATCH] Differentiate todo! and unimplemented! --- src/libcore/macros/mod.rs | 45 ++++++++++--------- .../run-fail/unimplemented-macro-panic.rs | 2 +- .../ui/consts/const-eval/const_panic.stderr | 2 +- .../const-eval/const_panic_libcore.stderr | 2 +- .../const_panic_libcore_main.stderr | 2 +- 5 files changed, 29 insertions(+), 24 deletions(-) diff --git a/src/libcore/macros/mod.rs b/src/libcore/macros/mod.rs index cf460745ffa30..6672ab8938da0 100644 --- a/src/libcore/macros/mod.rs +++ b/src/libcore/macros/mod.rs @@ -556,13 +556,15 @@ macro_rules! unreachable { }); } -/// Indicates unfinished code by panicking with a message of "not yet implemented". +/// Indicates unimplemented code by panicking with a message of "not implemented". /// /// This allows the your code to type-check, which is useful if you are prototyping or /// implementing a trait that requires multiple methods which you don't plan of using all of. /// -/// There is no difference between `unimplemented!` and `todo!` apart from the -/// name. +/// The difference between `unimplemented!` and [`todo!`](macro.todo.html) is that while `todo!` +/// conveys an intent of implementing the functionality later and the message is "not yet +/// implemented", `unimplemented!` makes no such claims. Its message is "not implemented". +/// Also some IDEs will mark `todo!`s. /// /// # Panics /// @@ -573,7 +575,7 @@ macro_rules! unreachable { /// /// # Examples /// -/// Here's an example of some in-progress code. We have a trait `Foo`: +/// Say we have a trait `Foo`: /// /// ``` /// trait Foo { @@ -583,13 +585,13 @@ macro_rules! unreachable { /// } /// ``` /// -/// We want to implement `Foo` for 'MyStruct', but so far we only know how to -/// implement the `bar()` function. `baz()` and `qux()` will still need to be defined +/// We want to implement `Foo` for 'MyStruct', but for some reason it only makes sense +/// to implement the `bar()` function. `baz()` and `qux()` will still need to be defined /// in our implementation of `Foo`, but we can use `unimplemented!` in their definitions /// to allow our code to compile. /// -/// In the meantime, we want to have our program stop running once these -/// unimplemented functions are reached. +/// We still want to have our program stop running if the unimplemented methods are +/// reached. /// /// ``` /// # trait Foo { @@ -605,19 +607,18 @@ macro_rules! unreachable { /// } /// /// fn baz(&self) { -/// // We aren't sure how to even start writing baz yet, -/// // so we have no logic here at all. -/// // This will display "thread 'main' panicked at 'not yet implemented'". +/// // It makes no sense to `baz` a `MyStruct`, so we have no logic here +/// // at all. +/// // This will display "thread 'main' panicked at 'not implemented'". /// unimplemented!(); /// } /// /// fn qux(&self) -> Result { -/// let n = self.bar(); /// // We have some logic here, -/// // so we can use unimplemented! to display what we have so far. +/// // We can add a message to unimplemented! to display our omission. /// // This will display: -/// // "thread 'main' panicked at 'not yet implemented: we need to divide by 2'". -/// unimplemented!("we need to divide by {}", n); +/// // "thread 'main' panicked at 'not implemented: MyStruct isn't quxable'". +/// unimplemented!("MyStruct isn't quxable"); /// } /// } /// @@ -629,8 +630,8 @@ macro_rules! unreachable { #[macro_export] #[stable(feature = "rust1", since = "1.0.0")] macro_rules! unimplemented { - () => (panic!("not yet implemented")); - ($($arg:tt)+) => (panic!("not yet implemented: {}", $crate::format_args!($($arg)+))); + () => (panic!("not implemented")); + ($($arg:tt)+) => (panic!("not implemented: {}", $crate::format_args!($($arg)+))); } /// Indicates unfinished code. @@ -638,8 +639,12 @@ macro_rules! unimplemented { /// This can be useful if you are prototyping and are just looking to have your /// code typecheck. /// -/// There is no difference between `unimplemented!` and `todo!` apart from the -/// name. +/// The difference between [`unimplemented!`] and `todo!` is that while `todo!` conveys +/// an intent of implementing the functionality later and the message is "not yet +/// implemented", `unimplemented!` makes no such claims. Its message is "not implemented". +/// Also some IDEs will mark `todo!`s. +/// +/// [`unimplemented!`]: macro.unimplemented.html /// /// # Panics /// @@ -682,7 +687,7 @@ macro_rules! unimplemented { /// let s = MyStruct; /// s.bar(); /// -/// // we aren't even using baz() yet, so this is fine. +/// // we aren't even using baz(), so this is fine. /// } /// ``` #[macro_export] diff --git a/src/test/run-fail/unimplemented-macro-panic.rs b/src/test/run-fail/unimplemented-macro-panic.rs index 2a848281e4f22..4d9cb740fc609 100644 --- a/src/test/run-fail/unimplemented-macro-panic.rs +++ b/src/test/run-fail/unimplemented-macro-panic.rs @@ -1,4 +1,4 @@ -// error-pattern:not yet implemented +// error-pattern:not implemented fn main() { unimplemented!() } diff --git a/src/test/ui/consts/const-eval/const_panic.stderr b/src/test/ui/consts/const-eval/const_panic.stderr index 8a51d8aa882f8..1b006c69cfd6e 100644 --- a/src/test/ui/consts/const-eval/const_panic.stderr +++ b/src/test/ui/consts/const-eval/const_panic.stderr @@ -25,7 +25,7 @@ error: any use of this value will cause an error LL | pub const X: () = unimplemented!(); | ------------------^^^^^^^^^^^^^^^^- | | - | the evaluated program panicked at 'not yet implemented', $DIR/const_panic.rs:10:19 + | the evaluated program panicked at 'not implemented', $DIR/const_panic.rs:10:19 | = note: this error originates in a macro outside of the current crate (in Nightly builds, run with -Z external-macro-backtrace for more info) diff --git a/src/test/ui/consts/const-eval/const_panic_libcore.stderr b/src/test/ui/consts/const-eval/const_panic_libcore.stderr index e76446f1015ba..abc844e984261 100644 --- a/src/test/ui/consts/const-eval/const_panic_libcore.stderr +++ b/src/test/ui/consts/const-eval/const_panic_libcore.stderr @@ -25,7 +25,7 @@ error: any use of this value will cause an error LL | const X: () = unimplemented!(); | --------------^^^^^^^^^^^^^^^^- | | - | the evaluated program panicked at 'not yet implemented', $DIR/const_panic_libcore.rs:11:15 + | the evaluated program panicked at 'not implemented', $DIR/const_panic_libcore.rs:11:15 | = note: this error originates in a macro outside of the current crate (in Nightly builds, run with -Z external-macro-backtrace for more info) diff --git a/src/test/ui/consts/const-eval/const_panic_libcore_main.stderr b/src/test/ui/consts/const-eval/const_panic_libcore_main.stderr index 22d173ad0c7bf..24ddefe01b5f9 100644 --- a/src/test/ui/consts/const-eval/const_panic_libcore_main.stderr +++ b/src/test/ui/consts/const-eval/const_panic_libcore_main.stderr @@ -25,7 +25,7 @@ error: any use of this value will cause an error LL | const X: () = unimplemented!(); | --------------^^^^^^^^^^^^^^^^- | | - | the evaluated program panicked at 'not yet implemented', $DIR/const_panic_libcore_main.rs:15:15 + | the evaluated program panicked at 'not implemented', $DIR/const_panic_libcore_main.rs:15:15 | = note: this error originates in a macro outside of the current crate (in Nightly builds, run with -Z external-macro-backtrace for more info)