| Age | Commit message (Collapse) | Author | Lines |
|---|
|
detects redundant imports that can be eliminated.
for #117772 :
In order to facilitate review and modification, split the checking code and
removing redundant imports code into two PR.
|
|
The deprecation notice is used when in crates as well. This applies to versions Rust or Crates.
Fixes #118148
Signed-off-by: Harold Dost <h.dost@criteo.com>
|
|
This is about equally readable, a lot more terse, and stops
special-casing functions and methods.
```console
$ du -hs doc-old/ doc-new/
671M doc-old/
670M doc-new/
```
|
|
There's no such thing as a big section header, so I don't know why the
name was used.
|
|
They're only used for HTML, so it makes more sense for them to live
their.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Parse rustc version at compile time
This PR eliminates a couple awkward codepaths where it was not clear how the compiler should proceed if its own version number is incomprehensible.
https://github.com/rust-lang/rust/blob/dab715641e96a61a534587fda9de1128b75b34dc/src/tools/clippy/clippy_utils/src/qualify_min_const_fn.rs#L385
https://github.com/rust-lang/rust/blob/dab715641e96a61a534587fda9de1128b75b34dc/compiler/rustc_attr/src/builtin.rs#L630
We can guarantee that every compiled rustc comes with a working version number, so the ICE codepaths above shouldn't need to be written.
|
|
rustdoc: use JS to inline target type impl docs into alias
Preview docs:
- https://notriddle.com/rustdoc-html-demo-5/js-trait-alias/std/io/type.Result.html
- https://notriddle.com/rustdoc-html-demo-5/js-trait-alias-compiler/rustc_middle/ty/type.PolyTraitRef.html
This pull request also includes a bug fix for trait alias inlining across crates. This means more documentation is generated, and is why ripgrep runs slower (it's a thin wrapper on top of the `grep` crate, so 5% of its docs are now the Result type).
- Before, built with rustdoc 1.75.0-nightly (aa1a71e9e 2023-10-26), Result type alias method docs are missing: http://notriddle.com/rustdoc-html-demo-5/ripgrep-js-nightly/rg/type.Result.html
- After, built with this branch, all the methods on Result are shown: http://notriddle.com/rustdoc-html-demo-5/ripgrep-js-trait-alias/rg/type.Result.html
*Review note: This is mostly just reverting https://github.com/rust-lang/rust/pull/115201. The last commit has the new work in it.*
Fixes #115718
This is an attempt to balance three problems, each of which would
be violated by a simpler implementation:
- A type alias should show all the `impl` blocks for the target
type, and vice versa, if they're applicable. If nothing was
done, and rustdoc continues to match them up in HIR, this
would not work.
- Copying the target type's docs into its aliases' HTML pages
directly causes far too much redundant HTML text to be generated
when a crate has large numbers of methods and large numbers
of type aliases.
- Using JavaScript exclusively for type alias impl docs would
be a functional regression, and could make some docs very hard
to find for non-JS readers.
- Making sure that only applicable docs are show in the
resulting page requires a type checkers. Do not reimplement
the type checker in JavaScript.
So, to make it work, rustdoc stashes these type-alias-inlined docs
in a JSONP "database-lite". The file is generated in `write_shared.rs`,
included in a `<script>` tag added in `print_item.rs`, and `main.js`
takes care of patching the additional docs into the DOM.
The format of `trait.impl` and `type.impl` JS files are superficially
similar. Each line, except the JSONP wrapper itself, belongs to a crate,
and they are otherwise separate (rustdoc should be idempotent). The
"meat" of the file is HTML strings, so the frontend code is very simple.
Links are relative to the doc root, though, so the frontend needs to fix
that up, and inlined docs can reuse these files.
However, there are a few differences, caused by the sophisticated
features that type aliases have. Consider this crate graph:
```text
---------------------------------
| crate A: struct Foo<T> |
| type Bar = Foo<i32> |
| impl X for Foo<i8> |
| impl Y for Foo<i32> |
---------------------------------
|
----------------------------------
| crate B: type Baz = A::Foo<i8> |
| type Xyy = A::Foo<i8> |
| impl Z for Xyy |
----------------------------------
```
The type.impl/A/struct.Foo.js JS file has a structure kinda like this:
```js
JSONP({
"A": [["impl Y for Foo<i32>", "Y", "A::Bar"]],
"B": [["impl X for Foo<i8>", "X", "B::Baz", "B::Xyy"], ["impl Z for Xyy", "Z", "B::Baz"]],
});
```
When the type.impl file is loaded, only the current crate's docs are
actually used. The main reason to bundle them together is that there's
enough duplication in them for DEFLATE to remove the redundancy.
The contents of a crate are a list of impl blocks, themselves
represented as lists. The first item in the sublist is the HTML block,
the second item is the name of the trait (which goes in the sidebar),
and all others are the names of type aliases that successfully match.
This way:
- There's no need to generate these files for types that have no aliases
in the current crate. If a dependent crate makes a type alias, it'll
take care of generating its own docs.
- There's no need to reimplement parts of the type checker in
JavaScript. The Rust backend does the checking, and includes its
results in the file.
- Docs defined directly on the type alias are dropped directly in the
HTML by `render_assoc_items`, and are accessible without JavaScript.
The JSONP file will not list impl items that are known to be part
of the main HTML file already.
[JSONP]: https://en.wikipedia.org/wiki/JSONP
|
|
|
|
|
|
|
|
|
|
This reverts commit 19edb3ce808ee2b1190026b9d56cc6187e1ad9b1.
|
|
This reverts commit b3686c2fd6ad57912e1b0e778bedb0b9a05c73fa.
|
|
This reverts commit c3e5ad448b87be31e570c048cf7ba3b1e7daec44.
|
|
r=GuillaumeGomez
rustdoc: hide `#[repr(transparent)]` if it isn't part of the public ABI
Fixes #90435.
This hides `#[repr(transparent)]` when the non-1-ZST field the struct is "transparent" over is private.
CC `@RalfJung`
Tentatively nominating it for the release notes, feel free to remove the nomination.
`@rustbot` label needs-fcp relnotes A-rustdoc-ui
|
|
rustdoc: show crate name beside smaller logo
*Blocked on https://github.com/rust-lang/cargo/pull/12800*
## Summary
In this PR, the crate name and version are always shown in the sidebar, even in subpages, and the lateral navigation is always shown in the sidebar, even in modules.
Clicking the crate name does the same thing clicking the logo always did: take you to the crate root (the crate's home page, at least within Rustdoc).
The Rust logo is also no longer shown by default for non-Rust docs.
### Screenshots
<details><summary>Before</summary>
| | Macro | Module |
|--|-------|--------|
| In crate |  |
| In module[^1] |  | 
[^1]: This PR also includes a bug fix for derive macros not showing up in the lateral navigation part of the sidebar
</details>
#### Whole sidebar screenshots
| | Macro | Module |
|--|-------|--------|
| In crate |  | 
| In module |  | 
#### Different logo configurations
| | Short crate name | Long crate name |
|---------|------------------|-----------------|
| Root | ![short-root] | ![long-root]
| Subpage | ![short-subpage] | ![long-subpage]
[short-root]: https://github.com/rust-lang/rust/assets/1593513/9e2b4fa8-f581-4106-b562-1e0372c13f79
[short-subpage]: https://github.com/rust-lang/rust/assets/1593513/8331cdb8-fa13-4671-a1e2-dcc1cdca7451
[long-root]: https://github.com/rust-lang/rust/assets/1593513/7d377fec-0f1d-4343-9f82-0e35a8f58056
[long-subpage]: https://github.com/rust-lang/rust/assets/1593513/3b3094a4-63c9-477c-8c15-b6075837df30
##### Without a logo
### Preview pages
https://notriddle.com/rustdoc-html-demo-5/sidebar-layout-rocket/rocket/index.html
https://notriddle.com/rustdoc-html-demo-5/sidebar-layout-rocket/rocket_sync_db_pools/index.html
https://notriddle.com/rustdoc-html-demo-5/sidebar-layout-rust-compiler/index.html
https://notriddle.com/rustdoc-html-demo-5/sidebar-layout-rust/std/index.html
https://notriddle.com/rustdoc-html-demo-5/sidebar-layout-rocket/tokio/index.html
## Motivation
This improves visual information density (the construct with the logo and crate name is *shorter* than the logo on its own, because it's not square) and navigation clarity (we can now see what clicking the Rust logo does, specifically).
Compare this with the layout at [Phoenix's Hexdocs] (which is what this proposal is closely based on), the old proposal on [Internals Discourse] (which always says "Rust standard library" in the sidebar, but doesn't do the side-by-side layout).
[Phoenix's Hexdocs]: https://hexdocs.pm/phoenix/1.7.7/overview.html
[Internals Discourse]: https://internals.rust-lang.org/t/poc-of-a-new-design-for-the-generated-rustdoc/11018
## Guide-level explanation
This PR cleans up some of the sidebar navigation.
It makes the logo in the desktop sidebar a bit smaller, and puts the crate name and version next to it (either beside it, or below it, depending on if there's space), making it clearer what clicking on it does: click the crate name to open the crate's home page. It also removes the Rust logo from non-official-Rust crates, again to make the navigation and supply chain clearer (since the crate name has been added, the logo is no longer necessary for navigation).
It adds a bit more clarifying information for lateral navigation. On items that don't add their own sidebar items, it just shows its siblings directly below the crate name and logo, but for other items, it shows "In crate alloc" instead of just "In alloc". It also shows the lateral navigation tools on module pages, making modules consistent with every other item.
## Drawbacks
While this actually takes up less screen real estate than the old layout on desktop, it takes up more HTML. It's also a bit more visually complex.
## Rationale and alternatives
I could do what the Internals POC did and keep the vertically stacked layout all the time, instead of doing a horizontal stack where possible. It would take up more screen real estate, though.
## Prior art
This design is lifted almost verbatim from Hexdocs. It seems to work for them. [`opentelemetry_process_propagator`], for example, has a long application name.
[`opentelemetry_process_propagator`]: https://hexdocs.pm/opentelemetry_process_propagator/OpentelemetryProcessPropagator.html
## Unresolved questions
Maybe we should encourage crate authors to include their own logo more often? It certainly helps give people a better sense of "place." This seems to be blocked on coming up with an API to do it without requiring them to host the file somewhere.
## Future possibilities
Beyond this, plenty of other changes could be made to improve the layout, like
* Fix things so that clicking an item in the sidebar doesn't cause it to scroll back to the top.
* The [Internals demo](https://utherii.github.io/new.html) does this right: clicking an item in the sidebar changes the content area, but the sidebar itself does not change. This is nice, because clicking is cheap and I can skim the opening few paragraphs while browsing.
* The layout of the docs sidebar causes trouble to implement this, because it's different on different pages, but at least fix this on the file browser.
* Come up with a less cluttered way to do disclosure. There's a lot of `[-]` on the page.
* We don't lack ideas to fix this one. We have *too many*.
* Do a better job of separating local navigation (vec::Vec links to vec::IntoIter) and the table of contents (vec::Vec links to vec::Vec::new).
* A possibility: add a Back arrow next to the "In [module]" header?
* Give readers more control of how much rustdoc shows them, and giving doc authors more control of how much it generates. Basically, https://github.com/rust-lang/rust/pull/115660 is great, let's do it too.
But those are mostly orthogonal, not future possibilities unlocked by this change.
|
|
|
|
Helps with #90929
This changes the search results, specifically, when there's more than
one impl with an associated item with the same name. For example,
the search queries `simd<i8> -> simd<i8>` and `simd<i64> -> simd<i64>`
don't link to the same function, but most of the functions have the
same names.
This change should probably be FCP-ed, especially since it adds a new
anchor link format for `main.js` to handle, so that URLs like
`struct.Vec.html#impl-AsMut<[T]>-for-Vec<T,+A>/method.as_mut` redirect
to `struct.Vec.html#method.as_mut-2`. It's a strange design, but there
are a few reasons for it:
* I'd like to avoid making the HTML bigger. Obviously, fixing this bug
is going to add at least a little more data to the search index, but
adding more HTML penalises viewers for the benefit of searchers.
* Breaking `struct.Vec.html#method.len` would also be a disappointment.
On the other hand:
* The path-style anchors might be less prone to link rot than the numbered
anchors. It's definitely less likely to have URLs that appear to "work",
but silently point at the wrong thing.
* This commit arranges the path-style anchor to redirect to the numbered
anchor. Nothing stops rustdoc from doing the opposite, making path-style
anchors the default and redirecting the "legacy" numbered ones.
|
|
rustdoc-search: add support for type parameters
r? `@GuillaumeGomez`
## Preview
* https://notriddle.com/rustdoc-html-demo-4/advanced-search/rustdoc/read-documentation/search.html
* https://notriddle.com/rustdoc-html-demo-4/advanced-search/std/index.html?search=option%3Coption%3CT%3E%3E%20-%3E%20option%3CT%3E
* https://notriddle.com/rustdoc-html-demo-4/advanced-search/std/index.html?search=option%3CT%3E,%20E%20-%3E%20result%3CT,%20E%3E
* https://notriddle.com/rustdoc-html-demo-4/advanced-search/std/index.html?search=-%3E%20option%3CT%3E
## Description
When writing a type-driven search query in rustdoc, specifically one with more than one query element, non-existent types become generic parameters instead of auto-correcting (which is currently only done for single-element queries) or giving no result. You can also force a generic type parameter by writing `generic:T` (and can force it to not use a generic type parameter with something like `struct:T` or whatever, though if this happens it means the thing you're looking for doesn't exist and will give you no results).
There is no syntax provided for specifying type constraints for generic type parameters.
When you have a generic type parameter in a search query, it will only match up with generic type parameters in the actual function, not concrete types that match, not concrete types that implement a trait. It also strictly matches based on when they're the same or different, so `option<T>, option<U> -> option<U>` matches `Option::and`, but not `Option::or`. Similarly, `option<T>, option<T> -> option<T>` matches `Option::or`, but not `Option::and`.
## Motivation
This feature is motivated by the many "combinitor"-type functions found in generic libraries, such as Option, Future, Iterator, and Entry. These highly-generic functions have names that are almost completely arbitrary, and a type signature that tells you what it actually does.
This PR is a major step towards[^closure] being able to easily search for generic functions by their type signature instead of by name. Some examples of combinators that can be found using this PR (try them out in the preview):
* `option<option<T>> -> option<T>` returns Option::flatten
* `option<T> -> result<T>` returns Option::ok_or
* `option<result<T>> -> result<option<T>>` returns Option::transpose
* `entry<K, V>, FnOnce -> V` returns `Entry::or_insert_with` (and `or_insert_with_key`, since there's no way to specify the generics on FnOnce)
[^closure]:
For this feature to be as useful as it ought to be, you should be able to search for *trait-associated types* and *closures*. This PR does not implement either of these: they are **Future possibilities**.
Trait-associated types would allow queries like `option<T> -> iterator<item=T>` to return `Option::iter`. We should also allow `option<T> -> iterator<T>` to match the associated type version.
Closures would make a good way to query for things like `Option::map`. Closure support needs associated types to be represented in the search index, since `FnOnce() -> i32` desugars to `FnOnce<Output=i32, ()>`, so associated trait types should be implemented first. Also, we'd want to expose an easy way to query closures without specifying which of the three traits you want.
|
|
|
|
when its syntax is used.
|
|
|
|
When writing a type-driven search query in rustdoc, specifically one
with more than one query element, non-existent types become generic
parameters instead of auto-correcting (which is currently only done
for single-element queries) or giving no result. You can also force a
generic type parameter by writing `generic:T` (and can force it to not
use a generic type parameter with something like `struct:T` or whatever,
though if this happens it means the thing you're looking for doesn't
exist and will give you no results).
There is no syntax provided for specifying type constraints
for generic type parameters.
When you have a generic type parameter in a search query, it will only
match up with generic type parameters in the actual function, not
concrete types that match, not concrete types that implement a trait.
It also strictly matches based on when they're the same or different,
so `option<T>, option<U> -> option<U>` matches `Option::and`, but not
`Option::or`. Similarly, `option<T>, option<T> -> option<T>`` matches
`Option::or`, but not `Option::and`.
|
|
Co-authored-by: León Orell Valerian Liehr <me@fmease.dev>
|
|
Remake of "List matching impls on type aliases"
* 4b1d13d9841c815915433ca2a3088a8e3e97ad96
* 6f552c800b38b3e71c5e33a295e8b490d2018c71
* 2ce7cd906bde70d8cbd9b07b31c6a7bf1131c345
Partially reverts "Fix infinite loop when retrieving impls for
type alias", but keeps the test case.
This version of the PR avoids the infinite loop by structurally
matching types instead of using full unification. This version
does not support type alias trait bounds, but the compiler does
not enforce those anyway
(https://github.com/rust-lang/rust/issues/21903).
|
|
|
|
|
|
This matches the name used by the Rust Reference [1], which is also what
people usually call these items.
[1]: https://doc.rust-lang.org/reference/items/type-aliases.html
|
|
|
|
|
|
|
|
|
|
|
|
|
|
r=fmease,GuillaumeGomez
rustdoc: fix position of `default` in method rendering
With the following code:
```rs
#![feature(specialization)]
pub trait A {
unsafe fn a();
}
impl A for () {
default unsafe fn a() {}
}
```
rustdoc would render the `impl` of `a` as
```rs
unsafe default fn a()
```
which is inconsistent with the actual position of `default`.
This PR fixes this issue.
|
|
The CSS uses an inconsistent mix of both. This commit switches
it to always use `src`.
|
|
|
|
|
|
Fix indentation for where clause in rustdoc pages
Screenshot of the bug:
I used this opportunity to clarify the code a bit because some weird things were going on.
r? ````@notriddle````
|
|
|
|
fmease:rustdoc-render-assoc-ty-body-before-where-clause, r=notriddle
rustdoc: render the body of associated types before the where-clause
Fixes #112903.
|
