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!
Before this addition, every delimited group like (...) [...] {...} has
only a single Span that covers the full source location from opening
delimiter to closing delimiter. This makes it impossible for a
procedural macro to trigger an error pointing to just the opening or
closing delimiter. The Rust compiler does not seem to have the same
limitation:
mod m {
type T =
}
error: expected type, found `}`
--> src/main.rs:3:1
|
3 | }
| ^
On that same input, a procedural macro would be forced to trigger the
error on the last token inside the block, on the entire block, or on the
next token after the block, none of which is really what you want for an
error like above.
This commit adds group.span_open() and group.span_close() which access
the Span associated with just the opening delimiter and just the closing
delimiter of the group. Relevant to Syn as we implement real error
messages for when parsing fails in a procedural macro.
Rollup of 10 pull requests
Successful merges:
- #52946 (Documented impl From on line 367 of libserialize/json.rs)
- #53234 (Remove Travis shutdown debug scripts, and remove CI-specific DNS settings)
- #53313 (Two small improvements)
- #53360 (Addressed #51602)
- #53364 (Warn if the user tries to use GATs)
- #53373 (Tweak unclosed delimiter parser error)
- #53377 (std: Use target_pointer_width for BACKTRACE_ELF_SIZE)
- #53395 (Use #[non_exhaustive] on internal enums)
- #53399 (Tidy: ignore non-Markdown files when linting for the Unstable Book)
- #53412 (syntax_ext: remove leftover span_err_if_not_stage0 macro.)
TokenStream::extend
Two new insta-stable impls in libproc_macro:
```rust
impl Extend<TokenTree> for TokenStream
impl Extend<TokenStream> for TokenStream
```
`proc_macro::TokenStream` already implements `FromIterator<TokenTree>` and `FromIterator<TokenStream>` so I elected to support the same input types for `Extend`.
**This commit reduces compile time of Serde derives by 60% (takes less than half as long to compile)** as measured by building our test suite:
```console
$ git clone https://github.com/serde-rs/serde
$ cd serde/test_suite
$ cargo check --tests --features proc-macro2/nightly
$ rm -f ../target/debug/deps/libtest_*.rmeta
$ time cargo check --tests --features proc-macro2/nightly
Before: 20.8 seconds
After: 8.6 seconds
```
r? @alexcrichton
This commit stabilizes some of the `proc_macro` language feature as well as a
number of APIs in the `proc_macro` crate as [previously discussed][1]. This
means that on stable Rust you can now define custom procedural macros which
operate as attributes attached to items or `macro_rules!`-like bang-style
invocations. This extends the suite of currently stable procedural macros,
custom derives, with custom attributes and custom bang macros.
Note though that despite the stabilization in this commit procedural macros are
still not usable on stable Rust. To stabilize that we'll need to stabilize at
least part of the `use_extern_macros` feature. Currently you can define a
procedural macro attribute but you can't import it to call it!
A summary of the changes made in this PR (as well as the various consequences)
is:
* The `proc_macro` language and library features are now stable.
* Other APIs not stabilized in the `proc_macro` crate are now named under a
different feature, such as `proc_macro_diagnostic` or `proc_macro_span`.
* A few checks in resolution for `proc_macro` being enabled have switched over
to `use_extern_macros` being enabled. This means that code using
`#![feature(proc_macro)]` today will likely need to move to
`#![feature(use_extern_macros)]`.
It's intended that this PR, once landed, will be followed up with an attempt to
stabilize a small slice of `use_extern_macros` just for procedural macros to
make this feature 100% usable on stable.
[1]: https://internals.rust-lang.org/t/help-stabilize-a-subset-of-macros-2-0/7252
bors