rustdoc: list matching impls on type aliases #115201

notriddle · 2023-08-25T04:38:41Z

Fixes #32077

Partially reverts #112543, 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 (#21903).

r? @GuillaumeGomez

CC @lcnr

Remake of "List matching impls on type aliases" * 4b1d13d * 6f552c8 * 2ce7cd9 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 (rust-lang#21903).

src/librustdoc/html/render/mod.rs

lcnr

from a types team pov this is fine, don't know the code structure of rustdoc well enough to review the rest of this change

src/librustdoc/html/render/mod.rs

Co-authored-by: León Orell Valerian Liehr <[email protected]>

GuillaumeGomez · 2023-09-08T11:47:49Z

Time to merge it then. Thanks everyone!

@bors r+

bors · 2023-09-08T11:47:51Z

📌 Commit b3686c2 has been approved by GuillaumeGomez

It is now in the queue for this repository.

…llaumeGomez Rollup of 6 pull requests Successful merges: - rust-lang#104299 (Clarify stability guarantee for lifetimes in enum discriminants) - rust-lang#115088 (Fix Step Skipping Caused by Using the `--exclude` Option) - rust-lang#115201 (rustdoc: list matching impls on type aliases) - rust-lang#115633 (Lint node for `PRIVATE_BOUNDS`/`PRIVATE_INTERFACES` is the item which names the private type) - rust-lang#115638 (`-Cllvm-args` usability improvement) - rust-lang#115643 (fix: return early when has tainted in mir-lint) r? `@ghost` `@rustbot` modify labels: rollup

Rollup merge of rust-lang#115201 - notriddle:notriddle/type-alias-impl-list, r=GuillaumeGomez rustdoc: list matching impls on type aliases Fixes rust-lang#32077 Fixes rust-lang#99952 Remake of rust-lang#112429 Partially reverts rust-lang#112543, 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 (rust-lang#21903). r? `@GuillaumeGomez` CC `@lcnr`

steffahn · 2023-09-09T18:47:23Z

Probably intended (and it probably is more useful this way), but “fun” side-effect (of this general change, I suppose): The documentation of nalgebra (default features, built locally from the same source) casually grows from 27MB to 515MB between 1.72 and nightly 62ebe3a2b 2023-09-08. Admitted, they are combining a ton of type aliases with a ton of impls, so it’s all nice and quadratic.

Also, is it intended that none of the impls and methods appear in the side-bar? This makes navigating, especially pages with lots of contents, rather hard.

steffahn · 2023-09-09T19:01:04Z

Though this makes me wonder whether perhaps an opt-out option is wanted. For ndalgebra, they might want to opt-out of increasing the docs size at least for the deprecated aliases they have, which on first glance feels like it’s almost half of their type aliases (i.e. perhaps truly about half of the HTML content?)

For typenum which has a similar magnitude of size increase (44MB to 523MB for me), it seems like the additional impls on all the constants it probably not worth the additional file size (and documentation time either).

I know this is a merged PR. If this this sounds like a reasonable concern to you, I’m glad to open an issue.

GuillaumeGomez · 2023-09-09T19:11:52Z

Also, is it intended that none of the impls and methods appear in the side-bar? This makes navigating, especially pages with lots of contents, rather hard.

It's a bug and it will be solved in #115682.

Please open an issue and link to this PR. I think the concern is valid, and it might be possible to add a mechanism to allow to disable this behaviour, but it needs to be discussed first about:

Do we want to allow people to opt out of this feature?
How do we disable this feature?
- A global attribute?
- A command line option?
- An attribute to be used on each type alias?
- An attribute to be used on module?

Of course, any of the item above can be combined with others. Lot of possibilities. ;)

…GuillaumeGomez rustdoc: add impl items from aliased type into sidebar Follow-up of rust-lang#115201.

…r=<try> 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 *Review note: This is mostly just reverting rust-lang#115201. The last commit has the new work in it.* Fixes rust-lang#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

…r=GuillaumeGomez 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 (aa1a71e 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 rust-lang#115201. The last commit has the new work in it.* Fixes rust-lang#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

…meGomez 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 rust-lang/rust#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

notriddle and others added 2 commits August 24, 2023 21:36

Fix intra-doc links from pointer appearing in windows HANDLE type alias

20768b2

rustbot assigned GuillaumeGomez Aug 25, 2023

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Aug 25, 2023

GuillaumeGomez approved these changes Aug 25, 2023

View reviewed changes

fmease reviewed Aug 25, 2023

View reviewed changes

src/librustdoc/html/render/mod.rs Outdated Show resolved Hide resolved

fmease reviewed Aug 25, 2023

View reviewed changes

src/librustdoc/html/render/mod.rs Outdated Show resolved Hide resolved

lcnr reviewed Aug 26, 2023

View reviewed changes

src/librustdoc/html/render/mod.rs Outdated Show resolved Hide resolved

notriddle force-pushed the notriddle/type-alias-impl-list branch from e452bbe to b3686c2 Compare August 26, 2023 19:35

Add note about lazy_type_alias

b3686c2

Co-authored-by: León Orell Valerian Liehr <[email protected]>

GuillaumeGomez approved these changes Sep 8, 2023

View reviewed changes

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Sep 8, 2023

This was referenced Sep 8, 2023

rustdoc: show inner enum and struct in type definition for concrete type #114855

Merged

Rollup of 6 pull requests #115672

Merged

bors merged commit 1fb672c into rust-lang:master Sep 8, 2023
11 checks passed

rustbot added this to the 1.74.0 milestone Sep 8, 2023

notriddle deleted the notriddle/type-alias-impl-list branch September 8, 2023 16:07

GuillaumeGomez mentioned this pull request Sep 9, 2023

rustdoc: add impl items from aliased type into sidebar #115682

Merged

steffahn mentioned this pull request Sep 9, 2023

Documentation size can grow significantly due to documentation of impls on type aliases #115718

Closed

bors added a commit to rust-lang-ci/rust that referenced this pull request Sep 10, 2023

Auto merge of rust-lang#115682 - notriddle:notriddle/impl-sidebar, r=…

030e4d3

…GuillaumeGomez rustdoc: add impl items from aliased type into sidebar Follow-up of rust-lang#115201.

fmease mentioned this pull request Sep 23, 2023

Generate documentation for type aliases/definitions #113727

Closed

notriddle mentioned this pull request Oct 6, 2023

rustdoc: use JS to inline target type impl docs into alias #116471

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

rustdoc: list matching impls on type aliases #115201

rustdoc: list matching impls on type aliases #115201

notriddle commented Aug 25, 2023 •

edited

Loading

lcnr left a comment

GuillaumeGomez commented Sep 8, 2023

bors commented Sep 8, 2023

steffahn commented Sep 9, 2023

steffahn commented Sep 9, 2023 •

edited

Loading

GuillaumeGomez commented Sep 9, 2023

rustdoc: list matching impls on type aliases #115201

rustdoc: list matching impls on type aliases #115201

Conversation

notriddle commented Aug 25, 2023 • edited Loading

lcnr left a comment

Choose a reason for hiding this comment

GuillaumeGomez commented Sep 8, 2023

bors commented Sep 8, 2023

steffahn commented Sep 9, 2023

steffahn commented Sep 9, 2023 • edited Loading

GuillaumeGomez commented Sep 9, 2023

notriddle commented Aug 25, 2023 •

edited

Loading

steffahn commented Sep 9, 2023 •

edited

Loading