diff options
| author | Corey Farwell <coreyf@rwell.org> | 2017-12-06 09:35:41 -0500 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2017-12-06 09:35:41 -0500 |
| commit | bb239e294ee35aab4ddd7c7a306d0bf5bd8518b6 (patch) | |
| tree | 3bae34d8913ec84c8325bd31096b16368fcdca41 | |
| parent | 872c0259b698c7670d4087e414d6cfa9186981a5 (diff) | |
| parent | aaaea2c562dc5638e8fcaa00371492ae71b07e46 (diff) | |
| download | rust-bb239e294ee35aab4ddd7c7a306d0bf5bd8518b6.tar.gz rust-bb239e294ee35aab4ddd7c7a306d0bf5bd8518b6.zip | |
Rollup merge of #46512 - Havvy:doc-compile_fail, r=kennytm
Give compile_error macro examples I cannot get Rust to build at all with it complaining about GCC not being a valid C compiler or something, so letting TravisCI be my tester... Fixes #46171
| -rw-r--r-- | src/libcore/macros.rs | 4 | ||||
| -rw-r--r-- | src/libstd/macros.rs | 29 |
2 files changed, 29 insertions, 4 deletions
diff --git a/src/libcore/macros.rs b/src/libcore/macros.rs index 6e3dbcbec9d..fe2df226115 100644 --- a/src/libcore/macros.rs +++ b/src/libcore/macros.rs @@ -596,9 +596,9 @@ mod builtin { /// Unconditionally causes compilation to fail with the given error message when encountered. /// - /// For more information, see the [RFC]. + /// For more information, see the documentation for [`std::compile_error!`]. /// - /// [RFC]: https://github.com/rust-lang/rfcs/blob/master/text/1695-add-error-macro.md + /// [`std::compile_error!`]: ../std/macro.compile_error.html #[stable(feature = "compile_error_macro", since = "1.20.0")] #[macro_export] #[cfg(dox)] diff --git a/src/libstd/macros.rs b/src/libstd/macros.rs index 7d62f94056f..b36473d9b75 100644 --- a/src/libstd/macros.rs +++ b/src/libstd/macros.rs @@ -282,9 +282,34 @@ pub mod builtin { /// Unconditionally causes compilation to fail with the given error message when encountered. /// - /// For more information, see the [RFC]. + /// This macro should be used when a crate uses a conditional compilation strategy to provide + /// better error messages for errornous conditions. /// - /// [RFC]: https://github.com/rust-lang/rfcs/blob/master/text/1695-add-error-macro.md + /// # Examples + /// + /// Two such examples are macros and `#[cfg]` environments. + /// + /// Emit better compiler error if a macro is passed invalid values. + /// + /// ```compile_fail + /// macro_rules! give_me_foo_or_bar { + /// (foo) => {}; + /// (bar) => {}; + /// ($x:ident) => { + /// compile_error!("This macro only accepts `foo` or `bar`"); + /// } + /// } + /// + /// give_me_foo_or_bar!(neither); + /// // ^ will fail at compile time with message "This macro only accepts `foo` or `bar`" + /// ``` + /// + /// Emit compiler error if one of a number of features isn't available. + /// + /// ```compile_fail + /// #[cfg(not(any(feature = "foo", feature = "bar")))] + /// compile_error!("Either feature \"foo\" or \"bar\" must be enabled for this crate.") + /// ``` #[stable(feature = "compile_error_macro", since = "1.20.0")] #[macro_export] macro_rules! compile_error { ($msg:expr) => ({ /* compiler built-in */ }) } |