Make `TypeFolder::fold_*` return `Result`
Implements rust-lang/compiler-team#432.
Initially this is just a rebase of `@LeSeulArtichaut's` work in #85469 (abandoned; see https://github.com/rust-lang/rust/pull/85485#issuecomment-908781112). At that time, it caused a regression in performance that required some further exploration... with this rebased PR bors can hopefully report some perf analysis from which we can investigate further (if the regression is indeed still present).
r? `@jackh726` cc `@nikomatsakis`
rustdoc: Consolidate static-file replacement mechanism
There were a few places in rustdoc where we would take static JS or CSS and rewrite it at doc generation time to insert values. This consolidates all the CSS instances into one CSS file and replaces the JS examples with data- attributes on the rustdoc-vars div.
Demo https://rustdoc.crud.net/jsha/static-file-replace/test_docs/
r? ``@GuillaumeGomez``
Remove `--display-doctest-warnings`
`--display-doctest-warnings` can be replicated in full with other existing features, there's no
need to have a separate option for it. This removes the option and documents the combination of other features to replicate it.
This also fixes a bug where `--test-args=--show-output` had no effect.
cc `@ollie27,` https://github.com/rust-lang/rust/pull/73314#issuecomment-668317262
Fixes https://github.com/rust-lang/rust/issues/41574
r? `@GuillaumeGomez`
rustdoc: Rename `Type::ResolvedPath` to `Type::Path` and don't re-export it
The new name is shorter, simpler, and consistent with `hir::Ty`. It can't be
re-exported since the name would conflict with the `clean::Path` struct. But
usually enum variants are referred to using their qualified names in Rust anyway
(and parts of rustdoc already do that with `clean::Type`), so this is also more
consistent with the language.
r? `@GuillaumeGomez`
cc `@jyn514`
Fix another ICE in rustdoc scrape_examples
This has occurred to me when documenting a crate with the arguments. Not sure what could have caused it.
r? `@willcrichton`
This can be replicated in full with other existing features, there's no
need to have a separate option for it.
This also fixes a bug where `--test-args=--show-output` had no effect,
and updates the documentation.
I would like to rename it to `Type::Path`, but then it can't be
re-exported since the name would conflict with the `Path` struct.
Usually enum variants are referred to using their qualified names in
Rust (and parts of rustdoc already do that with `clean::Type`), so this
is also more consistent with the language.
rustdoc: Remove `ResolvedPath.did`
`ResolvedPath.did` was not actually the same as `.path.def_id()`. Instead,
`.did` referred to the `DefId` of the page to be used as a hyperlink target.
For example, a link to `Struct::method()` would use `Struct`'s `DefId` as its
`.did` field. This behavior is confusing, easy to accidentally misuse, and can
instead be obtained on-demand when computing hyperlink targets. It's also likely
part of the reason `kind_side_channel` exists. I'm currently working on some
experimental refactorings in `collect_intra_doc_links` that I believe require --
or at least benefit from -- removing `.did`.
r? `@jyn514`
Tokenize emoji as if they were valid identifiers
In the lexer, consider emojis to be valid identifiers and reject
them later to avoid knock down parse errors.
Partially address #86102.
We had been injecting the list of themes and the rustdoc version into
main.js by rewriting it at doc generation time. By avoiding this
rewrite, we can make it easier to edit main.js without regenerating all
the docs.
Added a more convenient accessor for rustdoc-vars.
Changed storage.js to not rely on resourcesSuffix. It could in theory
use rustdoc-vars, but because rustdoc-vars is at the end of the HTML,
it's not available when storage.js runs (very early in page load).
We carry around a list of stylesheets that can carry two different types
of thing:
1. Internal stylesheets specific to a page type (only for settings)
2. Themes
In this change I move the link generation for settings.css into
settings(), so Context.style_files is reserved just for themes.
We had two places where we extracted a base theme name from a list of
StylePaths. I consolidated that code to be a method on StylePath.
I moved generation of link tags for stylesheets into the page.html
template. With that change, I made the template responsible for special
handling of light.css (making it the default theme) and of the other
themes (marking them disabled). That allowed getting rid of the
`disabled` field on StylePath.
Before, if `register_res` were called on an associated item or enum
variant, it would return the parent's `DefId`. Now, it returns the
actual `DefId`.
This change is a step toward removing `Type::ResolvedPath.did` and
potentially removing `kind_side_channel` in rustdoc. It also just
simplifies rustdoc's behavior.
fix(doctest): detect extern crate items in statement doctests
This partially reverts #91026, because rustdoc needs to detect the extern statements, even when they appear inside implicit `main()`. It does not entirely revert it, so the old bug is still fixed, by duplicating some of the logic from `parse_mod` instead of trying to use it directly.
Fixes#91134
Inhibit clicks on summary's children
A byproduct of using `<details>` and `<summary>` to show/hide detailed documentation was that clicking any part of a method heading (or impl heading) would show or hide the documentation. This was not super noticeable because clicking a link inside the method heading would navigate to that link. But clicking any unlinked black text in a method heading would trigger the behavior.
That behavior was somewhat unexpected, and means that if you try to click a type name in a method heading, but miss by a few pixels, you get a confusing surprise.
This change inhibits that behavior by putting an event listener on most summaries that cancels the event unless the event target was the summary itself. In practice, that means it cancels the event unless the target was the "[+]" / "[-]", because the rest of the heading is wrapped inside a `<div>`, which is the target for anything that doesn't have a more specific target.
r? ``@Manishearth``
Avoid documenting top-level private imports
PR #88447 aimed to make rustdoc's `--document-private-items` mode only document imports that are visible outside the importing module. Unfortunately, I inadvertently set things up so that imports at the crate top-level are always documented, regardless of their visibility. This behavior was unintended and is [not desirable](https://github.com/rust-lang/rust/issues/90865#issuecomment-971172649).
This PR treats top-level imports as never being visible outside their parent module. In practice, the only way a top-level import can be visible externally is if it's fully public, and there's a seperate check for that.
It's worth calling attention to the fact that this change means that `pub(crate)` imports will be visible in lower level modules, but not at the top-level. This is because, at the top level of the crate, `pub(crate)` means the same thing as `pub(self)`.
It turned out that there were existing tests checking for the only behavior, which I didn't notice at the time of my previous PR. I have updated them to check for the new behavior and substantially extended them to handle differences between the top-level module and lower level modules. I may have gone overboard, so please tell me if there's anything I should cut.
r? `@jyn514`
Fixes#90865.
This partially reverts #91026, because rustdoc needs to detect the extern statements,
even when they appear inside implicit `main()`. It does not entirely revert it,
so the old bug is still fixed, by duplicating some of the logic from `parse_mod`
instead of trying to use it directly.
Fixes#91134
Set color for <a> in a more straightforward way.
Previously, we set the default color for <a> tags to black, and then had an override with a bunch of not() clauses to set anchors in
docblocks to blue.
Instead, we should set the default color for <a> to blue (or equivalent in other themes), and override it for places like the sidebar or search results, where we don't want them to be styled as links.
Demo at https://rustdoc.crud.net/jsha/theme-anchor/std/string/struct.String.html. This should result in no visible changes.
r? `@GuillaumeGomez`
Previously, we set the default color for <a> tags to black, and then
had an override with a bunch of not() clauses to set anchors in
docblocks to blue.
Instead, we should set the default color for <a> to blue (or equivalent
in other themes), and override it for places like the sidebar or search
results, where we don't want them to be styled as links.
A byproduct of using `<details>` and `<summary>` to show/hide detailed
documentation was that clicking any part of a method heading (or impl
heading) would show or hide the documentation. This was not super
noticeable because clicking a link inside the method heading would
navigate to that link. But clicking any unlinked black text in a method
heading would trigger the behavior.
That behavior was somewhat unexpected, and means that if you try to click
a type name in a method heading, but miss by a few pixels, you get a
confusing surprise.
This change inhibits that behavior by putting an event listener on most
summaries that cancels the event unless the event target was the summary
itself. In practice, that means it cancels the event unless the target
was the "[+]" / "[-]", because the rest of the heading is wrapped inside
a `<div>`, which is the target for anything that doesn't have a more
specific target.
Make scrollbar in the sidebar always visible for visual consistency
Fixes#90943.
I had to add a background in `dark` and `ayu` themes, otherwise it was looking strange (like an invisible margin). So it looks like this:
Sadly, I wasn't able to add a GUI test to ensure that the scrollbar was always displayed because it seems not possible in puppeteer for whatever reason... I used this method: on small pages (like `lib2/sub_mod/index.html`), comparing `.navbar`'s `clientWidth` with `offsetWidth` (the first doesn't include the sidebar in the computed amount). When checking in the browser, it works fine but in puppeteer it almost never works...
In case anyone want to try to solve the bug, here is the puppeteer code:
<details>
More information about this: I tried another approach which was to get the element in `evaluate` directly (by calling it from `page.evaluate(() => { .. });` directly instead of `parseAssertElemProp.evaluate(e => {...});`.
```js
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto("file:///path/rust/build/x86_64-unknown-linux-gnu/test/rustdoc-gui/doc/lib2/sub_mod/index.html");
await page.waitFor(".sidebar");
let parseAssertElemProp = await page.$(".sidebar");
if (parseAssertElemProp === null) { throw '".sidebar" not found'; }
await parseAssertElemProp.evaluate(e => {
const parseAssertElemPropDict = {"clientWidth": "192", "offsetWidth":"200"};
for (const [parseAssertElemPropKey, parseAssertElemPropValue] of Object.entries(parseAssertElemPropDict)) {
if (e[parseAssertElemPropKey] === undefined || String(e[parseAssertElemPropKey]) != parseAssertElemPropValue) {
throw 'expected `' + parseAssertElemPropValue + '` for property `' + parseAssertElemPropKey + '` for selector `.sidebar`, found `' + e[parseAssertElemPropKey] + '`';
}
}
}).catch(e => console.error(e));
await browser.close();
})();
```
</details>
r? ``@jsha``
