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

2024 edition prelude item docs are not inlined, and cause some duplication and confusion #136102

Closed
ehuss opened this issue Jan 26, 2025 · 3 comments · Fixed by #136886
Closed
Labels
A-edition-2024 Area: The 2024 edition C-bug Category: This is a bug. T-edition Relevant to the edition team. T-libs-api Relevant to the library API team, which will review and decide on the PR/issue.

Comments

@ehuss
Copy link
Contributor

ehuss commented Jan 26, 2025

#116016 made some changes to how the prelude items are structured which causes some problems with how the documentation is generated:

I would like to propose that after #134272 merges to undo the introduction of the common module, and revert it back to the previous state where rust_2024 re-exports v1 with doc(no_inline). Unfortunately this will break/delete existing pages like https://doc.rust-lang.org/core/prelude/rust_2024/attr.derive.html. I'm personally fine with that.

@ehuss ehuss added A-edition-2024 Area: The 2024 edition C-bug Category: This is a bug. labels Jan 26, 2025
@rustbot rustbot added the needs-triage This issue may need triage. Remove it if it has been sufficiently triaged. label Jan 26, 2025
@traviscross
Copy link
Contributor

@rustbot labels +I-libs-api-nominated
cc @rust-lang/libs-api

What's the situation on being able to give canonical paths to the macros and attribute macros here?:

https://doc.rust-lang.org/core/prelude/v1/index.html#macros

While reverting the use of the common module would fix the problem noted here, without giving these canonical paths, we'd still be left with the oddity that the only place that, e.g. derive is documented is under its prelude path:

https://doc.rust-lang.org/core/prelude/v1/attr.derive.html

@rustbot rustbot added the I-libs-api-nominated Nominated for discussion during a libs-api team meeting. label Jan 28, 2025
@traviscross traviscross added T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. T-libs-api Relevant to the library API team, which will review and decide on the PR/issue. T-edition Relevant to the edition team. and removed I-libs-api-nominated Nominated for discussion during a libs-api team meeting. needs-triage This issue may need triage. Remove it if it has been sufficiently triaged. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Jan 28, 2025
@traviscross
Copy link
Contributor

traviscross commented Jan 28, 2025

Worth mentioning, if we did ever need to remove something from an edition prelude that remained in older preludes, another way we might do it, rather than having a common module and removing doc(no_inline), would be to elaborate the v1 imports rather than using the v1::* (or e.g. rust_2021::*) glob import. That would at least make it easy to see what was added in the new prelude. Seeing what was removed would be harder, but that's a problem with the inlining approach as well.

@traviscross traviscross added the I-libs-api-nominated Nominated for discussion during a libs-api team meeting. label Feb 4, 2025
@traviscross
Copy link
Contributor

@rustbot labels -I-libs-api-nominated

This was discussed in the libs-api call today. Libs-api is OK with the strategy of reverting the common module.

If we ever did need to remove something from a prelude over an edition, the strategy of elaborating the import also sounded right to people.

On the matter of giving paths to these macros, the team also felt warmly about that. One matter that was raised was the question of whether this might affect what is brought into scope for users of the no_implicit_prelude attribute. It was theorized that, in this case, todo would still be brought into scope but not derive, and that exporting derive as std::derive would change this and thus we'd need to consider backward compatibility concerns.

Fortunately, it doesn't seem this is the case. Firstly, the behavior that would have given rise to this is exclusive to Rust 2015. Quoting the Reference:

In the 2015 edition, the no_implicit_prelude attribute does not affect the macro_use prelude, and all macros exported from the standard library are still included in the macro_use prelude. Starting in the 2018 edition, it will remove the macro_use prelude.

But, moreover, even without a std::derive path, derive is still part of the macro_use prelude, and so even in Rust 2015 there is no difference. E.g.:

//@ edition: 2015
#![no_implicit_prelude]

#[derive()]
struct S;

fn main() {
    let _ = todo!();
}

Playground link

On the call, the decision of the team was that PRs adding paths to these macros should be nominated for libs-api so that these can be handled via FCP.

@rustbot rustbot removed the I-libs-api-nominated Nominated for discussion during a libs-api team meeting. label Feb 11, 2025
ehuss added a commit to ehuss/rust that referenced this issue Feb 11, 2025
This fixes the issues described in
rust-lang#136102. Primarily, this
resolves some issues with how the documentation for the prelude is
generated:

- It avoids showing "unstable" for macros in the prelude that are
  actually stable.
- Avoids duplication of some pages due to the previous lack of
  `doc(no_inline)`.
- Makes the different edition preludes consistent, and sets a pattern
  that can be used by future editions.

We may need to rearrange these modules in the future if we decide to
remove anything from the prelude again. If we do, I think we should look
into a different solution that avoids the documentation problems.
ehuss added a commit to ehuss/rust that referenced this issue Feb 11, 2025
This fixes the issues described in
rust-lang#136102. Primarily, this
resolves some issues with how the documentation for the prelude is
generated:

- It avoids showing "unstable" for macros in the prelude that are
  actually stable.
- Avoids duplication of some pages due to the previous lack of
  `doc(no_inline)`.
- Makes the different edition preludes consistent, and sets a pattern
  that can be used by future editions.

We may need to rearrange these modules in the future if we decide to
remove anything from the prelude again. If we do, I think we should look
into a different solution that avoids the documentation problems.
workingjubilee added a commit to workingjubilee/rustc that referenced this issue Feb 14, 2025
…ratt

Remove the common prelude module

This fixes the issues described in rust-lang#136102. Primarily, this resolves some issues with how the documentation for the prelude is generated:

- It avoids showing "unstable" for macros in the prelude that are actually stable.
- Avoids duplication of some pages due to the previous lack of `doc(no_inline)`.
- Makes the different edition preludes consistent, and sets a pattern that can be used by future editions.

We may need to rearrange these modules in the future if we decide to remove anything from the prelude again. If we do, I think we should look into a different solution that avoids the documentation problems.

Closes rust-lang#136102
@bors bors closed this as completed in c21a76f Feb 14, 2025
rust-timer added a commit to rust-lang-ci/rust that referenced this issue Feb 14, 2025
Rollup merge of rust-lang#136886 - ehuss:remove-prelude-common, r=jhpratt

Remove the common prelude module

This fixes the issues described in rust-lang#136102. Primarily, this resolves some issues with how the documentation for the prelude is generated:

- It avoids showing "unstable" for macros in the prelude that are actually stable.
- Avoids duplication of some pages due to the previous lack of `doc(no_inline)`.
- Makes the different edition preludes consistent, and sets a pattern that can be used by future editions.

We may need to rearrange these modules in the future if we decide to remove anything from the prelude again. If we do, I think we should look into a different solution that avoids the documentation problems.

Closes rust-lang#136102
github-actions bot pushed a commit to model-checking/verify-rust-std that referenced this issue Feb 22, 2025
This fixes the issues described in
rust-lang#136102. Primarily, this
resolves some issues with how the documentation for the prelude is
generated:

- It avoids showing "unstable" for macros in the prelude that are
  actually stable.
- Avoids duplication of some pages due to the previous lack of
  `doc(no_inline)`.
- Makes the different edition preludes consistent, and sets a pattern
  that can be used by future editions.

We may need to rearrange these modules in the future if we decide to
remove anything from the prelude again. If we do, I think we should look
into a different solution that avoids the documentation problems.
github-actions bot pushed a commit to carolynzech/rust that referenced this issue Feb 22, 2025
This fixes the issues described in
rust-lang#136102. Primarily, this
resolves some issues with how the documentation for the prelude is
generated:

- It avoids showing "unstable" for macros in the prelude that are
  actually stable.
- Avoids duplication of some pages due to the previous lack of
  `doc(no_inline)`.
- Makes the different edition preludes consistent, and sets a pattern
  that can be used by future editions.

We may need to rearrange these modules in the future if we decide to
remove anything from the prelude again. If we do, I think we should look
into a different solution that avoids the documentation problems.
github-actions bot pushed a commit to tautschnig/verify-rust-std that referenced this issue Feb 22, 2025
This fixes the issues described in
rust-lang#136102. Primarily, this
resolves some issues with how the documentation for the prelude is
generated:

- It avoids showing "unstable" for macros in the prelude that are
  actually stable.
- Avoids duplication of some pages due to the previous lack of
  `doc(no_inline)`.
- Makes the different edition preludes consistent, and sets a pattern
  that can be used by future editions.

We may need to rearrange these modules in the future if we decide to
remove anything from the prelude again. If we do, I think we should look
into a different solution that avoids the documentation problems.
github-actions bot pushed a commit to thanhnguyen-aws/verify-rust-std that referenced this issue Feb 22, 2025
This fixes the issues described in
rust-lang#136102. Primarily, this
resolves some issues with how the documentation for the prelude is
generated:

- It avoids showing "unstable" for macros in the prelude that are
  actually stable.
- Avoids duplication of some pages due to the previous lack of
  `doc(no_inline)`.
- Makes the different edition preludes consistent, and sets a pattern
  that can be used by future editions.

We may need to rearrange these modules in the future if we decide to
remove anything from the prelude again. If we do, I think we should look
into a different solution that avoids the documentation problems.
github-actions bot pushed a commit to thanhnguyen-aws/verify-rust-std that referenced this issue Mar 3, 2025
This fixes the issues described in
rust-lang#136102. Primarily, this
resolves some issues with how the documentation for the prelude is
generated:

- It avoids showing "unstable" for macros in the prelude that are
  actually stable.
- Avoids duplication of some pages due to the previous lack of
  `doc(no_inline)`.
- Makes the different edition preludes consistent, and sets a pattern
  that can be used by future editions.

We may need to rearrange these modules in the future if we decide to
remove anything from the prelude again. If we do, I think we should look
into a different solution that avoids the documentation problems.
github-actions bot pushed a commit to thanhnguyen-aws/verify-rust-std that referenced this issue Mar 4, 2025
This fixes the issues described in
rust-lang#136102. Primarily, this
resolves some issues with how the documentation for the prelude is
generated:

- It avoids showing "unstable" for macros in the prelude that are
  actually stable.
- Avoids duplication of some pages due to the previous lack of
  `doc(no_inline)`.
- Makes the different edition preludes consistent, and sets a pattern
  that can be used by future editions.

We may need to rearrange these modules in the future if we decide to
remove anything from the prelude again. If we do, I think we should look
into a different solution that avoids the documentation problems.
github-actions bot pushed a commit to tautschnig/verify-rust-std that referenced this issue Mar 6, 2025
This fixes the issues described in
rust-lang#136102. Primarily, this
resolves some issues with how the documentation for the prelude is
generated:

- It avoids showing "unstable" for macros in the prelude that are
  actually stable.
- Avoids duplication of some pages due to the previous lack of
  `doc(no_inline)`.
- Makes the different edition preludes consistent, and sets a pattern
  that can be used by future editions.

We may need to rearrange these modules in the future if we decide to
remove anything from the prelude again. If we do, I think we should look
into a different solution that avoids the documentation problems.
github-actions bot pushed a commit to thanhnguyen-aws/verify-rust-std that referenced this issue Mar 6, 2025
This fixes the issues described in
rust-lang#136102. Primarily, this
resolves some issues with how the documentation for the prelude is
generated:

- It avoids showing "unstable" for macros in the prelude that are
  actually stable.
- Avoids duplication of some pages due to the previous lack of
  `doc(no_inline)`.
- Makes the different edition preludes consistent, and sets a pattern
  that can be used by future editions.

We may need to rearrange these modules in the future if we decide to
remove anything from the prelude again. If we do, I think we should look
into a different solution that avoids the documentation problems.
github-actions bot pushed a commit to tautschnig/verify-rust-std that referenced this issue Mar 11, 2025
This fixes the issues described in
rust-lang#136102. Primarily, this
resolves some issues with how the documentation for the prelude is
generated:

- It avoids showing "unstable" for macros in the prelude that are
  actually stable.
- Avoids duplication of some pages due to the previous lack of
  `doc(no_inline)`.
- Makes the different edition preludes consistent, and sets a pattern
  that can be used by future editions.

We may need to rearrange these modules in the future if we decide to
remove anything from the prelude again. If we do, I think we should look
into a different solution that avoids the documentation problems.
github-actions bot pushed a commit to tautschnig/verify-rust-std that referenced this issue Mar 11, 2025
…ratt

Remove the common prelude module

This fixes the issues described in rust-lang#136102. Primarily, this resolves some issues with how the documentation for the prelude is generated:

- It avoids showing "unstable" for macros in the prelude that are actually stable.
- Avoids duplication of some pages due to the previous lack of `doc(no_inline)`.
- Makes the different edition preludes consistent, and sets a pattern that can be used by future editions.

We may need to rearrange these modules in the future if we decide to remove anything from the prelude again. If we do, I think we should look into a different solution that avoids the documentation problems.

Closes rust-lang#136102
github-actions bot pushed a commit to tautschnig/verify-rust-std that referenced this issue Mar 11, 2025
This fixes the issues described in
rust-lang#136102. Primarily, this
resolves some issues with how the documentation for the prelude is
generated:

- It avoids showing "unstable" for macros in the prelude that are
  actually stable.
- Avoids duplication of some pages due to the previous lack of
  `doc(no_inline)`.
- Makes the different edition preludes consistent, and sets a pattern
  that can be used by future editions.

We may need to rearrange these modules in the future if we decide to
remove anything from the prelude again. If we do, I think we should look
into a different solution that avoids the documentation problems.
github-actions bot pushed a commit to tautschnig/verify-rust-std that referenced this issue Mar 11, 2025
…ratt

Remove the common prelude module

This fixes the issues described in rust-lang#136102. Primarily, this resolves some issues with how the documentation for the prelude is generated:

- It avoids showing "unstable" for macros in the prelude that are actually stable.
- Avoids duplication of some pages due to the previous lack of `doc(no_inline)`.
- Makes the different edition preludes consistent, and sets a pattern that can be used by future editions.

We may need to rearrange these modules in the future if we decide to remove anything from the prelude again. If we do, I think we should look into a different solution that avoids the documentation problems.

Closes rust-lang#136102
github-actions bot pushed a commit to model-checking/verify-rust-std that referenced this issue Mar 11, 2025
This fixes the issues described in
rust-lang#136102. Primarily, this
resolves some issues with how the documentation for the prelude is
generated:

- It avoids showing "unstable" for macros in the prelude that are
  actually stable.
- Avoids duplication of some pages due to the previous lack of
  `doc(no_inline)`.
- Makes the different edition preludes consistent, and sets a pattern
  that can be used by future editions.

We may need to rearrange these modules in the future if we decide to
remove anything from the prelude again. If we do, I think we should look
into a different solution that avoids the documentation problems.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-edition-2024 Area: The 2024 edition C-bug Category: This is a bug. T-edition Relevant to the edition team. T-libs-api Relevant to the library API team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants