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!
