`impl trait` in bindings (feature: impl-trait-existential-types)
This PR enables `impl Trait` syntax (opaque types) to be used in bindings, e.g.
* `let foo: impl Clone = 1;`
* `static foo: impl Clone = 2;`
* `const foo: impl Clone = 3;`
This is part of [RFC 2071](https://github.com/rust-lang/rfcs/blob/master/text/2071-impl-trait-existential-types.md) ([tracking issue](https://github.com/rust-lang/rust/issues/34511)), but exists behind the separate feature gate `impl_trait_in_bindings`.
CC @cramertj @oli-obk @eddyb @Centril @varkor
Support an explicit annotation for marker traits
From the tracking issue for rust-lang/rfcs#1268:
> It seems obvious that we should make a `#[marker]` annotation. ~ https://github.com/rust-lang/rust/issues/29864#issuecomment-368959441
This PR allows you to put `#[marker]` on a trait, at which point:
- [x] The trait must not have any items ~~All of the trait's items must have defaults~~
- [x] Any impl of the trait must be empty (not override any items)
- [x] But impls of the trait are allowed to overlap
r? @nikomatsakis
Rollup of 16 pull requests
Successful merges:
- #53652 (define copy_within on slices)
- #54261 (Make `dyn` a keyword in the 2018 edition)
- #54280 (remove (more) CAS API from Atomic* types where not natively supported)
- #54323 (rustbuild: drop color handling)
- #54350 (Support specifying edition in doc test)
- #54370 (Improve handling of type bounds in `bit_set.rs`.)
- #54371 (add -Zui-testing to rustdoc)
- #54374 (Make 'proc_macro::MultiSpan' public.)
- #54402 (Use no_default_libraries for all NetBSD flavors)
- #54409 (Detect `for _ in in bar {}` typo)
- #54412 (add applicability to span_suggestion call)
- #54413 (Add UI test for deref recursion limit printing twice)
- #54415 (parser: Tweak function parameter parsing to avoid rollback on succesfull path)
- #54420 (Compress `Liveness` data some more.)
- #54422 (Simplify slice's first(_mut) and last(_mut) with get)
- #54446 (Unify christianpoveda's emails)
Failed merges:
- #54058 (Introduce the partition_dedup/by/by_key methods for slices)
r? @ghost
Remove README with now-out-of-date docs about docs.
These docs haven't really been touched in years, and from what I tried, the `rustdoc` commands don't work. Seems like we don't need this?
Add a small search box to seach Rust's standary library
This change partially addresses #14572. No CSS doesn't look fancy
but at least it is functional.
docs: Use dollar sign for all bash prompts
Making it consistent across the board, as most of them already use `$`.
Also split one continues bash run into two, to make it easier see
different runs: one with warning and another with error.
stabilize #[used]
closes#40289
RFC for stabilization: rust-lang/rfcs#2386
r? @Centril
Where should this be documented? Currently the documentation is in the unstable book
Making it consistent across the board, as most of them already use `$`.
Also split one continues bash run into two, to make it easier see
different runs: one with warning and another with error.
librustc_lint: In recursion warning, change 'recurring' to 'recursing'
The existing wording seems incorrect.
Aside: This warning, 'function cannot return without recursing' is not perfectly clear - it implies that the function _can_ return, it's just got to recurse. But really the fn cannot return period. Clearer wording: 'function recurses infinitely; it cannot return'; or 'function is infinitely self-recursive; it cannot return, and this is probably an error'. I like that.
set cfg(rustdoc) when rustdoc is running on a crate
When using `#[doc(cfg)]` to document platform-specific items, it's a little cumbersome to get all the platforms' items to appear all at once. For example, the standard library adds `--cfg dox` to rustdoc's command line whenever it builds docs, and the documentation for `#![feature(doc_cfg)]` suggests using a Cargo feature to approximate the same thing. This is a little awkward, because you always need to remember to set `--features dox` whenever you build documentation.
This PR proposes making rustdoc set `#[cfg(rustdoc)]` whenever it runs on a crate, to provide an officially-sanctioned version of this that is set automatically. This way, there's a standardized way to declare that a certain version of an item is specifically when building docs.
To try to prevent the spread of this feature from happening too quickly, this PR also restricts the use of this flag to whenever `#![feature(doc_cfg)]` is active. I'm sure there are other uses for this, but right now i'm tying it to this feature. (If it makes more sense to give this its own feature, i can easily do that.)
rustdoc: add flag to control the html_root_url of dependencies
The `--extern-html-root-url` flag in this PR allows one to override links to crates whose docs are not already available locally in the doc bundle. Docs.rs currently uses a version of this to make sure links to other crates go into that crate's docs.rs page. See the included test for intended use, but the idea is as follows:
Calling rustdoc with `--extern-html-root-url crate=https://some-url.com` will cause rustdoc to override links that point to that crate to instead be replaced with a link rooted at `https://some-url.com/`. (e.g. for docs.rs this would be `https://docs.rs/crate/0.1.0` or the like.) Cheekily, rustup could use these options to redirect links to std/core/etc to instead point to locally-downloaded docs, if it so desired.
Fixes https://github.com/rust-lang/rust/issues/19603
The paragraph described a case where we can't optimize away repetitive
dynamic stack allocation. However, as arielb1 pointed out, it can
actually optimizable by dynamically delaying the stack unwinding.
Use #[non_exhaustive] on internal enums
This replaces `__Nonexhaustive` variants (and variants thereof) with `#[non_exhaustive]`. These were mostly unstable previously, with the exception of the `cloudabi` enums and `Level` in proc_macro: these were `#[doc(hidden)]`, so clearly intended not to be used directly. It should be safe to replace all of these.
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
rustdoc codeblock hash escape
So that docstring text such as the following (in a code block) can be created ergonomically:
```rust
let s = "
foo
# bar
baz
";
```
Such code in a docstring hide the <code> # bar</code> line.
Previously, using two consecutive hashes <code> ## bar</code> would turn the line into _shown_ `# bar`, losing the leading whitespace. A line of code like <code> # bar</code> (such as in the example above) **could not be represented** in the docstring text.
This commit makes the two consecutive hashes not also trim the leading whitespace — the two hashes simply **escape** into a single hash and do not hide the line, leaving the rest of that line unaffected. The new docstring text to achieve the above code block is:
```rust
/// ```
/// let s = "
/// foo
/// ## bar
/// baz
/// ";
/// ```
```
Mention spec and indented blocks in doctest docs
Fixes#49717.
This commit adds a new section to the Documentation Test docs, which briefly mentions indented code blocks, and links to the CommonMark specification for both.
I’m not sure about saying "fenced code blocks the more popular choice in the Rust community” because it seems like I’m speaking for everyone, but I can’t think of a better way to phrase it!
Update rustdoc book to suggest using Termination trait instead of hidden ‘foo’ function
Closes#50721.
I suggest that someone double-checks my English since I am not a native speaker.
r? @steveklabnik
Add doc comment to hiding portions of code example
fixes#50816
Not sure if this is all that's needed, but I think it's a good start. One thing to note is that the code block is a text block where it could possibly be a rust block.
This commit adds a new section to the Documentation Test docs, which briefly mentions indented code blocks, and links to the CommonMark specification for both.
I’m not sure about saying "fenced code blocks the more popular choice in the Rust community” because it seems like I’m speaking for everyone, but I can’t think of a better way to phrase it!
Point to the current box syntax tracking issue
The issue was used for both box syntax as well as placement new.
It got closed due to placement new being unapproved.
So a new one got created for box syntax, yet neither
the unstable book nor feature_gate.rs got updated.
We are doing this now.
r? @aidanhs
The issue was used for both box syntax as well as placement new.
It got closed due to placement new being unapproved.
So a new one got created for box syntax, yet neither
the unstable book nor feature_gate.rs got updated.
We are doing this now.
Reorder description for snippets in rustdoc documentation
The example code snippets for the `no_run` and `compile_fail` attributes in the rustdoc documentation were followed by the description for the wrong attribute. This patch reorders the descriptions to match the code snippets.
Turn deprecation lint `legacy_imports` into a hard error
Closes https://github.com/rust-lang/rust/issues/38260
The lint was introduced in Dec 2016, then made deny-by-default in Jun 2017 when crater run found 0 regressions caused by it.
This lint requires some not entirely trivial amount of import resolution logic that (surprisingly or not) interacts with `feature(use_extern_macros)` (https://github.com/rust-lang/rust/issues/35896), so it would be desirable to remove it before stabilizing `use_extern_macros`.
In particular, this PR fixes the failing example in https://github.com/rust-lang/rust/issues/50725 (but not the whole issue, `use std::panic::{self}` still can cause other undesirable errors when `use_extern_macros` is enabled).
The example code snippets for the `no_run` and `compile_fail` attributes
in the rustdoc documentation were followed by the description for the
wrong attribute. This patch reorders the descriptions to match the code
snippets.
Make sure people know the book is free oline
I've used the tutorial a number of times to relearn rust basics. When i saw this for a moment I was sad thinking it had been taken offline.
Fix null exclusions in grammar docs
The grammar documentation incorrectly says that comments, character literals,
and string literals may not include null.
Fix grammar documentation wrt Unicode identifiers
The grammar defines identifiers in terms of XID_start and XID_continue,
but this is referring to the unstable non_ascii_idents feature.
The documentation implies that non_ascii_idents is forthcoming, but this
is left over from pre-1.0 documentation; in reality, non_ascii_idents
has been without even an RFC for several years now, and will not be
stabilized anytime soon. Furthermore, according to the tracking issue at
https://github.com/rust-lang/rust/issues/28979 , it's highly
questionable whether or not this feature will use XID_start or
XID_continue even when or if non_ascii_idents is stabilized.
This commit fixes this by respecifying identifiers as the usual
[a-zA-Z_][a-zA-Z0-9_]*
The grammar defines identifiers in terms of XID_start and XID_continue,
but this is referring to the unstable non_ascii_idents feature.
The documentation implies that non_ascii_idents is forthcoming, but this
is left over from pre-1.0 documentation; in reality, non_ascii_idents
has been without even an RFC for several years now, and will not be
stabilized anytime soon. Furthermore, according to the tracking issue at
https://github.com/rust-lang/rust/issues/28979 , it's highly
questionable whether or not this feature will use XID_start or
XID_continue even when or if non_ascii_idents is stabilized.
This commit fixes this by respecifying identifiers as the usual
[a-zA-Z_][a-zA-Z0-9_]*
lint: deny incoherent_fundamental_impls by default
Warn the ecosystem of the pending intent-to-disallow in #49799.
There are 4 ICEs on my machine, look unrelated (having happened before in https://github.com/rust-lang/rust/issues/49146#issuecomment-384473523)
```rust
thread 'main' panicked at 'assertion failed: position <= slice.len()', libserialize/leb128.rs:97:1
```
```
[run-pass] run-pass/allocator/xcrate-use2.rs
[run-pass] run-pass/issue-12133-3.rs
[run-pass] run-pass/issue-32518.rs
[run-pass] run-pass/trait-default-method-xc-2.rs
```
r? @nikomatsakis
Bury Error::description()
Second attempt of #49536https://github.com/rust-lang/rfcs/pull/2230
The exact wording of the default implementation is still up in the air, but I think it's a detail that can be amended later.
Add "the Rustc book"
This PR introduces a new book into the documentation, "The rustc book". We already have books for Cargo, and for Rustdoc, rustc should have some too. This book is focused on *users* of rustc, and provides a nice place to write documentation for users.
I haven't put content here, but plan on scaffolding it out very soon, and wanted this PR open for a few discussions first. One of those is "what exactly should said TOC be?" I plan on having a proposed one up tomorrow, but figured I'd let people know to start thinking about it now.
The big one is that we also will want to put https://github.com/rust-lang-nursery/rustc-guide in-tree as well, and the naming is... tough. I'm proposing:
* doc.rust-lang.org/rustc is "The Rustc book", to mirror the other tools' books.
* doc.rust-lang.org/rustc-contribution is "The Rustc contribution guide", and contains that book
@nikomatsakis et al, any thoughts on this? I'm not attached to it in particular, but had to put something together to get this discussion going. I think mirroring the other tools is a good idea for this work, but am not sure where exactly that leaves yours.
Fixes https://github.com/rust-docs/team/issues/11
rustdoc: port the -C option from rustc
Blocked on https://github.com/rust-lang/rust/pull/49864. The included test won't work without those changes, so this PR includes those commits as well.
When documenting items that require certain target features, it helps to be able to force those target features into existence. Rather than include a flag just to parse those features, i instead decided to port the `-C` flag from rustc in its entirety. It takes the same parameters, because it runs through the same parsing function. This has the added benefit of being able to control the codegen of doctests as well.
One concern i have with the flag is that i set it to stable here. My rationale is that it is a direct port of functionality on rustc that is currently stable, used only in mechanisms that it is originally used for. If needed, i can set it back to be unstable.
Re-write the documentation index
The docs team has decided that we're framing resources in three ways:
"learning Rust," "using Rust," "mastering Rust." This is a more useful
split than "beginner/intermediate/advanced." As we add more resources
in the future, we expect "using Rust" to grow. "the bookshelf" as a
concept is great, but isn't really organized along these lines. As such,
this reorganizes the docs along these lines.
The docs team has decided that we're framing resources in three ways:
"learning Rust," "using Rust," "mastering Rust." This is a more useful
split than "beginner/intermediate/advanced." As we add more resources
in the future, we expect "using Rust" to grow. "the bookshelf" as a
concept is great, but isn't really organized along these lines. As such,
this reorganizes the docs along these lines.
rustdoc: add an --edition flag to compile docs/doctests with a certain edition
To correspond with the 2018 edition, this adds a (currently unstable) `--edition` flag to rustdoc that makes it compile crates and doctests with the given edition. Once this lands, Cargo should be updated to pass this flag when the edition configuration option is given.
add an "unstable features" chapter to the rustdoc book
There are several rustdoc features that currently are undocumented, but also don't fit with the rest of the Rustdoc Book since they're also unstable. Some of these have corresponding feature gates and chapters in the Unstable Book, but many don't, and i wanted a place to talk about them officially.
Goal: talk about everything rustdoc can do that needs nightly
- [x] Feature gates (extensions to the doc attribute that can be caught by the compiler)
- [x] doc(cfg)
- [x] doc(masked)
- [x] doc(spotlight)
- [x] doc(include)
- [x] Command-line flags (features that require a CLI flag to use, where the flag itself is a `-Z` command or otherwise requires `-Z unstable-options` before rustdoc will accept it)
- [x] markdown-before-content/markdown-after-content
- [x] playground-url
- [x] display-warnings
- [x] crate-version
- [x] linker
- [x] sort-modules-by-appearance
- [x] themes/theme-checker
- [x] resource-suffix
- [x] `-Z force-unstable-if-unmarked`
- [x] Nightly-gated functionality (features that are gated by requiring a nightly build without needing a CLI flag or a feature gate to unlock)
- [x] intra-links
- [x] error numbers for `compile_fail` doctests
