I believe rustdoc should not be conflating private items (visibility
lower than `pub`) and hidden items (attribute `doc(hidden)`). This
matters now that Cargo is passing --document-private-items by default
for bin crates. In bin crates that rely on macros, intentionally hidden
implementation details of the macros can overwhelm the actual useful
internal API that one would want to document.
This PR restores the strip-hidden pass when documenting private items,
and introduces a separate unstable --document-hidden-items option to
skip the strip-hidden pass. The two options are orthogonal to one
another.
Remove mem::uninitalized from tests
This purges uses of uninitialized where possible from test cases. Some
are merely moved over to the equally bad pattern of
MaybeUninit::uninit().assume_init() but with an annotation that this is
"the best we can do".
Fixes#62397
This purges uses of uninitialized where possible from test cases. Some
are merely moved over to the equally bad pattern of
MaybeUninit::uninit().assume_init() but with an annotation that this is
"the best we can do".
Add options to --extern flag.
This changes the `--extern` flag so that it can take a series of options that changes its behavior. The general syntax is `[opts ':'] name ['=' path]` where `opts` is a comma separated list of options. Two options are supported, `priv` which replaces `--extern-private` and `noprelude` which avoids adding the crate to the extern prelude.
```text
--extern priv:mylib=/path/to/libmylib.rlib
--extern noprelude:alloc=/path/to/liballoc.rlib
```
`noprelude` is to be used by Cargo's build-std feature in order to use `--extern` to reference standard library crates.
This also includes a second commit which adds the `aux-crate` directive to compiletest. I can split this off into a separate PR if desired, but it helps with defining these kinds of tests. It is based on #54020, and can be used in the future to replace and simplify some of the Makefile tests.
rustdoc: Stabilize `edition` annotation.
The rustdoc `edition` annotation is currently ignored on stable. This means that the tests will be ignored, unless there is a `rust` annotation, then it will use the global edition. I suspect this was just an oversight during the edition stabilization, but I don't know. Example:
```rust
/// ```edition2018
/// // This code block was ignored on stable.
/// ```
/// ```rust,edition2018
/// // This code block would use whatever edition is passed on the command line.
/// ```
```
AFAIK, it is not possible to write a test that verifies stable behavior, as all tests appear to set RUSTC_BOOTSTRAP which forces all tests to run as "nightly", even on a stable release.
Closes#65980
Fix ICE when documentation includes intra-doc-link
When collecting intra-doc-links we could trigger the loading of extra crates into the crate store due to name resolution finding crates referred to in documentation but not in code. This might be due to
configuration differences or simply referring to something else.
This would cause an ICE because the newly loaded crate metadata existed in a crate store associated with the rustdoc global context, but the resolver had its own crate store cloned just before the documentation processing began and as such it could try and look up crates in a store which lacked them.
In this PR, I add support for `--extern-private` to the `rustdoc` tool so that it is supported for `compiletest` to then pass the crates in; and then I fix the issue by forcing the resolver to look over all the crates before we then lower the input ready for processing into documentation.
The first commit (the `--extern-private`) could be replaced with a commit which adds support for `--extern` to `compiletest` if preferred, though I think that adding `--extern-private` to `rustdoc` is more useful anyway since it makes the CLI a little more like `rustc`'s which might help reduce surprise for someone running it by hand or in their own test code.
The PR is meant to fix#66159 though it may also fix#65840.
cc @GuillaumeGomez
In order that we can successfully later resolve paths in crates
which weren't loaded as a result of merely parsing the crate
we're documenting, we force the resolution of the path to each
crate before cloning the resolver to use later. Closes#66159
Signed-off-by: Daniel Silverstone <dsilvers@digital-scurf.org>
rustdoc: Resolve module-level doc references more locally
Module level docs should resolve intra-doc links as locally as
possible. As such, this commit alters the heuristic for finding
intra-doc links such that we attempt to resolve names mentioned
in *inner* documentation comments within the (sub-)module rather
that from the context of its parent.
I'm hoping that this fixes#55364 though right now I'm not sure it's the right fix.
r? @GuillaumeGomez
Module level docs should resolve intra-doc links as locally as
possible. As such, this commit alters the heuristic for finding
intra-doc links such that we attempt to resolve names mentioned
in *inner* documentation comments within the (sub-)module rather
that from the context of its parent.
Signed-off-by: Daniel Silverstone <dsilvers@digital-scurf.org>
rustdoc: forward -Z options to rustc
Currently rustdoc does not forward `-Z` options to rustc when building
test executables. This makes impossible to use rustdoc to run test
samples when crate under test is instrumented with one of sanitizers
`-Zsanitizer=...`, since the final linking step will not include
sanitizer runtime library.
Forward `-Z` options to rustc to solve the issue.
Helps with #43031.
Currently rustdoc does not forward `-Z` options to rustc when building
test executables. This makes impossible to use rustdoc to run test
samples when crate under test is instrumented with one of sanitizers
`-Zsanitizer=...`, since the final linking step will not include
sanitizer runtime library.
Forward `-Z` options to rustc to solve the issue.
Helps with #43031.
Improve Rustdoc's handling of procedural macros
Fixes#58700Fixes#58696Fixes#49553Fixes#52210
This commit removes the special rustdoc handling for proc macros, as we can now
retrieve their span and attributes just like any other item.
A new command-line option is added to rustdoc: `--crate-type`. This takes the same options as rustc's `--crate-type` option. However, all values other than `proc-macro` are treated the same. This allows Rustdoc to enable 'proc macro mode' when handling a proc macro crate.
In compiletest, a new 'rustdoc-flags' option is added. This allows us to
pass in the '--proc-macro-crate' flag in the absence of Cargo.
I've opened [an additional PR to Cargo](https://github.com/rust-lang/cargo/pull/7159) to support passing in this flag.
These two PRS can be merged in any order - the Cargo changes will not
take effect until the 'cargo' submodule is updated in this repository.
Fixes#58700Fixes#58696Fixes#49553Fixes#52210
This commit removes the special rustdoc handling for proc macros, as we
can now
retrieve their span and attributes just like any other item.
A new command-line option is added to rustdoc: `--crate-type`. This
takes the same options as rustc's `--crate-type` option. However, all
values other than `proc-macro` are treated the same. This allows Rustdoc
to enable 'proc macro mode' when handling a proc macro crate.
In compiletest, a new 'rustdoc-flags' option is added. This allows us to
pass in the '--proc-macro-crate' flag in the absence of Cargo.
I've opened [an additional PR to
Cargo](https://github.com/rust-lang/cargo/pull/7159) to support passing
in this flag.
These two PRS can be merged in any order - the Cargo changes will not
take effect until the 'cargo' submodule is updated in this repository.
Use doc comments from 'pub use' statements
Split off from #62855
Currently, rustdoc ignores any doc comments found on 'pub use'
statements. As described in issue #58700, this makes it impossible to
properly document procedural macros. Any doc comments must be written on
the procedural macro definition, which must occur in a dedicated
proc-macro crate. This means that any doc comments or doc tests cannot
reference items defined in re-exporting crate, despite the fact that
such items may be required to use the procedural macro.
To solve this issue, this commit allows doc comments to be written on
'pub use' statements. For consistency, this applies to *all* 'pub use'
statements, not just those importing procedural macros.
When inlining documentation, documentation on 'pub use' statements will
be prepended to the documentation of the inlined item. For example,
the following items:
```rust
mod other_mod {
/// Doc comment from definition
pub struct MyStruct;
}
/// Doc comment from 'pub use'
///
pub use other_mod::MyStruct;
```
will caues the documentation for the re-export of 'MyStruct' to be
rendered as:
```
Doc comment from 'pub use'
Doc comment from definition
```
Note the empty line in the 'pub use' doc comments - because doc comments
are concatenated as-is, this ensure that the doc comments on the
definition start on a new line.
Split off from #62855
Currently, rustdoc ignores any doc comments found on 'pub use'
statements. As described in issue #58700, this makes it impossible to
properly document procedural macros. Any doc comments must be written on
the procedural macro definition, which must occur in a dedicated
proc-macro crate. This means that any doc comments or doc tests cannot
reference items defined in re-exporting crate, despite the fact that
such items may be required to use the procedural macro.
To solve this issue, this commit allows doc comments to be written on
'pub use' statements. For consistency, this applies to *all* 'pub use'
statements, not just those importing procedural macros.
When inlining documentation, documentation on 'pub use' statements will
be prepended to the documentation of the inlined item. For example,
the following items:
```rust
mod other_mod {
/// Doc comment from definition
pub struct MyStruct;
}
/// Doc comment from 'pub use'
///
pub use other_mod::MyStruct;
```
will caues the documentation for the re-export of 'MyStruct' to be
rendered as:
```
Doc comment from 'pub use'
Doc comment from definition
```
Note the empty line in the 'pub use' doc comments - because doc comments
are concatenated as-is, this ensure that the doc comments on the
definition start on a new line.
It's internal to resolve and always results in `Res::Err` outside of resolve.
Instead put `DefKind::Fn`s themselves into the macro namespace, it's ok.
Proc macro stubs are items placed into macro namespase for functions that define proc macros.
https://github.com/rust-lang/rust/pull/52383
The rustdoc test is changed because the old test didn't actually reproduce the ICE it was supposed to reproduce.
Raise the default recursion limit to 128
The previous limit of 64 is being (just) barely hit by genuine code out there, which is causing issues like https://github.com/rust-lang/rust/issues/62059 to rear their end.
Ideally, we wouldn’t have such arbitrary limits at all, but while we do, it makes a lot of sense to just raise this limit whenever genuine use-cases end up hitting it.
r? @pnkfelix
Fixes https://github.com/rust-lang/rust/issues/62059
Previously we would only generate a list of synthetic implementations
for two well known traits – Send and Sync. With this patch all the auto
traits known to rustc are considered. This includes such traits like
Unpin and user’s own traits.
Sadly the implementation still iterates through the list of crate items
and checks them against the traits, which for non-std crates containing
their own auto-traits will still not include types defined in std/core.
It is an improvement nontheless.
Don't generate div inside header (h4/h3/h...) elements
Fixes#60865.
According to the HTML spec, we're not supposed to put `div` elements inside heading elements (h4/h3/h...). It doesn't change the display as far as I could tell.
r? @QuietMisdreavus
implicit `Option`-returning doctests
This distinguishes `Option` and `Result`-returning doctests with implicit `main` method, where the former tests must end with `Some(())`.
Open question: Does this need a feature gate?
r? @GuillaumeGomez
Always try to project predicates when finding auto traits in rustdoc
Fixes#60726
Previous, AutoTraitFinder would only try to project predicates when the
predicate type contained an inference variable. When finding auto
traits, we only project to try to unify inference variables - we don't
otherwise learn any new information about the required bounds.
However, this lead to failing to properly generate a negative auto trait
impl (indicating that a type never implements a certain auto trait) in
the following unusual scenario:
In almost all cases, a type has an (implicit) negative impl of an auto
trait due some other type having an explicit *negative* impl of that
auto trait. For example:
struct MyType<T> {
field: *const T
}
has an implicit 'impl<T> !Send for MyType<T>', due to the explicit
negative impl (in libcore) 'impl<T: ?Sized> !Send for *const T'.
However, as exposed by the 'abi_stable' crate, this isn't always the
case. This minimzed example shows how a type can never implement
'Send', due to a projection error:
```
pub struct True;
pub struct False;
pub trait MyTrait {
type Project;
}
pub struct MyStruct<T> {
field: T
}
impl MyTrait for u8 {
type Project = False;
}
unsafe impl<T> Send for MyStruct<T>
where T: MyTrait<Project=True> {}
pub struct Wrapper {
inner: MyStruct<u8>
}
```
In this example, `<u8 as MyTrait>::Project == True'
must hold for 'MyStruct<u8>: Send' to hold.
However, '<u8 as MyTrait>::Project == False' holds instead
To properly account for this unusual case, we need to call
'poly_project_and_unify' on *all* predicates, not just those with
inference variables. This ensures that we catch the projection error
that occurs above, and don't incorrectly determine that 'Wrapper: Send'
holds.
Fix intra-doc link resolution failure on re-exporting libstd
Currently, re-exporting libstd items as below will [occur a lot of failures](https://gist.github.com/taiki-e/e33e0e8631ef47f65a74a3b69f456366).
```rust
pub use std::*;
```
Until the underlying issue (#56922) fixed, we can fix that so they don't propagate to downstream crates.
Related: https://github.com/rust-lang/rust/pull/56941 (That PR fixed failures that occur when re-exporting from libcore to libstd.)
r? @QuietMisdreavus
rustdoc: set the default edition when pre-parsing a doctest
Fixes https://github.com/rust-lang/rust/issues/59313 (possibly more? i think we've had issues with parsing edition-specific syntax in doctests at some point)
When handling a doctest, rustdoc needs to parse it beforehand, so that it can see whether it declares a `fn main` or `extern crate my_crate` explicitly. However, while doing this, rustdoc doesn't set the "default edition" used by the parser like the regular compilation runs do. This caused a problem when parsing a doctest with an `async move` block in it, since it was expecting the `move` keyword to start a closure, not a block.
This PR changes the `rustdoc::test::make_test` function to set the parser's default edition while looking for a main function and `extern crate` statement. However, to do this, `make_test` needs to know what edition to set. Since this is also used during the HTML rendering process (to make playground URLs), now the HTML renderer needs to know about the default edition. Upshot: rendering standalone markdown files can now accept a "default edition" for their doctests with the `--edition` flag! (I'm pretty sure i waffled around how to set that a long time ago when we first added the `--edition` flag... `>_>`)
I'm posting this before i stop for the night so that i can write this description while it's still in my head, but before this merges i want to make sure that (1) the `rustdoc-ui/failed-doctest-output` test still works (i expect it doesn't), and (2) i add a test with the sample from the linked issue.
Fixes#60726
Previous, AutoTraitFinder would only try to project predicates when the
predicate type contained an inference variable. When finding auto
traits, we only project to try to unify inference variables - we don't
otherwise learn any new information about the required bounds.
However, this lead to failing to properly generate a negative auto trait
impl (indicating that a type never implements a certain auto trait) in
the following unusual scenario:
In almost all cases, a type has an (implicit) negative impl of an auto
trait due some other type having an explicit *negative* impl of that
auto trait. For example:
struct MyType<T> {
field: *const T
}
has an implicit 'impl<T> !Send for MyType<T>', due to the explicit
negative impl (in libcore) 'impl<T: ?Sized> !Send for *const T'.
However, as exposed by the 'abi_stable' crate, this isn't always the
case. This minimzed example shows how a type can never implement
'Send', due to a projection error:
```
pub struct True;
pub struct False;
pub trait MyTrait {
type Project;
}
pub struct MyStruct<T> {
field: T
}
impl MyTrait for u8 {
type Project = False;
}
unsafe impl<T> Send for MyStruct<T>
where T: MyTrait<Project=True> {}
pub struct Wrapper {
inner: MyStruct<u8>
}
```
In this example, `<u8 as MyTrait>::Project == True'
must hold for 'MyStruct<u8>: Send' to hold.
However, '<u8 as MyTrait>::Project == False' holds instead
To properly account for this unusual case, we need to call
'poly_project_and_unify' on *all* predicates, not just those with
inference variables. This ensures that we catch the projection error
that occurs above, and don't incorrectly determine that 'Wrapper: Send'
holds.
Fix index-page generation
Fixes#60096.
The minifier was minifying crates name in `searchIndex` key position, which was a bit problematic for multiple reasons.
r? @rust-lang/rustdoc
rustdoc: use --static-root-path for settings.js
At the time i was writing https://github.com/rust-lang/docs.rs/pull/332, i noticed that the `settings.js` file that was being loaded was not being loaded from the `--static-root-path`. This PR fixes that so that users on docs.rs can effectively cache this file.
rustdoc: don't process `Crate::external_traits` when collecting intra-doc links
Part of https://github.com/rust-lang/rust/issues/58745, closes https://github.com/rust-lang/rust/pull/58917
The `collect-intra-doc-links` pass keeps track of the modules it recurses through as it processes items. This is used to know what module to give the resolver when looking up links. When looking through the regular items of the crate, this works fine, but the `DocFolder` trait as written doesn't just process the main crate hierarchy - it also processes the trait items in the `external_traits` map. This is useful for other passes (so they can strip out `#[doc(hidden)]` items, for example), but here it creates a situation where we're processing items "outside" the regular module hierarchy. Since everything in `external_traits` is defined outside the current crate, we can't fall back to finding its module scope like we do with local items.
Skipping this collection saves us from emitting some spurious warnings. We don't even lose anything by skipping it, either - the docs loaded from here are only ever rendered through `html::render::document_short` which strips any links out, so the fact that the links haven't been loaded doesn't matter. Hopefully this removes most of the remaining spurious resolution warnings from intra-doc links.
r? @GuillaumeGomez
- Makes the warning part of the `intra_doc_link_resolution_failure`
lint.
- Tightens the span to just the ambiguous link.
- Reports ambiguities across all three namespaces.
- Uses structured suggestions for disambiguation.
- Adds a test for the warnings.
Modify doctest's auto-`fn main()` to allow `Result`s
This lets the default `fn main()` ~~return `impl Termination`~~ unwrap Results, which allows the use of `?` in most tests without adding it manually. This fixes#56260
~~Blocked on `std::process::Termination` stabilization.~~
Using `Termination` would have been cleaner, but this should work OK.
Rustdoc remove old style files
Reopening of #56577 (which I can't seem to reopen...).
I made the flag unstable so with this change, what was blocking the PR is now gone I assume.
Ignore future deprecations in #[deprecated]
The future deprecation warnings should only apply to `#[rustc_deprecated]` as they take into account rustc's version. Fixes#57952.
I've also slightly modified rustdoc's display of future deprecation notices to make it more consistent, so I'm assigning a rustdoc team member for review to make sure this is okay.
r? @GuillaumeGomez
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!
rustdoc: overhaul code block lexing errors
Fixes#53919.
This PR moves the reporting of code block lexing errors from rendering time to an early pass, so we can use the compiler's error reporting mechanisms. This dramatically improves the diagnostics in this situation: we now de-emphasize the lexing errors as a note under a warning that has a span and suggestion instead of just emitting errors at the top level.
Additionally, this PR generalizes the markdown -> source span calculation function, which should allow other rustdoc warnings to use better spans in the future.
Last, the PR makes sure that the code block is always emitted in the docs, even if it fails to highlight correctly.
Of note:
- The new pass unfortunately adds another pass over the docs to gather the doc blocks for syntax-checking. I wonder if this could be combined with the pass that looks for testable blocks? I'm not familiar with that code, so I don't know how feasible that is.
- `pulldown_cmark` doesn't make it easy to find the spans of the code blocks, so the code that calculates the spans is a little nasty. It works for all the test cases I threw at it, but I wouldn't be surprised if an edge case would break it. Should have a thorough review.
- This PR worsens the state of #56885, since those certain fatal lexing errors are now emitted before docs get generated at all.
Fix stack overflow when finding blanket impls
Currently, SelectionContext tries to prevent stack overflow by keeping
track of the current recursion depth. However, this depth tracking is
only used when performing normal section (which includes confirmation).
No such tracking is performed for evaluate_obligation_recursively, which
can allow a stack overflow to occur.
To fix this, this commit tracks the current predicate evaluation depth.
This is done separately from the existing obligation depth tracking:
an obligation overflow can occur across multiple calls to 'select' (e.g.
when fulfilling a trait), while a predicate evaluation overflow can only
happen as a result of a deep recursive call stack.
Fixes#56701
I've re-used `tcx.sess.recursion_limit` when checking for predication evaluation overflows. This is such a weird corner case that I don't believe it's necessary to have a separate setting controlling the maximum depth.
Simplify foreign type rendering.
Simplified foreign type rendering by switching from tables to flexbox. Also, removed some seemingly extraneous elements like “ghost” spans.
Reduces element count on the `std::iter::Iterator` page by 30%. On my laptop it drops Iterator page load time from ~15s to ~10s. Frame times during scrolling are a hair lower too.
Known visual changes (happy to tweak based on feedback):
* The main `impl ...` headers are now getting the default, larger, h3 font size. This was an accident, but I liked how it turned out so I didn't fix it.
* There's a hair less vertical spacing between the end of a where block and the start of the next fn. Now, all spacing is consistent. I think this looks a bit worse. I may tweak vertical spacing more here or in a follow-up that cleans up vertical spacing more broadly.
* "[src]" links are all sized at 17px. A few were 19px in the original.
I haven't yet done heavy cross-browser or cross-crate testing. I was hoping to get a quick thumbs up or thumbs down here at this first draft, then if this is on the right track I'll spend some time on that testing.
TODO:
- [x] Test on Chrome
- [x] Test on Firefox
- [ ] ~~Test on UC Android~~
- [x] Test on Edge
- [x] Test on iOS safari
- [x] Test on desktop safari
- [x] Update automated tests
- [x] Increase vertical margin
- [x] Fix "Important traits for" hover overlap
- [x] Wait for #55798 to land & merge it
use utf-8 throughout htmldocck
This commit improves compatibility with Python 3, which already uses
Unicode throughout.
It also fixes a subtle incompatibility stemming from the use of
`entitydefs`, which contains replacement text _encoded in latin-1_ for
HTML entities. When using Python 3, this would cause `0xa0` to be
incorrectly added to the element tree.
This meant that there was a rustdoc test that would pass under Python 2
but fail under Python 3, due to an incorrect regex match against the
non-breaking space character. This commit triggers that failure in both
versions, and also fixes it.
This commit improves compatibility with Python 3, which already uses
Unicode throughout.
It also fixes a subtle incompatibility stemming from the use of
`entitydefs`, which contains replacement text _encoded in latin-1_ for
HTML entities. When using Python 3, this would cause `0xa0` to be
incorrectly added to the element tree.
This meant that there was a rustdoc test that would pass under Python 2
but fail under Python 3, due to an incorrect regex match against the
non-breaking space character. This commit triggers that failure in both
versions, and also fixes it.
Currently, SelectionContext tries to prevent stack overflow by keeping
track of the current recursion depth. However, this depth tracking is
only used when performing normal section (which includes confirmation).
No such tracking is performed for evaluate_obligation_recursively, which
can allow a stack overflow to occur.
To fix this, this commit tracks the current predicate evaluation depth.
This is done separately from the existing obligation depth tracking:
an obligation overflow can occur across multiple calls to 'select' (e.g.
when fulfilling a trait), while a predicate evaluation overflow can only
happen as a result of a deep recursive call stack.
Fixes#56701
Simplified foreign type rendering by switching from tables to flexbox. Also, removed some seemingly extraneous elements like “ghost” spans.
Reduces element count on std::iter::Iterator by 30%.
Call poly_project_and_unify_type on types that contain inference types
Commit f57247c48c (Ensure that Rusdoc discovers all necessary auto
trait bounds) added a check to ensure that we only attempt to unify a
projection predicatre with inference variables. However, the check it
added was too strict - instead of checking that a type *contains* an
inference variable (e.g. '&_', 'MyType<_>'), it required the type to
*be* an inference variable (i.e. only '_' would match).
This commit relaxes the check to use 'ty.has_infer_types', ensuring that
we perform unification wherever possible.
Fixes#56822
rustdoc: add new CLI flag to load static files from a different location
This PR adds a new CLI flag to rustdoc, `--static-root-path`, which controls how rustdoc links pages to the CSS/JS/font static files bundled with the output. By default, these files are linked with a series of `../` which is calculated per-page to link it to the documentation root - i.e. a relative link to the directory given by `-o`. This is causing problems for docs.rs, because even though docs.rs has saved one copy of these files and is dispatching them dynamically, browsers have no way of knowing that these are the same files and can cache them. This can allow it to link these files as, for example, `/rustdoc.css` instead of `../../rustdoc.css`, creating a single location that the files are loaded from.
I made sure to only change links for the *static* files, those that don't change between crates. Files like the search index, aliases, the source files listing, etc, are still linked with relative links.
r? @GuillaumeGomez
cc @onur
rustdoc: look for comments when scraping attributes/crates from doctests
Fixes https://github.com/rust-lang/rust/issues/56727
When scraping out crate-level attributes and `extern crate` statements, we wouldn't look for comments, so any presence of comments would shunt it and everything after it into "everything else". This could cause parsing issues when looking for `fn main` and `extern crate my_crate` later on, which would in turn cause rustdoc to incorrectly wrap a test with `fn main` when it already had one declared.
I took the opportunity to clean up the logic a little bit, but it would still benefit from a libsyntax-based loop like the `fn main` detection.
Commit f57247c48c (Ensure that Rusdoc discovers all necessary auto
trait bounds) added a check to ensure that we only attempt to unify a
projection predicatre with inference variables. However, the check it
added was too strict - instead of checking that a type *contains* an
inference variable (e.g. '&_', 'MyType<_>'), it required the type to
*be* an inference variable (i.e. only '_' would match).
This commit relaxes the check to use 'ty.has_infer_types', ensuring that
we perform unification wherever possible.
Fixes#56822
Ensure that Rustdoc discovers all necessary auto trait bounds
Fixes#50159
This commit makes several improvements to AutoTraitFinder:
* Call infcx.resolve_type_vars_if_possible before processing new
predicates. This ensures that we eliminate inference variables wherever
possible.
* Process all nested obligations we get from a vtable, not just ones
with depth=1.
* The 'depth=1' check was a hack to work around issues processing
certain predicates. The other changes in this commit allow us to
properly process all predicates that we encounter, so the check is no
longer necessary,
* Ensure that we only display predicates *without* inference variables
to the user, and only attempt to unify predicates that *have* an
inference variable as their type.
Additionally, the internal helper method is_of_param now operates
directly on a type, rather than taking a Substs. This allows us to use
the 'self_ty' method, rather than directly dealing with Substs.
If we end up with a projection predicate that equates a type with
itself (e.g. <T as MyType>::Value == <T as MyType>::Value), we can
run into issues if we try to add it to our ParamEnv.
Fixes#50159
This commit makes several improvements to AutoTraitFinder:
* Call infcx.resolve_type_vars_if_possible before processing new
predicates. This ensures that we eliminate inference variables wherever
possible.
* Process all nested obligations we get from a vtable, not just ones
with depth=1.
* The 'depth=1' check was a hack to work around issues processing
certain predicates. The other changes in this commit allow us to
properly process all predicates that we encounter, so the check is no
longer necessary,
* Ensure that we only display predicates *without* inference variables
to the user, and only attempt to unify predicates that *have* an
inference variable as their type.
Additionally, the internal helper method is_of_param now operates
directly on a type, rather than taking a Substs. This allows us to use
the 'self_ty' method, rather than directly dealing with Substs.
Check for negative impls when finding auto traits
Fixes#55321
When AutoTraitFinder begins examining a type, it checks for an explicit
negative impl. However, it wasn't checking for negative impls found when
calling 'select' on predicates found from nested obligations.
This commit makes AutoTraitFinder check for negative impls whenever it
makes a call to 'select'. If a negative impl is found, it immediately
bails out.
Normal users of SelectioContext don't need to worry about this, since
they stop as soon as an Unimplemented error is encountered. However, we
add predicates to our ParamEnv when we encounter this error, so we need
to handle negative impls specially (so that we don't try adding them to
our ParamEnv).
Choose predicates without inference variables over those with them
Fixes#54705
When constructing synthetic auto trait impls, we may come across
multiple predicates involving the same type, trait, and substitutions.
Since we can only display one of these, we pick the one with the 'most
strict' lifetime paramters. This ensures that the impl we render the
user is actually valid (that is, a struct matching that impl will
actually implement the auto trait in question).
This commit exapnds the definition of 'more strict' to take into account
inference variables. We always choose a predicate without inference
variables over a predicate with inference variables.
test that rustdoc doesn't overflow on a big enum
Adds a test to close#25295. The test case depended on `enum_primitive` so I just basically pulled its source into an auxiliary file, is that the right way to do it?
Add index page argument
@Mark-Simulacrum: I might need some help from you: in bootstrap, I want to add an argument (a new flag added into `rustdoc`) in order to generate the current index directly when `rustdoc` is documenting the `std` lib. However, my change in `bootstrap` didn't do it and I assume it must be moved inside the `Std` struct. But there, I don't see how to pass it to `rustdoc` through `cargo`. Did I miss anything?
r? @QuietMisdreavus
Fixes#54705
When constructing synthetic auto trait impls, we may come across
multiple predicates involving the same type, trait, and substitutions.
Since we can only display one of these, we pick the one with the 'most
strict' lifetime paramters. This ensures that the impl we render the
user is actually valid (that is, a struct matching that impl will
actually implement the auto trait in question).
This commit exapnds the definition of 'more strict' to take into account
inference variables. We always choose a predicate without inference
variables over a predicate with inference variables.
Rollup of 21 pull requests
Successful merges:
- #54816 (Don't try to promote already promoted out temporaries)
- #54824 (Cleanup rustdoc tests with `@!has` and `@!matches`)
- #54921 (Add line numbers option to rustdoc)
- #55167 (Add a "cheap" mode for `compute_missing_ctors`.)
- #55258 (Fix Rustdoc ICE when checking blanket impls)
- #55264 (Compile the libstd we distribute with -Ccodegen-unit=1)
- #55271 (Unimplement ExactSizeIterator for MIR traversing iterators)
- #55292 (Macro diagnostics tweaks)
- #55298 (Point at macro definition when no rules expect token)
- #55301 (List allowed tokens after macro fragments)
- #55302 (Extend the impl_stable_hash_for! macro for miri.)
- #55325 (Fix link to macros chapter)
- #55343 (rustbuild: fix remap-debuginfo when building a release)
- #55346 (Shrink `Statement`.)
- #55358 (Remove redundant clone (2))
- #55370 (Update mailmap for estebank)
- #55375 (Typo fixes in configure_cmake comments)
- #55378 (rustbuild: use configured linker to build boostrap)
- #55379 (validity: assert that unions are non-empty)
- #55383 (Use `SmallVec` for the queue in `coerce_unsized`.)
- #55391 (bootstrap: clean up a few clippy findings)
Report const eval error inside the query
Functional changes: We no longer warn about bad constants embedded in unused types. This relied on being able to report just a warning, not a hard error on that case, which we cannot do any more now that error reporting is consistently centralized.
r? @RalfJung
fixes#53561
Fix Rustdoc ICE when checking blanket impls
Fixes#55001, #54744
Previously, SelectionContext would unconditionally cache the selection
result for an obligation. This worked fine for most users of
SelectionContext, but it caused an issue when used by Rustdoc's blanket
impl finder.
The issue occured when SelectionContext chose a ParamCandidate which
contained inference variables. Since inference variables can change
between calls to select(), it's not safe to cache the selection result -
the chosen candidate might not be applicable for future results, leading
to an ICE when we try to run confirmation.
This commit prevents SelectionContext from caching any ParamCandidate
that contains inference variables. This should always be completely
safe, as trait selection should never depend on a particular result
being cached.
I've also added some extra debug!() statements, which I found helpful in
tracking down this bug.
Fixes#55321
When AutoTraitFinder begins examining a type, it checks for an explicit
negative impl. However, it wasn't checking for negative impls found when
calling 'select' on predicates found from nested obligations.
This commit makes AutoTraitFinder check for negative impls whenever it
makes a call to 'select'. If a negative impl is found, it immediately
bails out.
Normal users of SelectioContext don't need to worry about this, since
they stop as soon as an Unimplemented error is encountered. However, we
add predicates to our ParamEnv when we encounter this error, so we need
to handle negative impls specially (so that we don't try adding them to
our ParamEnv).
Fixes#55001, #54744
Previously, SelectionContext would unconditionally cache the selection
result for an obligation. This worked fine for most users of
SelectionContext, but it caused an issue when used by Rustdoc's blanket
impl finder.
The issue occured when SelectionContext chose a ParamCandidate which
contained inference variables. Since inference variables can change
between calls to select(), it's not safe to cache the selection result -
the chosen candidate might not be applicable for future results, leading
to an ICE when we try to run confirmation.
This commit prevents SelectionContext from caching any ParamCandidate
that contains inference variables. This should always be completely
safe, as trait selection should never depend on a particular result
being cached.
I've also added some extra debug!() statements, which I found helpful in
tracking down this bug.
Fix spelling in the documentation to htmldocck.py
I was reading through htmldocck.py, and decided to attempt to clean it up a little bit. Let me know if you disagree with my edits.
The link that is matched against is not the same as would be generated by
rustdoc. We should also check that the `foo/private` directory is not generated
at all.
The generated code would look like `<code>impl <a href="...">Foo</a></code>`
which the plain text matcher doesn't match. But by using the XPATH notation, the
nodes are flattened and we can correctly assert that `impl Foo` does not occur
in the generated docs.
The Auto Trait Implementation section is not wrapped in a
`synthetic-implementations` class. In fact, it is wrapped in a
`synthetic-implementations` id. However, we can generalize and completely remove
the `synthetic-implementations` requirement. We just have to verify that there's
no mention of "Auto Trait Implementations" anywhere.
Struct names are no longer encapsulated in `<code>` tags, which meant that the
test was not correctly verifying that it wasn't being show. I've also added a
check to make sure the documentation page for the redirect::Qux struct is not
generated at all.
The `@!has` command does not support specifying just a PATH and an XPATH. That
means that the previous test searched for the literal string
`//h2[@id="implementations"]` within the generated output, which obviously
didn't exist. Even after adding a trait implementation, the test still passed.
The correct way to check for the existence of a DOM element with the id
`implementations` is to use the `@count` keyword.
"Run" links to the playground are not added to the generated documentation if
the unstable `--playground-url` argument is not passed to rustdoc. Therefore,
without specifying `--playground-url` as a compile-flag, the test doesn't
correctly assert that `#![doc(html_playground_url = "")]` removes playground
links.
The old test was supposed to check for proper html escaping when showing the
contents of constants. This was changed as part of #53409. The revised test
asserts that the contents of the constant is not shown as part of the generated
documentation.
rustdoc: give proc-macros their own pages
related to https://github.com/rust-lang/rust/issues/49553 but i don't think it'll fix it
Currently, rustdoc doesn't expose proc-macros all that well. In the source crate, only their definition function is exposed, but when re-exported, they're treated as a macro! This is an awkward situation in all accounts. This PR checks functions to see whether they have any of `#[proc_macro]`, `#[proc_macro_attribute]`, or `#[proc_macro_derive]`, and exposes them as macros instead. In addition, attributes and derives are exposed differently than other macros, getting their own item-type, CSS class, and module heading.
Function-like proc-macros are lumped in with `macro_rules!` macros, but they get a different declaration block (i'm open to tweaking this, it's just what i thought of given how function-proc-macros operate):
Proc-macro attributes and derives get their own pages, with a representative declaration block. Derive macros also show off their helper attributes:
There's one wrinkle which this PR doesn't address, which is why i didn't mark this as fixing the linked issue. Currently, proc-macros don't expose their attributes or source span across crates, so while rustdoc knows they exist, that's about all the information it gets. This leads to an "inlined" macro that has absolutely no docs on it, and no `[src]` link to show you where it was declared.
The way i got around it was to keep proc-macro re-export disabled, since we do get enough information across crates to properly link to the source page:
Until we can get a proc-macro's docs (and ideally also its source span) across crates, i believe this is the best way forward.
overlook overflows in rustdoc trait solving
Context:
The new rustdoc "auto trait" feature walks across impls and tries to run trait solving on them with a lot of unconstrained variables. This is prone to overflows. These overflows used to cause an ICE because of a caching bug (fixed in this PR). But even once that is fixed, it means that rustdoc causes an overflow rather than generating docs.
This PR therefore adds a new helper that propagates the overflow error out. This requires rustdoc to then decide what to do when it encounters such an overflow: technically, an overflow represents neither "yes" nor "no", but rather a failure to make a decision. I've decided to opt on the side of treating this as "yes, implemented", since rustdoc already takes an optimistic view. This may prove to include too many items, but I *suspect* not.
We could probably reduce the rate of overflows by unifying more of the parameters from the impl -- right now we only seem to consider the self type. Moreover, in the future, as we transition to Chalk, overflow errors are expected to just "go away" (in some cases, though, queries might return an ambiguous result).
Fixes#52873
cc @QuietMisdreavus -- this is the stuff we were talking about earlier
cc @GuillaumeGomez -- this supersedes #53687
Implement the `min_const_fn` feature gate
cc @RalfJung @eddyb
r? @Centril
implements the feature gate for #53555
I added a hack so the `const_fn` feature gate also enables the `min_const_fn` feature gate. This ensures that nightly users of `const_fn` don't have to touch their code at all.
The `min_const_fn` checks are run first, and if they succeeded, the `const_fn` checks are run additionally to ensure we didn't miss anything.
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
Fix missing impl trait display as ret type
I need to convert a `TraitPredicate` into a `TraitBound` to get the returned impl trait. So far, didn't find how or even if it was the good way to do it.
cc @eddyb @oli-obk (since you're the one behind the change apparently 😉)
