rewrite documentation for unimplemented! to clarify use
The current docs for `unimplemented!` seem to miss the point of this macro.
> This can be useful if you are prototyping and are just looking to have your code type-check, or if you're implementing a trait that requires multiple methods, and you're only planning on using one of them.
You could also return a `()` if you just want your code to type-check.
I think `unimplemented!` is useful for when you want your program to exit when it reaches an unimplemented area.
I rewrote the explanation and gave examples of both forms of this macro that I think clarify its use a little better.
Stabilize todo macro
The `todo!` macro is just another name for `unimplemented!`.
Tracking issue: https://github.com/rust-lang/rust/issues/59277
This PR needs a FCP to merge.
r? @withoutboats
All transparancies are passed explicitly now.
Also remove `#[rustc_macro_transparency]` annotations from built-in macros, they are no longer used.
`#[rustc_macro_transparency]` only makes sense for declarative macros now.
Remove gensym in format_args
This also fixes some things to allow us to export opaque macros from libcore:
* Don't consider items that are only reachable through opaque macros as public/exported (so they aren't linted as needing docs)
* Mark private items reachable from the root of libcore as unstable - they are now reachable (in principle) in other crates via macros in libcore
r? @petrochenkov
More questionmarks in doctests
This removes the other `unwrap`s in the macro doctests, replacing them with `?`. For now, we need to specify the main function including the return type, we can get rid of that once the return type suggestion for `fn main() { .. }` works correctly.
r? @QuietMisdreavus
The expansions were created to allow unstable things inside `#[test_case/test/bench]`, but that's not a proper way to do that.
Put the required `allow_internal_unstable`s into the macros' properties instead.
TIL that debug_assert is implemented using `if cfg!(debug_assertions)`
rather than `#[cfg(debug_assertions)]`. This means one can not use API
gated with `#[cfg(debug_assertions)]` in `debug_assert` family of
macros.
First question mark in doctest
We have had `?` for `Result`s in doctests for some time, but so far haven't used them in doctests. With this PR, I want to start the de-`unwrap`ping of doctests – and the discussion on where to do so.
There is one downside, which is that the code can no longer be copied into a plain `main()` method, on the other hand, there should be a workable error if one does this.
The errors are either:
- The meta-variable used in the right-hand side is not bound (or defined) in the
left-hand side.
- The meta-variable used in the right-hand side does not repeat with the same
kleene operator as its binder in the left-hand side. Either it does not repeat
enough, or it uses a different operator somewhere.
This change should have no semantic impact.
Speed up the fast path for assert_eq! and assert_ne!
Currently, the panic!() calls directly borrow the value bindings. This
causes those bindings to always be initialized, i.e. they're initialized
even before the values are even compared. This causes noticeable
overhead in what should be a really cheap operation.
By performing a reborrow of the value in the call to panic!(), we allow
LLVM to optimize that code, so that the extra borrow only happens in the
error case.
We could achieve the same result by dereferencing the values passed to
panic!(), as the format machinery borrows them anyway, but this causes
assertions to fail to compile if one of the values is unsized, i.e. it
would be a breaking change.
Cosmetic improvements to doc comments
This has been factored out from https://github.com/rust-lang/rust/pull/58036 to only include changes to documentation comments (throughout the rustc codebase).
r? @steveklabnik
Once you're happy with this, maybe we could get it through with r=1, so it doesn't constantly get invalidated? (I'm not sure this will be an issue, but just in case...) Anyway, thanks for your advice so far!
