Skip to content
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: change trait bound formatting #102842

Merged
merged 1 commit into from
Feb 5, 2023
Merged

Conversation

rol1510
Copy link
Contributor

@rol1510 rol1510 commented Oct 9, 2022

Fixes #85566

Before
image

Now
image

@rustbot rustbot added the T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. label Oct 9, 2022
@rust-highfive
Copy link
Collaborator

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @GuillaumeGomez (or someone else) soon.

Please see the contribution instructions for more information.

@rust-highfive rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Oct 9, 2022
@Urgau
Copy link
Member

Urgau commented Oct 9, 2022

This new formatting style is (in my opinion) very confusing and I believe does not follow the Rust style guidelines (which rustfmt applies).

Is there another reason to do this change (other than taking 2 lines less) ?

@GuillaumeGomez
Copy link
Member

It makes the reading more difficult, indeed. I think it's not a good idea but let's hear from the rest of the team first. cc @rust-lang/rustdoc

@Manishearth
Copy link
Member

Worth noting that this only makes a difference on defaulted methods methods. "This method has a default impl" is not that important from a rustdoc pov and giving it an entire line doesn't seem worth it to me.

That said, this is mostly a problem for Iterator, perhaps we can only apply this to traits with > N defaulted methods?

I'm fine with the proposed change as it is, though.

@jsha
Copy link
Contributor

jsha commented Oct 9, 2022

@Manishearth hits the nail precisely on the head with regards to why I proposed the formatting change in #85566. IMO { ... } does not deserve its own line in what is supposed to be a summary view. It's not a very efficient or effective way to say "there is a provided implementation for this function."

I think "this is not rustfmt style" is an important argument but not a decisive one. The current behavior puts the opening and closing braces on the same line, which rustfmt would never do unless the function body was empty.

Really, there's a conflict between "make the item-decl look like source code" and "hide the implementation."

Perhaps a better way to resolve this conflict is to avoid the pseudo-syntax { ... }. Instead we would break the trait item-decl into two sections, just like we do in the detailed documentation:

pub trait Iterator {
    type Item;
    
    // Required method
    fn next(&mut self) -> Option<Self::Item>;

    // Provided methods
    fn next_chunk<const N: usize>(
        &mut self
    ) -> Result<[Self::Item; N], IntoIter<Self::Item, N>>
    fn size_hint(&self) -> (usize, Option<usize>)
    fn count(self) -> usize
    fn last(self) -> Option<Self::Item>
    fn advance_by(&mut self, n: usize) -> Result<(), usize>
    ...
}

This has the advantage of taking something that is implicit and hard to notice, and making it explicit and easy to notice. That is, readers are expected to notice that a trailing ; means "required method" and a trailing { ... } means "provided method". And also that provided/required methods are grouped into blocks in the item-decl.

By the way, @rol1510 thank you for the implementation! Sorry that we are still hashing out the details of how we want this to look. Sometimes it takes an implementation to spark more detailed discussion. :-D

@Manishearth
Copy link
Member

Manishearth commented Oct 9, 2022

Another thing that could be done is to make {...} look different (perhaps smaller with a slightly different background and a border), and give it a tooltip on hover. That way it's not mimicking inline syntax, rather it's a symbol marking some special behavior. But still ideally copy-pastes as {..} so that people implementing the trait by copy-paste will notice.

(But again, I'm fine with the current proposal)

@notriddle
Copy link
Contributor

I like @jsha’s proposal with the two different sections, as long as where clauses get formatted the same way rustfmt formats them.

@GuillaumeGomez
Copy link
Member

I also really like @jsha's suggestion with the two sections.

@Manishearth: I'd prefer to avoid adding tooltips if possible but thanks to @jsha's explanation, I now understand the idea behind it.

@Urgau
Copy link
Member

Urgau commented Oct 10, 2022

@jsha suggestion to have two distinct sections seems like a great idea. I'm a bit more nuanced with a proposed removal of { ... }, but as long as a normal user can quickly see that the method is provided this seems fine.

@rol1510
Copy link
Contributor Author

rol1510 commented Oct 23, 2022

Did we come to a conclusion on this? Should I implement @jsha's suggestion?

@GuillaumeGomez
Copy link
Member

I think the proposal with two sections got the most approval. Let's wait for a few days to give time to anyone who doesn't agree to express their opinion then you can open a PR.

@Manishearth
Copy link
Member

@Manishearth: I'd prefer to avoid adding tooltips if possible but thanks to @jsha's explanation, I now understand the idea behind it.

I assume this would be a native tooltip not a JS tooltip, fwiw.

@notriddle
Copy link
Contributor

@rol1510 Nobody seems to object to the proposal with the two sections.

@rol1510
Copy link
Contributor Author

rol1510 commented Nov 24, 2022

Do we keep the old style for the where clauses, or use the new one?

old:
image

new:
image

@GuillaumeGomez
Copy link
Member

GuillaumeGomez commented Nov 24, 2022

I find the older one easier to read.

@Manishearth
Copy link
Member

I actually kinda prefer the new one 🙃

@notriddle
Copy link
Contributor

I don’t actually have a preference between them, but I noticed that the item-spacer is broken. Make it display: block, and it might look better.

@rol1510
Copy link
Contributor Author

rol1510 commented Nov 26, 2022

With the fixed spacer:

new:
image
image

old:
image
image

@rustbot
Copy link
Collaborator

rustbot commented Nov 26, 2022

Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez, @Folyd, @jsha

@rol1510
Copy link
Contributor Author

rol1510 commented Nov 26, 2022

This PR should now create the old style like in the picture above. It also adds a few tests and fixes the item-spacer

If you like the new style more, just let me know and I'll add it back in.

@rust-log-analyzer

This comment has been minimized.

@jsha
Copy link
Contributor

jsha commented Nov 26, 2022

Fwiw, I prefer the new style. :-) One note: the "provided methods" / "required methods" should start with //, not #, since that's the Rust comment style.

@GuillaumeGomez
Copy link
Member

Despite personal preference, my only argument in favor of the old style is that it follows the rustfmt style. If we don't care, then since the majority seems to prefer the new style, I have nothing to add. ^^'

@rol1510
Copy link
Contributor Author

rol1510 commented Nov 27, 2022

The PR now creates the new style.

image

@bors
Copy link
Contributor

bors commented Nov 29, 2022

☔ The latest upstream changes (presumably #105041) made this pull request unmergeable. Please resolve the merge conflicts.

@bors
Copy link
Contributor

bors commented Feb 4, 2023

☔ The latest upstream changes (presumably #107650) made this pull request unmergeable. Please resolve the merge conflicts.

rustdoc: fix item-spacer

rustdoc: use proper comment style

rustdoc: change formatting where clauses for traits

rustdoc: remove semicolon from provided methods

update provided methods formatting
@notriddle
Copy link
Contributor

@bors r+ rollup

@bors
Copy link
Contributor

bors commented Feb 4, 2023

📌 Commit 71a147d has been approved by notriddle

It is now in the queue for this repository.

@bors 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 Feb 4, 2023
@bors
Copy link
Contributor

bors commented Feb 5, 2023

⌛ Testing commit 71a147d with merge 5526605002b7186725a30f5ed1ddf0cfcfc24541...

@bors
Copy link
Contributor

bors commented Feb 5, 2023

💥 Test timed out

@bors bors added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels Feb 5, 2023
@notriddle
Copy link
Contributor

@bors retry

@bors 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 Feb 5, 2023
@bors
Copy link
Contributor

bors commented Feb 5, 2023

⌛ Testing commit 71a147d with merge 319b88c...

@bors
Copy link
Contributor

bors commented Feb 5, 2023

☀️ Test successful - checks-actions
Approved by: notriddle
Pushing 319b88c to master...

@bors bors added the merged-by-bors This PR was explicitly merged by bors. label Feb 5, 2023
@bors bors merged commit 319b88c into rust-lang:master Feb 5, 2023
@rustbot rustbot added this to the 1.69.0 milestone Feb 5, 2023
@rust-timer
Copy link
Collaborator

Finished benchmarking commit (319b88c): comparison URL.

Overall result: ❌✅ regressions and improvements - ACTION NEEDED

Next Steps: If you can justify the regressions found in this perf run, please indicate this with @rustbot label: +perf-regression-triaged along with sufficient written justification. If you cannot justify the regressions please open an issue or create a new PR that fixes the regressions, add a comment linking to the newly created issue or PR, and then add the perf-regression-triaged label to this PR.

@rustbot label: +perf-regression
cc @rust-lang/wg-compiler-performance

Instruction count

This is a highly reliable metric that was used to determine the overall result at the top of this comment.

mean range count
Regressions ❌
(primary)
- - 0
Regressions ❌
(secondary)
0.7% [0.7%, 0.7%] 2
Improvements ✅
(primary)
-0.3% [-0.4%, -0.2%] 2
Improvements ✅
(secondary)
-0.9% [-1.3%, -0.3%] 11
All ❌✅ (primary) -0.3% [-0.4%, -0.2%] 2

Max RSS (memory usage)

Results

This 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.

mean range count
Regressions ❌
(primary)
- - 0
Regressions ❌
(secondary)
3.7% [1.9%, 5.6%] 2
Improvements ✅
(primary)
- - 0
Improvements ✅
(secondary)
- - 0
All ❌✅ (primary) - - 0

Cycles

Results

This 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.

mean range count
Regressions ❌
(primary)
- - 0
Regressions ❌
(secondary)
3.7% [3.0%, 4.5%] 2
Improvements ✅
(primary)
- - 0
Improvements ✅
(secondary)
- - 0
All ❌✅ (primary) - - 0

@rustbot rustbot added the perf-regression Performance regression. label Feb 5, 2023
@rust-log-analyzer
Copy link
Collaborator

A job failed! Check out the build log: (web) (plain)

Click to see the possible cause of the failure (guessed by this bot)

@lqd
Copy link
Member

lqd commented Feb 6, 2023

This only modifies rustdoc rendering and these benchmarks are all check/debug/opt, so this is noise. The results are corrections from #107679 (comment)

@rustbot label: +perf-regression-triaged

@rustbot rustbot added the perf-regression-triaged The performance regression has been triaged. label Feb 6, 2023
wip-sync pushed a commit to NetBSD/pkgsrc-wip that referenced this pull request Apr 24, 2023
Pkgsrc changes:
 * Adjust patches and cargo checksums to new versions.
 * Sadly, the patch to reduce the cargo verbosity no longer applies,
   so I've asked upstream about the proper way to get the old result.
   (so the build log becomes Quite Bloated for now).

Upstream changes:

Version 1.69.0 (2023-04-20)
==========================

Language
--------

- [Deriving built-in traits on packed structs works with `Copy` fields.]
  (rust-lang/rust#104429)
- [Stabilize the `cmpxchg16b` target feature on x86 and x86_64.]
  (rust-lang/rust#106774)
- [Improve analysis of trait bounds for associated types.]
  (rust-lang/rust#103695)
- [Allow associated types to be used as union fields.]
  (rust-lang/rust#106938)
- [Allow `Self: Autotrait` bounds on dyn-safe trait methods.]
  (rust-lang/rust#107082)
- [Treat `str` as containing `[u8]` for auto trait purposes.]
  (rust-lang/rust#107941)

Compiler
--------

- [Upgrade `*-pc-windows-gnu` on CI to mingw-w64 v10 and GCC 12.2.]
  (rust-lang/rust#100178)
- [Rework min_choice algorithm of member constraints.]
  (rust-lang/rust#105300)
- [Support `true` and `false` as boolean flags in compiler arguments.]
  (rust-lang/rust#107043)
- [Default `repr(C)` enums to `c_int` size.]
  (rust-lang/rust#107592)

Libraries
---------

- [Implement the unstable `DispatchFromDyn` for cell types, allowing
  downstream experimentation with custom method receivers.]
  (rust-lang/rust#97373)
- [Document that `fmt::Arguments::as_str()` may return `Some(_)`
  in more cases after optimization, subject to change.]
  (rust-lang/rust#106823)
- [Implement `AsFd` and `AsRawFd` for `Rc`.]
  (rust-lang/rust#107317)

Stabilized APIs
---------------

- [`CStr::from_bytes_until_nul`]
  (https://doc.rust-lang.org/stable/core/ffi/struct.CStr.html#method.from_bytes_until_nul)
- [`core::ffi::FromBytesUntilNulError`]
  (https://doc.rust-lang.org/stable/core/ffi/struct.FromBytesUntilNulError.html)

These APIs are now stable in const contexts:

- [`SocketAddr::new`]
  (https://doc.rust-lang.org/stable/std/net/enum.SocketAddr.html#method.new)
- [`SocketAddr::ip`]
  (https://doc.rust-lang.org/stable/std/net/enum.SocketAddr.html#method.ip)
- [`SocketAddr::port`]
  (https://doc.rust-lang.org/stable/std/net/enum.SocketAddr.html#method.port)
- [`SocketAddr::is_ipv4`]
  (https://doc.rust-lang.org/stable/std/net/enum.SocketAddr.html#method.is_ipv4)
- [`SocketAddr::is_ipv6`]
  (https://doc.rust-lang.org/stable/std/net/enum.SocketAddr.html#method.is_ipv6)
- [`SocketAddrV4::new`]
  (https://doc.rust-lang.org/stable/std/net/struct.SocketAddrV4.html#method.new)
- [`SocketAddrV4::ip`]
  (https://doc.rust-lang.org/stable/std/net/struct.SocketAddrV4.html#method.ip)
- [`SocketAddrV4::port`]
  (https://doc.rust-lang.org/stable/std/net/struct.SocketAddrV4.html#method.port)
- [`SocketAddrV6::new`]
  (https://doc.rust-lang.org/stable/std/net/struct.SocketAddrV6.html#method.new)
- [`SocketAddrV6::ip`]
  (https://doc.rust-lang.org/stable/std/net/struct.SocketAddrV6.html#method.ip)
- [`SocketAddrV6::port`]
  (https://doc.rust-lang.org/stable/std/net/struct.SocketAddrV6.html#method.port)
- [`SocketAddrV6::flowinfo`]
  (https://doc.rust-lang.org/stable/std/net/struct.SocketAddrV6.html#method.flowinfo)
- [`SocketAddrV6::scope_id`]
  (https://doc.rust-lang.org/stable/std/net/struct.SocketAddrV6.html#method.scope_id)

Cargo
-----

- [Cargo now suggests `cargo fix` or `cargo clippy --fix` when compilation warnings are auto-fixable.]
  (rust-lang/cargo#11558)
- [Cargo now suggests `cargo add` if you try to install a library crate.]
  (rust-lang/cargo#11410)
- [Cargo now sets the `CARGO_BIN_NAME` environment variable also for binary examples.]
  (rust-lang/cargo#11705)

Rustdoc
-----

- [Vertically compact trait bound formatting.]
  (rust-lang/rust#102842)
- [Only include stable lints in `rustdoc::all` group.]
  (rust-lang/rust#106316)
- [Compute maximum Levenshtein distance based on the query.]
  (rust-lang/rust#107141)
- [Remove inconsistently-present sidebar tooltips.]
  (rust-lang/rust#107490)
- [Search by macro when query ends with `!`.]
  (rust-lang/rust#108143)

Compatibility Notes
-------------------

- [The `rust-analysis` component from `rustup` now only contains
  a warning placeholder.]
  (rust-lang/rust#101841) This was primarily
  intended for RLS, and the corresponding `-Zsave-analysis` flag
  has been removed from the compiler as well.
- [Unaligned references to packed fields are now a hard error.]
  (rust-lang/rust#102513) This has been
  a warning since 1.53, and denied by default with a future-compatibility
  warning since 1.62.
- [Update the minimum external LLVM to 14.]
  (rust-lang/rust#107573)
- [Cargo now emits errors on invalid characters in a registry token.]
  (rust-lang/cargo#11600)
- [When `default-features` is set to false of a workspace dependency,
  and an inherited dependency of a member has `default-features =
  true`, Cargo will enable default features of that dependency.]
  (rust-lang/cargo#11409)
- [Cargo denies `CARGO_HOME` in the `[env]` configuration table.
  Cargo itself doesn't pick up this value, but recursive calls to
  cargo would, which was not intended.]
  (rust-lang/cargo#11644)
- [Debuginfo for build dependencies is now off if not explicitly
  set. This is expected to improve the overall build time.]

  (rust-lang/cargo#11252)

Internal Changes
----------------

These changes do not affect any public interfaces of Rust, but they represent
significant improvements to the performance or internals of rustc and related
tools.

- [Move `format_args!()` into AST (and expand it during AST lowering)]
  (rust-lang/rust#106745)
netbsd-srcmastr pushed a commit to NetBSD/pkgsrc that referenced this pull request May 4, 2023
Pkgsrc changes:
 * Adjust patches and cargo checksums to new versions.

Upstream changes:

Version 1.69.0 (2023-04-20)
==========================

Language
--------

- [Deriving built-in traits on packed structs works with `Copy` fields.]
  (rust-lang/rust#104429)
- [Stabilize the `cmpxchg16b` target feature on x86 and x86_64.]
  (rust-lang/rust#106774)
- [Improve analysis of trait bounds for associated types.]
  (rust-lang/rust#103695)
- [Allow associated types to be used as union fields.]
  (rust-lang/rust#106938)
- [Allow `Self: Autotrait` bounds on dyn-safe trait methods.]
  (rust-lang/rust#107082)
- [Treat `str` as containing `[u8]` for auto trait purposes.]
  (rust-lang/rust#107941)

Compiler
--------

- [Upgrade `*-pc-windows-gnu` on CI to mingw-w64 v10 and GCC 12.2.]
  (rust-lang/rust#100178)
- [Rework min_choice algorithm of member constraints.]
  (rust-lang/rust#105300)
- [Support `true` and `false` as boolean flags in compiler arguments.]
  (rust-lang/rust#107043)
- [Default `repr(C)` enums to `c_int` size.]
  (rust-lang/rust#107592)

Libraries
---------

- [Implement the unstable `DispatchFromDyn` for cell types, allowing
  downstream experimentation with custom method receivers.]
  (rust-lang/rust#97373)
- [Document that `fmt::Arguments::as_str()` may return `Some(_)`
  in more cases after optimization, subject to change.]
  (rust-lang/rust#106823)
- [Implement `AsFd` and `AsRawFd` for `Rc`.]
  (rust-lang/rust#107317)

Stabilized APIs
---------------

- [`CStr::from_bytes_until_nul`]
  (https://doc.rust-lang.org/stable/core/ffi/struct.CStr.html#method.from_bytes_until_nul)
- [`core::ffi::FromBytesUntilNulError`]
  (https://doc.rust-lang.org/stable/core/ffi/struct.FromBytesUntilNulError.html)

These APIs are now stable in const contexts:

- [`SocketAddr::new`]
  (https://doc.rust-lang.org/stable/std/net/enum.SocketAddr.html#method.new)
- [`SocketAddr::ip`]
  (https://doc.rust-lang.org/stable/std/net/enum.SocketAddr.html#method.ip)
- [`SocketAddr::port`]
  (https://doc.rust-lang.org/stable/std/net/enum.SocketAddr.html#method.port)
- [`SocketAddr::is_ipv4`]
  (https://doc.rust-lang.org/stable/std/net/enum.SocketAddr.html#method.is_ipv4)
- [`SocketAddr::is_ipv6`]
  (https://doc.rust-lang.org/stable/std/net/enum.SocketAddr.html#method.is_ipv6)
- [`SocketAddrV4::new`]
  (https://doc.rust-lang.org/stable/std/net/struct.SocketAddrV4.html#method.new)
- [`SocketAddrV4::ip`]
  (https://doc.rust-lang.org/stable/std/net/struct.SocketAddrV4.html#method.ip)
- [`SocketAddrV4::port`]
  (https://doc.rust-lang.org/stable/std/net/struct.SocketAddrV4.html#method.port)
- [`SocketAddrV6::new`]
  (https://doc.rust-lang.org/stable/std/net/struct.SocketAddrV6.html#method.new)
- [`SocketAddrV6::ip`]
  (https://doc.rust-lang.org/stable/std/net/struct.SocketAddrV6.html#method.ip)
- [`SocketAddrV6::port`]
  (https://doc.rust-lang.org/stable/std/net/struct.SocketAddrV6.html#method.port)
- [`SocketAddrV6::flowinfo`]
  (https://doc.rust-lang.org/stable/std/net/struct.SocketAddrV6.html#method.flowinfo)
- [`SocketAddrV6::scope_id`]
  (https://doc.rust-lang.org/stable/std/net/struct.SocketAddrV6.html#method.scope_id)

Cargo
-----

- [Cargo now suggests `cargo fix` or `cargo clippy --fix` when compilation warnings are auto-fixable.]
  (rust-lang/cargo#11558)
- [Cargo now suggests `cargo add` if you try to install a library crate.]
  (rust-lang/cargo#11410)
- [Cargo now sets the `CARGO_BIN_NAME` environment variable also for binary examples.]
  (rust-lang/cargo#11705)

Rustdoc
-----

- [Vertically compact trait bound formatting.]
  (rust-lang/rust#102842)
- [Only include stable lints in `rustdoc::all` group.]
  (rust-lang/rust#106316)
- [Compute maximum Levenshtein distance based on the query.]
  (rust-lang/rust#107141)
- [Remove inconsistently-present sidebar tooltips.]
  (rust-lang/rust#107490)
- [Search by macro when query ends with `!`.]
  (rust-lang/rust#108143)

Compatibility Notes
-------------------

- [The `rust-analysis` component from `rustup` now only contains
  a warning placeholder.]
  (rust-lang/rust#101841) This was primarily
  intended for RLS, and the corresponding `-Zsave-analysis` flag
  has been removed from the compiler as well.
- [Unaligned references to packed fields are now a hard error.]
  (rust-lang/rust#102513) This has been
  a warning since 1.53, and denied by default with a future-compatibility
  warning since 1.62.
- [Update the minimum external LLVM to 14.]
  (rust-lang/rust#107573)
- [Cargo now emits errors on invalid characters in a registry token.]
  (rust-lang/cargo#11600)
- [When `default-features` is set to false of a workspace dependency,
  and an inherited dependency of a member has `default-features =
  true`, Cargo will enable default features of that dependency.]
  (rust-lang/cargo#11409)
- [Cargo denies `CARGO_HOME` in the `[env]` configuration table.
  Cargo itself doesn't pick up this value, but recursive calls to
  cargo would, which was not intended.]
  (rust-lang/cargo#11644)
- [Debuginfo for build dependencies is now off if not explicitly
  set. This is expected to improve the overall build time.]

  (rust-lang/cargo#11252)

Internal Changes
----------------

These changes do not affect any public interfaces of Rust, but they represent
significant improvements to the performance or internals of rustc and related
tools.

- [Move `format_args!()` into AST (and expand it during AST lowering)]
  (rust-lang/rust#106745)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-traits Area: Trait system disposition-merge This issue / PR is in PFCP or FCP with a disposition to merge it. finished-final-comment-period The final comment period is finished for this PR / Issue. merged-by-bors This PR was explicitly merged by bors. perf-regression Performance regression. perf-regression-triaged The performance regression has been triaged. S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

rustdoc: awkward vertical spacing on trait bounds