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.
