-
Notifications
You must be signed in to change notification settings - Fork 12.8k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
rustdoc: use JS to inline target type impl docs into alias #116471
Conversation
r? @jsha (rustbot has picked a reviewer for you, use r? to override) |
Some changes occurred in GUI tests. These commits modify the If this was unintentional then you should revert the changes before this PR is merged. Some changes occurred in HTML/CSS/JS. cc @GuillaumeGomez, @jsha |
5b7b756
to
0243d95
Compare
These commits modify the If this was unintentional then you should revert the changes before this PR is merged. Some changes occurred in HTML/CSS/JS. cc @GuillaumeGomez, @jsha Some changes occurred in GUI tests. |
0243d95
to
8ab73e5
Compare
This comment has been minimized.
This comment has been minimized.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
@@ -587,6 +588,177 @@ function preLoadCss(cssUrl) { | |||
window.register_implementors(window.pending_implementors); | |||
} | |||
|
|||
// <https://github.com/search?q=repo%3Arust-lang%2Frust+[RUSTDOCIMPL]+type.impl&type=code> | |||
window.register_type_impls = imp => { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Also, could you add some comments explaining a bit more what it is manipulating and what it's generating? Not sure what the best format would be here though. There are a lot of smaller "sections" in the code, so maybe have a comment for each section explaining what it's doing instead of a big one explaining everything at the start? What do you think?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah, it definitely needs more doc comment.
This is a great PR. I didn't see any big issue from it. Considering how big it is, it's very likely I missed things so might be better to get a second reviewer as well. Also, once updated, can you start a perf check please? I expect a big improvement in doc size but I'm curious about the impact on the doc generation. |
This comment has been minimized.
This comment has been minimized.
319cb34
to
760c7f0
Compare
@bors try @rust-timer queue |
This comment has been minimized.
This comment has been minimized.
…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
☀️ Try build successful - checks-actions |
This comment has been minimized.
This comment has been minimized.
Finished benchmarking commit (a68b523): comparison URL. Overall result: ❌✅ regressions and improvements - ACTION NEEDEDBenchmarking this pull request likely means that it is perf-sensitive, so we're automatically marking it as not fit for rolling up. While you can manually mark this PR as fit for rollup, we strongly recommend not doing so since this PR may lead to changes in compiler perf. Next Steps: If you can justify the regressions found in this try perf run, please indicate this with @bors rollup=never Instruction countThis is a highly reliable metric that was used to determine the overall result at the top of this comment.
Max RSS (memory usage)ResultsThis is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.
CyclesResultsThis is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.
Binary sizeThis benchmark run did not return any relevant results for this metric. Bootstrap: 624.544s -> 623.266s (-0.20%) |
I'm going to need to figure out what happened to ripgrip. Other than that, HTML size seems to be mostly improved (I ran personal tests on the Perf results for doc_bytes: https://perf.rust-lang.org/compare.html?start=48e24629e946339943b194163a81374cf533ce5a&end=a68b52379d0536887ff555de1884b415cac2d0b1&stat=size%3Adoc_bytes Doc bytes for nalgebra and typenum: $ du -s typenum/target/doc nalgebra/target/doc
105336 typenum/target/doc
86408 nalgebra/target/doc
$ du -hs typenum/target/doc nalgebra/target/doc
51M typenum/target/doc
42M nalgebra/target/doc |
…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
☀️ Try build successful - checks-actions |
This comment has been minimized.
This comment has been minimized.
Finished benchmarking commit (9811b1e): comparison URL. Overall result: ❌✅ regressions and improvements - ACTION NEEDEDBenchmarking this pull request likely means that it is perf-sensitive, so we're automatically marking it as not fit for rolling up. While you can manually mark this PR as fit for rollup, we strongly recommend not doing so since this PR may lead to changes in compiler perf. Next Steps: If you can justify the regressions found in this try perf run, please indicate this with @bors rollup=never Instruction countThis is a highly reliable metric that was used to determine the overall result at the top of this comment.
Max RSS (memory usage)ResultsThis is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.
CyclesResultsThis is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.
Binary sizeThis benchmark run did not return any relevant results for this metric. Bootstrap: missing data |
Why there's a perf regressionThis pull request 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
|
Do you have before/after numbers for the size of the generated docs for |
@GuillaumeGomez [michael@deep-thought rust-build]$ du -hs after/doc before/doc
669M after/doc
778M before/doc
[michael@deep-thought rust-build]$ du -hs after/compiler-doc before/compiler-doc
710M after/compiler-doc
722M before/compiler-doc |
That's still quite a lot, nice work! @bors r+ rollup=never |
☀️ Test successful - checks-actions |
Finished benchmarking commit (6f349cd): comparison URL. Overall result: ❌✅ regressions and improvements - ACTION NEEDEDNext Steps: If you can justify the regressions found in this perf run, please indicate this with @rustbot label: +perf-regression Instruction countThis is a highly reliable metric that was used to determine the overall result at the top of this comment.
Max RSS (memory usage)ResultsThis is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.
CyclesResultsThis is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.
Binary sizeThis benchmark run did not return any relevant results for this metric. Bootstrap: 635.719s -> 635.428s (-0.05%) |
The perf regression was explained above; it's very small, rustdoc-only, and is more than balanced by the large reductions in generated doc size. @rustbot label: +perf-regression-triaged |
74: Automated pull from upstream `master` r=tshepang a=github-actions[bot] This PR pulls the following changes from the upstream repository: * rust-lang/rust#117363 * rust-lang/rust#116405 * rust-lang/rust#117415 * rust-lang/rust#117414 * rust-lang/rust#117411 * rust-lang/rust#117403 * rust-lang/rust#117398 * rust-lang/rust#117396 * rust-lang/rust#117389 * rust-lang/rust#116862 * rust-lang/rust#117405 * rust-lang/rust#117395 * rust-lang/rust#117390 * rust-lang/rust#117383 * rust-lang/rust#117376 * rust-lang/rust#117370 * rust-lang/rust#117357 * rust-lang/rust#117356 * rust-lang/rust#117317 * rust-lang/rust#117132 * rust-lang/rust#117068 * rust-lang/rust#112463 * rust-lang/rust#117267 * rust-lang/rust#116939 * rust-lang/rust#117387 * rust-lang/rust#117385 * rust-lang/rust#117382 * rust-lang/rust#117371 * rust-lang/rust#117365 * rust-lang/rust#117350 * rust-lang/rust#117205 * rust-lang/rust#117177 * rust-lang/rust#117147 * rust-lang/rust#116485 * rust-lang/rust#117328 * rust-lang/rust#117332 * rust-lang/rust#117089 * rust-lang/rust#116733 * rust-lang/rust#116889 * rust-lang/rust#116270 * rust-lang/rust#117354 * rust-lang/rust#117337 * rust-lang/rust#117312 * rust-lang/rust#117082 * rust-lang/rust#117043 * rust-lang/rust#115968 * rust-lang/rust#117336 * rust-lang/rust#117325 * rust-lang/rust#117322 * rust-lang/rust#117259 * rust-lang/rust#117170 * rust-lang/rust#117335 * rust-lang/rust#117319 * rust-lang/rust#117316 * rust-lang/rust#117311 * rust-lang/rust#117162 * rust-lang/rust#115773 * rust-lang/rust#116447 * rust-lang/rust#117149 * rust-lang/rust#116240 * rust-lang/rust#117123 * rust-lang/rust#81746 * rust-lang/rust#117038 * rust-lang/rust#116609 * rust-lang/rust#117309 * rust-lang/rust#117277 * rust-lang/rust#117268 * rust-lang/rust#117256 * rust-lang/rust#117025 * rust-lang/rust#116945 * rust-lang/rust#116816 * rust-lang/rust#116739 * rust-lang/rust#116534 * rust-lang/rust#117253 * rust-lang/rust#117302 * rust-lang/rust#117197 * rust-lang/rust#116471 * rust-lang/rust#117294 * rust-lang/rust#117287 * rust-lang/rust#117281 * rust-lang/rust#117270 * rust-lang/rust#117247 * rust-lang/rust#117246 * rust-lang/rust#117212 * rust-lang/rust#116834 * rust-lang/rust#103208 * rust-lang/rust#117166 * rust-lang/rust#116751 * rust-lang/rust#116858 * rust-lang/rust#117272 * rust-lang/rust#117266 * rust-lang/rust#117262 * rust-lang/rust#117241 * rust-lang/rust#117240 * rust-lang/rust#116868 * rust-lang/rust#114998 * rust-lang/rust#116205 * rust-lang/rust#117260 * rust-lang/rust#116035 * rust-lang/rust#113183 * rust-lang/rust#117249 * rust-lang/rust#117243 * rust-lang/rust#117188 * rust-lang/rust#117114 * rust-lang/rust#117106 * rust-lang/rust#117032 * rust-lang/rust#116968 * rust-lang/rust#116581 * rust-lang/rust#117228 * rust-lang/rust#117221 * rust-lang/rust#117214 * rust-lang/rust#117207 * rust-lang/rust#117202 * rust-lang/rust#117194 * rust-lang/rust#117143 * rust-lang/rust#117095 * rust-lang/rust#116905 * rust-lang/rust#117171 * rust-lang/rust#113262 * rust-lang/rust#112875 * rust-lang/rust#116983 * rust-lang/rust#117148 * rust-lang/rust#117115 * rust-lang/rust#116818 * rust-lang/rust#115872 * rust-lang/rust#117193 * rust-lang/rust#117175 * rust-lang/rust#117009 * rust-lang/rust#117008 * rust-lang/rust#116931 * rust-lang/rust#116553 * rust-lang/rust#116401 * rust-lang/rust#117180 * rust-lang/rust#117173 * rust-lang/rust#117163 * rust-lang/rust#117159 * rust-lang/rust#117154 * rust-lang/rust#117152 * rust-lang/rust#117141 * rust-lang/rust#117111 * rust-lang/rust#117172 * rust-lang/rust#117168 * rust-lang/rust#117160 * rust-lang/rust#117158 * rust-lang/rust#117150 * rust-lang/rust#117136 * rust-lang/rust#117133 * rust-lang/rust#116801 * rust-lang/rust#117165 * rust-lang/rust#117113 * rust-lang/rust#117102 * rust-lang/rust#117076 * rust-lang/rust#116236 * rust-lang/rust#116993 * rust-lang/rust#117139 * rust-lang/rust#116482 * rust-lang/rust#115796 * rust-lang/rust#117135 * rust-lang/rust#117127 * rust-lang/rust#117010 * rust-lang/rust#116943 * rust-lang/rust#116841 * rust-lang/rust#116792 * rust-lang/rust#116714 * rust-lang/rust#116396 * rust-lang/rust#116094 * rust-lang/rust#117126 * rust-lang/rust#117105 * rust-lang/rust#117093 * rust-lang/rust#117092 * rust-lang/rust#117091 * rust-lang/rust#117081 * rust-lang/rust#116773 * rust-lang/rust#117124 * rust-lang/rust#116461 * rust-lang/rust#116435 * rust-lang/rust#116319 * rust-lang/rust#116238 * rust-lang/rust#116998 * rust-lang/rust#116300 * rust-lang/rust#117103 * rust-lang/rust#117086 * rust-lang/rust#117074 * rust-lang/rust#117070 * rust-lang/rust#117046 * rust-lang/rust#116859 * rust-lang/rust#107159 * rust-lang/rust#116033 * rust-lang/rust#107009 * rust-lang/rust#117087 * rust-lang/rust#117073 * rust-lang/rust#117064 * rust-lang/rust#117040 * rust-lang/rust#116978 * rust-lang/rust#116960 * rust-lang/rust#116837 * rust-lang/rust#116835 * rust-lang/rust#116849 * rust-lang/rust#117071 * rust-lang/rust#117069 * rust-lang/rust#117051 * rust-lang/rust#117049 * rust-lang/rust#117044 * rust-lang/rust#117042 * rust-lang/rust#105666 * rust-lang/rust#116606 * rust-lang/rust#117066 * rust-lang/rust#115324 * rust-lang/rust#117062 * rust-lang/rust#117000 * rust-lang/rust#117007 * rust-lang/rust#117018 * rust-lang/rust#116256 * rust-lang/rust#117041 * rust-lang/rust#117037 * rust-lang/rust#117034 * rust-lang/rust#116989 * rust-lang/rust#116985 * rust-lang/rust#116950 * rust-lang/rust#116956 * rust-lang/rust#116932 * rust-lang/rust#117031 * rust-lang/rust#117030 * rust-lang/rust#117028 * rust-lang/rust#117026 * rust-lang/rust#116992 * rust-lang/rust#116981 * rust-lang/rust#116955 * rust-lang/rust#116928 * rust-lang/rust#116312 * rust-lang/rust#116368 * rust-lang/rust#116922 * rust-lang/rust#117021 * rust-lang/rust#117020 * rust-lang/rust#117019 * rust-lang/rust#116975 * rust-lang/rust#106601 * rust-lang/rust#116734 * rust-lang/rust#117013 * rust-lang/rust#116995 * rust-lang/rust#116990 * rust-lang/rust#116974 * rust-lang/rust#116964 * rust-lang/rust#116961 * rust-lang/rust#116917 * rust-lang/rust#116911 * rust-lang/rust#114521 * rust-lang/rust#117011 * rust-lang/rust#116958 * rust-lang/rust#116951 * rust-lang/rust#116966 * rust-lang/rust#116965 * rust-lang/rust#116962 * rust-lang/rust#116946 * rust-lang/rust#116899 * rust-lang/rust#116785 * rust-lang/rust#116838 * rust-lang/rust#116875 * rust-lang/rust#116874 * rust-lang/rust#115214 * rust-lang/rust#116810 * rust-lang/rust#116940 * rust-lang/rust#116921 * rust-lang/rust#116906 * rust-lang/rust#116896 * rust-lang/rust#116650 * rust-lang/rust#116132 * rust-lang/rust#116037 * rust-lang/rust#116923 * rust-lang/rust#116912 * rust-lang/rust#116908 * rust-lang/rust#116883 * rust-lang/rust#116829 * rust-lang/rust#116795 * rust-lang/rust#116761 * rust-lang/rust#116663 * rust-lang/rust#114534 * rust-lang/rust#116402 * rust-lang/rust#116493 * rust-lang/rust#116046 * rust-lang/rust#116887 * rust-lang/rust#116885 * rust-lang/rust#116879 * rust-lang/rust#116870 * rust-lang/rust#116865 * rust-lang/rust#116856 * rust-lang/rust#116812 * rust-lang/rust#116815 * rust-lang/rust#116814 * rust-lang/rust#116713 * rust-lang/rust#116830 Co-authored-by: Matthias Krüger <[email protected]> Co-authored-by: antoyo <[email protected]> Co-authored-by: Antoni Boucher <[email protected]> Co-authored-by: bors <[email protected]> Co-authored-by: Esteban Küber <[email protected]> Co-authored-by: Kjetil Kjeka <[email protected]> Co-authored-by: clubby789 <[email protected]> Co-authored-by: okaneco <[email protected]> Co-authored-by: David Tolnay <[email protected]> Co-authored-by: Nadrieril <[email protected]> Co-authored-by: Celina G. Val <[email protected]> Co-authored-by: Ralf Jung <[email protected]> Co-authored-by: Zalathar <[email protected]> Co-authored-by: Havard Eidnes <[email protected]> Co-authored-by: Jacob Pratt <[email protected]> Co-authored-by: Kjetil Kjeka <[email protected]>
74: Automated pull from upstream `master` r=tshepang a=github-actions[bot] This PR pulls the following changes from the upstream repository: * rust-lang/rust#117363 * rust-lang/rust#116405 * rust-lang/rust#117415 * rust-lang/rust#117414 * rust-lang/rust#117411 * rust-lang/rust#117403 * rust-lang/rust#117398 * rust-lang/rust#117396 * rust-lang/rust#117389 * rust-lang/rust#116862 * rust-lang/rust#117405 * rust-lang/rust#117395 * rust-lang/rust#117390 * rust-lang/rust#117383 * rust-lang/rust#117376 * rust-lang/rust#117370 * rust-lang/rust#117357 * rust-lang/rust#117356 * rust-lang/rust#117317 * rust-lang/rust#117132 * rust-lang/rust#117068 * rust-lang/rust#112463 * rust-lang/rust#117267 * rust-lang/rust#116939 * rust-lang/rust#117387 * rust-lang/rust#117385 * rust-lang/rust#117382 * rust-lang/rust#117371 * rust-lang/rust#117365 * rust-lang/rust#117350 * rust-lang/rust#117205 * rust-lang/rust#117177 * rust-lang/rust#117147 * rust-lang/rust#116485 * rust-lang/rust#117328 * rust-lang/rust#117332 * rust-lang/rust#117089 * rust-lang/rust#116733 * rust-lang/rust#116889 * rust-lang/rust#116270 * rust-lang/rust#117354 * rust-lang/rust#117337 * rust-lang/rust#117312 * rust-lang/rust#117082 * rust-lang/rust#117043 * rust-lang/rust#115968 * rust-lang/rust#117336 * rust-lang/rust#117325 * rust-lang/rust#117322 * rust-lang/rust#117259 * rust-lang/rust#117170 * rust-lang/rust#117335 * rust-lang/rust#117319 * rust-lang/rust#117316 * rust-lang/rust#117311 * rust-lang/rust#117162 * rust-lang/rust#115773 * rust-lang/rust#116447 * rust-lang/rust#117149 * rust-lang/rust#116240 * rust-lang/rust#117123 * rust-lang/rust#81746 * rust-lang/rust#117038 * rust-lang/rust#116609 * rust-lang/rust#117309 * rust-lang/rust#117277 * rust-lang/rust#117268 * rust-lang/rust#117256 * rust-lang/rust#117025 * rust-lang/rust#116945 * rust-lang/rust#116816 * rust-lang/rust#116739 * rust-lang/rust#116534 * rust-lang/rust#117253 * rust-lang/rust#117302 * rust-lang/rust#117197 * rust-lang/rust#116471 * rust-lang/rust#117294 * rust-lang/rust#117287 * rust-lang/rust#117281 * rust-lang/rust#117270 * rust-lang/rust#117247 * rust-lang/rust#117246 * rust-lang/rust#117212 * rust-lang/rust#116834 * rust-lang/rust#103208 * rust-lang/rust#117166 * rust-lang/rust#116751 * rust-lang/rust#116858 * rust-lang/rust#117272 * rust-lang/rust#117266 * rust-lang/rust#117262 * rust-lang/rust#117241 * rust-lang/rust#117240 * rust-lang/rust#116868 * rust-lang/rust#114998 * rust-lang/rust#116205 * rust-lang/rust#117260 * rust-lang/rust#116035 * rust-lang/rust#113183 * rust-lang/rust#117249 * rust-lang/rust#117243 * rust-lang/rust#117188 * rust-lang/rust#117114 * rust-lang/rust#117106 * rust-lang/rust#117032 * rust-lang/rust#116968 * rust-lang/rust#116581 * rust-lang/rust#117228 * rust-lang/rust#117221 * rust-lang/rust#117214 * rust-lang/rust#117207 * rust-lang/rust#117202 * rust-lang/rust#117194 * rust-lang/rust#117143 * rust-lang/rust#117095 * rust-lang/rust#116905 * rust-lang/rust#117171 * rust-lang/rust#113262 * rust-lang/rust#112875 * rust-lang/rust#116983 * rust-lang/rust#117148 * rust-lang/rust#117115 * rust-lang/rust#116818 * rust-lang/rust#115872 * rust-lang/rust#117193 * rust-lang/rust#117175 * rust-lang/rust#117009 * rust-lang/rust#117008 * rust-lang/rust#116931 * rust-lang/rust#116553 * rust-lang/rust#116401 * rust-lang/rust#117180 * rust-lang/rust#117173 * rust-lang/rust#117163 * rust-lang/rust#117159 * rust-lang/rust#117154 * rust-lang/rust#117152 * rust-lang/rust#117141 * rust-lang/rust#117111 * rust-lang/rust#117172 * rust-lang/rust#117168 * rust-lang/rust#117160 * rust-lang/rust#117158 * rust-lang/rust#117150 * rust-lang/rust#117136 * rust-lang/rust#117133 * rust-lang/rust#116801 * rust-lang/rust#117165 * rust-lang/rust#117113 * rust-lang/rust#117102 * rust-lang/rust#117076 * rust-lang/rust#116236 * rust-lang/rust#116993 * rust-lang/rust#117139 * rust-lang/rust#116482 * rust-lang/rust#115796 * rust-lang/rust#117135 * rust-lang/rust#117127 * rust-lang/rust#117010 * rust-lang/rust#116943 * rust-lang/rust#116841 * rust-lang/rust#116792 * rust-lang/rust#116714 * rust-lang/rust#116396 * rust-lang/rust#116094 * rust-lang/rust#117126 * rust-lang/rust#117105 * rust-lang/rust#117093 * rust-lang/rust#117092 * rust-lang/rust#117091 * rust-lang/rust#117081 * rust-lang/rust#116773 * rust-lang/rust#117124 * rust-lang/rust#116461 * rust-lang/rust#116435 * rust-lang/rust#116319 * rust-lang/rust#116238 * rust-lang/rust#116998 * rust-lang/rust#116300 * rust-lang/rust#117103 * rust-lang/rust#117086 * rust-lang/rust#117074 * rust-lang/rust#117070 * rust-lang/rust#117046 * rust-lang/rust#116859 * rust-lang/rust#107159 * rust-lang/rust#116033 * rust-lang/rust#107009 * rust-lang/rust#117087 * rust-lang/rust#117073 * rust-lang/rust#117064 * rust-lang/rust#117040 * rust-lang/rust#116978 * rust-lang/rust#116960 * rust-lang/rust#116837 * rust-lang/rust#116835 * rust-lang/rust#116849 * rust-lang/rust#117071 * rust-lang/rust#117069 * rust-lang/rust#117051 * rust-lang/rust#117049 * rust-lang/rust#117044 * rust-lang/rust#117042 * rust-lang/rust#105666 * rust-lang/rust#116606 * rust-lang/rust#117066 * rust-lang/rust#115324 * rust-lang/rust#117062 * rust-lang/rust#117000 * rust-lang/rust#117007 * rust-lang/rust#117018 * rust-lang/rust#116256 * rust-lang/rust#117041 * rust-lang/rust#117037 * rust-lang/rust#117034 * rust-lang/rust#116989 * rust-lang/rust#116985 * rust-lang/rust#116950 * rust-lang/rust#116956 * rust-lang/rust#116932 * rust-lang/rust#117031 * rust-lang/rust#117030 * rust-lang/rust#117028 * rust-lang/rust#117026 * rust-lang/rust#116992 * rust-lang/rust#116981 * rust-lang/rust#116955 * rust-lang/rust#116928 * rust-lang/rust#116312 * rust-lang/rust#116368 * rust-lang/rust#116922 * rust-lang/rust#117021 * rust-lang/rust#117020 * rust-lang/rust#117019 * rust-lang/rust#116975 * rust-lang/rust#106601 * rust-lang/rust#116734 * rust-lang/rust#117013 * rust-lang/rust#116995 * rust-lang/rust#116990 * rust-lang/rust#116974 * rust-lang/rust#116964 * rust-lang/rust#116961 * rust-lang/rust#116917 * rust-lang/rust#116911 * rust-lang/rust#114521 * rust-lang/rust#117011 * rust-lang/rust#116958 * rust-lang/rust#116951 * rust-lang/rust#116966 * rust-lang/rust#116965 * rust-lang/rust#116962 * rust-lang/rust#116946 * rust-lang/rust#116899 * rust-lang/rust#116785 * rust-lang/rust#116838 * rust-lang/rust#116875 * rust-lang/rust#116874 * rust-lang/rust#115214 * rust-lang/rust#116810 * rust-lang/rust#116940 * rust-lang/rust#116921 * rust-lang/rust#116906 * rust-lang/rust#116896 * rust-lang/rust#116650 * rust-lang/rust#116132 * rust-lang/rust#116037 * rust-lang/rust#116923 * rust-lang/rust#116912 * rust-lang/rust#116908 * rust-lang/rust#116883 * rust-lang/rust#116829 * rust-lang/rust#116795 * rust-lang/rust#116761 * rust-lang/rust#116663 * rust-lang/rust#114534 * rust-lang/rust#116402 * rust-lang/rust#116493 * rust-lang/rust#116046 * rust-lang/rust#116887 * rust-lang/rust#116885 * rust-lang/rust#116879 * rust-lang/rust#116870 * rust-lang/rust#116865 * rust-lang/rust#116856 * rust-lang/rust#116812 * rust-lang/rust#116815 * rust-lang/rust#116814 * rust-lang/rust#116713 * rust-lang/rust#116830 Co-authored-by: antoyo <[email protected]> Co-authored-by: Antoni Boucher <[email protected]> Co-authored-by: bors <[email protected]> Co-authored-by: Esteban Küber <[email protected]> Co-authored-by: Kjetil Kjeka <[email protected]> Co-authored-by: clubby789 <[email protected]> Co-authored-by: okaneco <[email protected]> Co-authored-by: David Tolnay <[email protected]> Co-authored-by: Nadrieril <[email protected]> Co-authored-by: Celina G. Val <[email protected]> Co-authored-by: Ralf Jung <[email protected]> Co-authored-by: Zalathar <[email protected]> Co-authored-by: Havard Eidnes <[email protected]> Co-authored-by: Jacob Pratt <[email protected]> Co-authored-by: Kjetil Kjeka <[email protected]> Co-authored-by: Matthias Krüger <[email protected]>
rustdoc apparently cannot generate docs for methods implemented on a type alias target unless said type alias is exported from the crate. I think it's b/c under the hood rustdoc is using some clever javascript tricks to inline documentation. They do this to avoid HTML bloat for crates with lots of type alises [0]. The upshot of this is now trait impls like `AsFd` are visible in web docs. This is really important, as otherwise it's quite difficult for users to discover these APIs. The downside of this approach is we publically expose implementation structs in docs. It's not a huge deal, as with skeleton it should be fairly obvious what types they should actually interact with. I kinda doubt anyone reads the docs front to back. [0]: rust-lang/rust#116471
rustdoc apparently cannot generate docs for methods implemented on a type alias target unless said type alias is exported from the crate. I think it's b/c under the hood rustdoc is using some clever javascript tricks to inline documentation. They do this to avoid HTML bloat for crates with lots of type alises [0]. The upshot of this is now trait impls like `AsFd` are visible in web docs. This is really important, as otherwise it's quite difficult for users to discover these APIs. The downside of this approach is we publically expose implementation structs in docs. It's not a huge deal, as with skeleton it should be fairly obvious what types they should actually interact with. I kinda doubt anyone reads the docs front to back. [0]: rust-lang/rust#116471
rustdoc apparently cannot generate docs for methods implemented on a type alias target unless said type alias is exported from the crate. I think it's b/c under the hood rustdoc is using some clever javascript tricks to inline documentation. They do this to avoid HTML bloat for crates with lots of type alises [0]. The upshot of this is now trait impls like `AsFd` are visible in web docs. This is really important, as otherwise it's quite difficult for users to discover these APIs. The downside of this approach is we publically expose implementation structs in docs. It's not a huge deal, as with skeleton it should be fairly obvious what types they should actually interact with. I kinda doubt anyone reads the docs front to back. [0]: rust-lang/rust#116471
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).Review note: This is mostly just reverting #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 targettype, 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 inprint_item.rs
, andmain.js
takes care of patching the additional docs into the DOM.
The format of
trait.impl
andtype.impl
JS files are superficiallysimilar. 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:
The type.impl/A/struct.Foo.js JS file has a structure kinda like this:
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:
in the current crate. If a dependent crate makes a type alias, it'll
take care of generating its own docs.
JavaScript. The Rust backend does the checking, and includes its
results in the file.
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.