-
Notifications
You must be signed in to change notification settings - Fork 12.9k
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: Discriminate required and provided associated constants and types #95316
Rustdoc: Discriminate required and provided associated constants and types #95316
Conversation
Some changes occurred in HTML/CSS/JS. cc @GuillaumeGomez,@Folyd,@jsha Some changes occurred in cc @camelid |
Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @CraftSpider (or someone else) soon. Please see the contribution instructions for more information. |
For the URL changes, definitely. For the UI changes, not really unless some someone has concerns. Otherwise I think it's a nice improvement overall. I like having new sections. Not a big fan of the new spaces you added in the type definition source code block.
It's logical for methods to not write the content since it's way too verbose. But for constants I think it'd make more sense to provide the value. |
Also cc @camelid (for code changes) and @Manishearth (for UI changes). |
This comment has been minimized.
This comment has been minimized.
I'm okay with this from the UI POV. Not a fan of URL fragments breaking but overall as long as it's just the fragments i'm still okay with this |
I have to add that the URL change prepending (OTOH, the addition of those new sections force URL fragment changes no matter what obviously) I went for consistency, though I can go for backward compatibility and performance(?) depending on the concensus. |
This comment was marked as outdated.
This comment was marked as outdated.
Yeah I'm fine with the consistent solution too. |
I think overall you went a bit too far on this feature: having new sections to differentiate provided and required associated items is a good idea (and even makes the
You might have discovered a new rustdoc bug. 😄 Before making any fixes in the std docs, better wait we all agree on the changes here to prevent you to do it more than once (which will already be huge...). |
This comment was marked as resolved.
This comment was marked as resolved.
1081a0e
to
be3867a
Compare
This comment was marked as outdated.
This comment was marked as outdated.
19e1cf1
to
1dabd1b
Compare
cc @notriddle @camelid in case you want to make another review round |
1dabd1b
to
8de453a
Compare
Let's go! @bors: r=notriddle,GuillaumeGomez |
📌 Commit 8de453a has been approved by |
Rollup of 7 pull requests Successful merges: - rust-lang#95316 (Rustdoc: Discriminate required and provided associated constants and types) - rust-lang#95405 (Move name resolution logic to a dedicated file) - rust-lang#95914 (Implement tuples using recursion) - rust-lang#95918 (Delay a bug when we see SelfCtor in ref pattern) - rust-lang#95970 (Fix suggestions in case of `T:` bounds) - rust-lang#95973 (prevent opaque types from appearing in impl headers) - rust-lang#95986 (Autolabel library PRs with T-libs) Failed merges: r? `@ghost` `@rustbot` modify labels: rollup
Hey @fmease and @GuillaumeGomez , it seems like rollup PR #95990 regressed diesel-1.4.8 doc by 4.1% and many-assoc-items doc by 71.71% Skimming over the contents of rollup PR #95990, it seems plausible that this PR is the root cause of those regressions. (Useful hint: the links for each of the numeric percentages go to specific pages that include the performance collector invocation that downloads the compiler artifacts, runs them on the benchmark atop cachegrind, and diffs the performance data; see e.g. 71.71% link) Can one of you look into whether this PR is the cause of those regressions? |
I'll try to as soon as possible. |
@pnkfelix Apologies for the missing updates. I am going to take a look at the regression in a few hours from now. Since this is my first time profiling |
@fmease @GuillaumeGomez has there been any progress on figuring out a fix for the performance improvement? |
I think @fmease found something but otherwise no idea. |
@rylev I am terribly sorry to report that no, I do not have any clue how to improve the performance since I have next to no expertise with const evaluation, the origin of the regression. rustdoc simply calls I am not sure if anything can be done on the rustdoc side, maybe the representation of constants in rustdoc ( The only thing I personally can offer right now is a temporary workaround / partial rollback of this PR where we don't do any const eval (but still keep basically 90% of the changes introduced in this PR). @GuillaumeGomez, I know, you once expressed your disapproval in regards to that (printing a placeholder like |
Performance regression could be reduced with the help of someone who knows about the const evaluation but the added information is definitely important in my opinion. Do you know who we could ask for help @rylev by any chance? |
Perhaps @oli-obk might be of some assistance? |
There's nothing to be done about this. If you want an evaluated constant you need to evaluate it. |
Currently, rustdoc merely separates required and provided associated functions (i.e. methods). This PR extends this to constants (fixes #94652) and types. This makes the documentation of all three kinds of associated items more alike and consistent.
As an aside, associated types may actually be provided / have a default when users enable the unstable feature
associated_type_defaults
.clean::types::ItemKind
modificationItemKind::TypedefItem(.., true)
→ItemKind::AssocTypeItem(..)
ItemKind::TypedefItem(.., false)
→ItemKind::TypedefItem(..)
Further, I added
ItemKind::TyAssoc{Const,Type}Item
, the “required” variant ofItemKind::Assoc{Const,Type}Item
, analogous toItemKind::TyMethodItem
withItemKind::MethodItem
. These new variants don't contain new information really, they are just the result of me getting rid of theOption<_>
field inAssocConstItem
andAssocTypeItem
.Goal: Make associated items more consistent.
Originally I thought modifying
ItemKind
was necessary to achieve the new functionality of this PR but in retrospect, it does not. If you don't like the changes toItemKind
, I think I can get rid of them.This change is the root cause of those tiny changes in a lot of different files.
Concerns and Open Questions
associated-const
(sic!) ->{provided,required}-associated-consts
associated-types
->{provided,required}-associated-types
conversions.rs
(conversion to JSON),cache.rs
/fold_item
,stripper.rs
/fold_item
,check_doc_test_visibility.rs
/should_have_doc_example
,collect_intra_doc_links.rs
/from_assoc_item
AssocTypeItem
s toTypedef
etc. (FIXME)