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
Rustdoc: example of use of assertions
I added this section at the beginning of the file because it seems to be basic information. Let me know if there's someplace more relevant.
See #47945.
Remove experimental -Zremap-path-prefix-from/to, and replace it with
the stabilized --remap-path-prefix=from=to variant.
This is an implementation for issue of #41555.
This updates the book repository, but mostly to include
https://github.com/rust-lang/book/pull/1180
TL;DR: the second edition is close enough to done that we should
universally recommend it over the first edition.
Stabilize feature(match_beginning_vert)
With this feature stabilized, match expressions can optionally have a `|` at the beginning of each arm.
Reference PR: rust-lang-nursery/reference#231
Closes#44101
Implement repr(transparent)
r? @eddyb for the functional changes. The bulk of the PR is error messages and docs, might be good to have a doc person look over those.
cc #43036
cc @nox
add Rust By Example to the bookshelf
cc #46194
With #46196 freshly merged, we should add a link to the main docs distribution so people can find it! We discussed this at the docs team meeting today and decided to go ahead with adding it to the bookshelf.
Allow lifetimes in macros
This is a resurrection of PR #41927 which was a resurrection of #33135, which is intended to fix#34303.
In short, this allows macros_rules! to use :lifetime as a matcher to match 'lifetimes.
Still to do:
- [x] Feature gate
Stabilize spin_loop_hint
Stabilize `spin_loop_hint` in release `1.23.0`.
I've also renamed feature `hint_core_should_pause` to `spin_loop_hint`.
cc #41196
rustdoc: include external files in documentation (RFC 1990)
Part of https://github.com/rust-lang/rfcs/pull/1990 (needs work on the error reporting, which i'm deferring to after this initial PR)
cc #44732
Also fixes#42760, because the prep work for the error reporting made it easy to fix that at the same time.
show in docs whether the return type of a function impls Iterator/Read/Write
Closes#25928
This PR makes it so that when rustdoc documents a function, it checks the return type to see whether it implements a handful of specific traits. If so, it will print the impl and any associated types. Rather than doing this via a whitelist within rustdoc, i chose to do this by a new `#[doc]` attribute parameter, so things like `Future` could tap into this if desired.
### Known shortcomings
~~The printing of impls currently uses the `where` class over the whole thing to shrink the font size relative to the function definition itself. Naturally, when the impl has a where clause of its own, it gets shrunken even further:~~ (This is no longer a problem because the design changed and rendered this concern moot.)
The lookup currently just looks at the top-level type, not looking inside things like Result or Option, which renders the spotlights on Read/Write a little less useful:
<details><summary>`File::{open, create}` don't have spotlight info (pic of old design)</summary>
</details>
All three of the initially spotlighted traits are generically implemented on `&mut` references. Rustdoc currently treats a `&mut T` reference-to-a-generic as an impl on the reference primitive itself. `&mut Self` counts as a generic in the eyes of rustdoc. All this combines to create this lovely scene on `Iterator::by_ref`:
<details><summary>`Iterator::by_ref` spotlights Iterator, Read, and Write (pic of old design)</summary>
</details>
rustdoc book: talk about #![doc(test(no_crate_inject))] and #![doc(test(attr(...)))]
While investigating https://github.com/rust-lang/rust/issues/45750 i noticed that `#![doc(test(attr(...)))]` wasn't documented at all. Since this is useful for making your examples follow the same coding guidelines as your code, i wanted to add it to the Rustdoc Book. I also added `#![doc(test(no_crate_inject))]` since it's used in the same place and might be useful for macro-heavy crates. I added mentions for these to "The `doc` attribute" as well as "Documentation tests" since it's useful information in both places.
Technically the step reordering in the second commit is gated on https://github.com/rust-lang/rust/pull/45764, since before that lands attributes from the doctest come before the ones from `#![doc(test(attr(...)))]`.
This commit removes the `rand` crate from the standard library facade as
well as the `__rand` module in the standard library. Neither of these
were used in any meaningful way in the standard library itself. The only
need for randomness in libstd is to initialize the thread-local keys of
a `HashMap`, and that unconditionally used `OsRng` defined in the
standard library anyway.
The cruft of the `rand` crate and the extra `rand` support in the
standard library makes libstd slightly more difficult to port to new
platforms, namely WebAssembly which doesn't have any randomness at all
(without interfacing with JS). The purpose of this commit is to clarify
and streamline randomness in libstd, focusing on how it's only required
in one location, hashmap seeds.
Note that the `rand` crate out of tree has almost always been a drop-in
replacement for the `rand` crate in-tree, so any usage (accidental or
purposeful) of the crate in-tree should switch to the `rand` crate on
crates.io. This then also has the further benefit of avoiding
duplication (mostly) between the two crates!
RFC 2008: Future-proofing enums/structs with #[non_exhaustive] attribute
This work-in-progress pull request contains my changes to implement [RFC 2008](https://github.com/rust-lang/rfcs/pull/2008). The related tracking issue is #44109.
As of writing, enum-related functionality is not included and there are some issues related to tuple/unit structs. Enum related tests are currently ignored.
WIP PR requested by @nikomatsakis [in Gitter](https://gitter.im/rust-impl-period/WG-compiler-middle?at=59e90e6297cedeb0482ade3e).
Bump to 1.23 and update bootstrap
This commit updates the bootstrap compiler, bumps the version to 1.23, updates
Cargo, updates books, and updates crates.io dependencies
Remove deprecated `collections` crate.
The real `collections` was merged with `alloc`, this facade was introduced [in this PR](https://github.com/rust-lang/rust/pull/42720) to give `#[no_std]` users time to adapt. This was done at least two cycles ago, now we can consider removing it for good.
Fix out of date unstable book entries for `alloc_*` features.
The `alloc_jemalloc` crate does not provide a type to use with `#[global_allocator]`, and (according to Alex) `extern crate alloc_jemalloc;` alone became a no-op when `#[global_allocator]` was introduced.
List of all lang items in unstable book.
I don't know how to link to the source code correctly, so I just put the information aside the lang item name.
Moved details of unstable non-ascii identifiers from the Reference
Moved details of unstable non-ascii identifiers from the Reference to the Unstable book
r? @steveklabnik
Implement `and_modify` on `Entry`
## Motivation
`Entry`s are useful for allowing access to existing values in a map while also allowing default values to be inserted for absent keys. The existing API is similar to that of `Option`, where `or` and `or_with` can be used if the option variant is `None`.
The `Entry` API is, however, missing an equivalent of `Option`'s `and_then` method. If it were present it would be possible to modify an existing entry before calling `or_insert` without resorting to matching on the entry variant.
Tracking issue: https://github.com/rust-lang/rust/issues/44733.
Add ..= to the parser
Add ..= to libproc_macro
Add ..= to ICH
Highlight ..= in rustdoc
Update impl Debug for RangeInclusive to ..=
Replace `...` to `..=` in range docs
Make the dotdoteq warning point to the ...
Add warning for ... in expressions
Updated more tests to the ..= syntax
Updated even more tests to the ..= syntax
Updated the inclusive_range entry in unstable book
hide internal types/traits from std docs via new #[doc(masked)] attribute
Fixes#43701 (hopefully for good this time)
This PR introduces a new parameter to the `#[doc]` attribute that rustdoc looks for on `extern crate` statements. When it sees `#[doc(masked)]` on such a statement, it hides traits and types from that crate from appearing in either the "Trait Implementations" section of many type pages, or the "Implementors" section of trait pages. This is then applied to the `libc`/`rand`/`compiler_builtins` imports in libstd to prevent those crates from creating broken links in the std docs.
Like in #43348, this also introduces a feature gate, `doc_masked`, that controls the use of this parameter.
To view the std docs generated with this change, head to https://tonberry.quietmisdreavus.net/std-43701/std/index.html.
stabilized compiler_fences (fixes#41091)
I did not know what to proceed with "unstable-book" entry. The feature would no longer be unstable so I have deleted it. If it was the wrong call I'll revert it (unfortunately his case is not described in the CONTRIBUTING.md).
Compile fail stable
Since #30726, we never made the `compile_fail` flag nor the error code check stable. I think it's time to change this fact.
r? @alexcrichton
Add method `String::retain`
Behaves like `Vec::retain`, accepting a predicate `FnMut(char) -> bool`
and reducing the string to only characters for which the predicate
returns `true`.
Behaves like `Vec::retain`, accepting a predicate `FnMut(char) -> bool`
and reducing the string to only characters for which the predicate
returns `true`.
Expose all OS-specific modules in libstd doc.
1. Uses the special `--cfg dox` configuration passed by rustbuild when running `rustdoc`. Changes the `#[cfg(platform)]` into `#[cfg(any(dox, platform))]` so that platform-specific API are visible to rustdoc.
2. Since platform-specific implementations often won't compile correctly on other platforms, `rustdoc` is changed to apply `everybody_loops` to the functions during documentation and doc-test harness.
3. Since platform-specific code are documented on all platforms now, it could confuse users who found a useful API but is non-portable. Also, their examples will be doc-tested, so must be excluded when not testing on the native platform. An undocumented attribute `#[doc(cfg(...))]` is introduced to serve the above purposed.
Fixes#24658 (Does _not_ fully implement #1998).
This attribute has two effects:
1. Items with this attribute and their children will have the "This is
supported on **** only" message attached in the documentation.
2. The items' doc tests will be skipped if the configuration does not
match.
Stabilize more APIs for the 1.20.0 release
In addition to the few stabilizations that have already landed, this cleans up the remaining APIs that are in `final-comment-period` right now to be stable by the 1.20.0 release
Make the "main" constructors of NonZero/Shared/Unique return Option
Per discussion in https://github.com/rust-lang/rust/issues/27730#issuecomment-303939441.
This is a breaking change to unstable APIs.
The old behavior is still available under the name `new_unchecked`. Note that only that one can be `const fn`, since `if` is currently not allowed in constant contexts.
In the case of `NonZero` this requires adding a new `is_zero` method to the `Zeroable` trait. I mildly dislike this, but it’s not much worse than having a `Zeroable` trait in the first place. `Zeroable` and `NonZero` are both unstable, this can be reworked later.
The docs for the `compiler_builtins_lib` library feature were removed
in #42899. But, though the `compiler_builtins` library has been
migrated out-of-tree, the feature remains, and is needed to use the
stand-alone crate. We reintroduce the docs for the feature, and add a
reference to them when describing how to create a `no_std` executable.
Switch to rust-lang-nursery/compiler-builtins
This commit migrates the in-tree `libcompiler_builtins` to the upstream version
at https://github.com/rust-lang-nursery/compiler-builtins. The upstream version
has a number of intrinsics written in Rust and serves as an in-progress rewrite
of compiler-rt into Rust. Additionally it also contains all the existing
intrinsics defined in `libcompiler_builtins` for 128-bit integers.
It's been the intention since the beginning to make this transition but
previously it just lacked the manpower to get done. As this PR likely shows it
wasn't a trivial integration! Some highlight changes are:
* The PR rust-lang-nursery/compiler-builtins#166 contains a number of fixes
across platforms and also some refactorings to make the intrinsics easier to
read. The additional testing added there also fixed a number of integration
issues when pulling the repository into this tree.
* LTO with the compiler-builtins crate was fixed to link in the entire crate
after the LTO process as these intrinsics are excluded from LTO.
* Treatment of hidden symbols was updated as previously the
`#![compiler_builtins]` crate would mark all symbol *imports* as hidden
whereas it was only intended to mark *exports* as hidden.
rustc: Implement the #[global_allocator] attribute
This PR is an implementation of [RFC 1974] which specifies a new method of
defining a global allocator for a program. This obsoletes the old
`#![allocator]` attribute and also removes support for it.
[RFC 1974]: https://github.com/rust-lang/rfcs/pull/1974
The new `#[global_allocator]` attribute solves many issues encountered with the
`#![allocator]` attribute such as composition and restrictions on the crate
graph itself. The compiler now has much more control over the ABI of the
allocator and how it's implemented, allowing much more freedom in terms of how
this feature is implemented.
cc #27389
This PR is an implementation of [RFC 1974] which specifies a new method of
defining a global allocator for a program. This obsoletes the old
`#![allocator]` attribute and also removes support for it.
[RFC 1974]: https://github.com/rust-lang/rfcs/pull/197
The new `#[global_allocator]` attribute solves many issues encountered with the
`#![allocator]` attribute such as composition and restrictions on the crate
graph itself. The compiler now has much more control over the ABI of the
allocator and how it's implemented, allowing much more freedom in terms of how
this feature is implemented.
cc #27389
This commit migrates the in-tree `libcompiler_builtins` to the upstream version
at https://github.com/rust-lang-nursery/compiler-builtins. The upstream version
has a number of intrinsics written in Rust and serves as an in-progress rewrite
of compiler-rt into Rust. Additionally it also contains all the existing
intrinsics defined in `libcompiler_builtins` for 128-bit integers.
It's been the intention since the beginning to make this transition but
previously it just lacked the manpower to get done. As this PR likely shows it
wasn't a trivial integration! Some highlight changes are:
* The PR rust-lang-nursery/compiler-builtins#166 contains a number of fixes
across platforms and also some refactorings to make the intrinsics easier to
read. The additional testing added there also fixed a number of integration
issues when pulling the repository into this tree.
* LTO with the compiler-builtins crate was fixed to link in the entire crate
after the LTO process as these intrinsics are excluded from LTO.
* Treatment of hidden symbols was updated as previously the
`#![compiler_builtins]` crate would mark all symbol *imports* as hidden
whereas it was only intended to mark *exports* as hidden.
Add `Iterator::for_each`
This works like a `for` loop in functional style, applying a closure to
every item in the `Iterator`. It doesn't allow `break`/`continue` like
a `for` loop, nor any other control flow outside the closure, but it may
be a more legible style for tying up the end of a long iterator chain.
This was tried before in #14911, but nobody made the case for using it
with longer iterators. There was also `Iterator::advance` at that time
which was more capable than `for_each`, but that no longer exists.
The `itertools` crate has `Itertools::foreach` with the same behavior,
but thankfully the names won't collide. The `rayon` crate also has a
`ParallelIterator::for_each` where simple `for` loops aren't possible.
> I really wish we had `for_each` on seq iterators. Having to use a
> dummy operation is annoying. - [@nikomatsakis][1]
[1]: https://github.com/nikomatsakis/rayon/pull/367#issuecomment-308455185
This works like a `for` loop in functional style, applying a closure to
every item in the `Iterator`. It doesn't allow `break`/`continue` like
a `for` loop, nor any other control flow outside the closure, but it may
be a more legible style for tying up the end of a long iterator chain.
This was tried before in #14911, but nobody made the case for using it
with longer iterators. There was also `Iterator::advance` at that time
which was more capable than `for_each`, but that no longer exists.
The `itertools` crate has `Itertools::foreach` with the same behavior,
but thankfully the names won't collide. The `rayon` crate also has a
`ParallelIterator::for_each` where simple `for` loops aren't possible.
> I really wish we had `for_each` on seq iterators. Having to use a
> dummy operation is annoying. - [@nikomatsakis][1]
[1]: https://github.com/nikomatsakis/rayon/pull/367#issuecomment-308455185
add `FromStr` Impl for `char`
fixes#24939.
is it possible to use pub(restricted) instead of using a stability attribute for the internal error representation? is it needed at all?
Allocator integration
Lets start getting some feedback on `trait Alloc`.
Here is:
* the `trait Alloc` itself,
* the `struct Layout` and `enum AllocErr` that its API relies on
* a `struct HeapAlloc` that exposes the system allocator as an instance of `Alloc`
* an integration of `Alloc` with `RawVec`
* ~~an integration of `Alloc` with `Vec`~~
TODO
* [x] split `fn realloc_in_place` into `grow` and `shrink` variants
* [x] add `# Unsafety` and `# Errors` sections to documentation for all relevant methods
* [x] remove `Vec` integration with `Allocator`
* [x] add `allocate_zeroed` impl to `HeapAllocator`
* [x] remove typedefs e.g. `type Size = usize;`
* [x] impl `trait Error` for all error types in PR
* [x] make `Layout::from_size_align` public
* [x] clarify docs of `fn padding_needed_for`.
* [x] revise `Layout` constructors to ensure that [size+align combination is valid](https://github.com/rust-lang/rust/pull/42313#issuecomment-306845446)
* [x] resolve mismatch re requirements of align on dealloc. See [comment](https://github.com/rust-lang/rust/pull/42313#issuecomment-306202489).
