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

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

While the 2024 edition is unstable, searching for stable attribute macros like derive leads you to a page that says the attribute is unstable. This is misleading, it is the re-export that is unstable. The search index only shows one entry, and the unstable page doesn't tell you why it is unstable.
- Example: Go to https://doc.rust-lang.org/1.84.0/core/index.html and search for derive. It will lead you to https://doc.rust-lang.org/1.84.0/core/prelude/rust_2024/attr.derive.html which says it is unstable.
Some of the pages are now duplicated. Example:
- https://doc.rust-lang.org/1.84.0/core/prelude/rust_2024/attr.derive.html
- https://doc.rust-lang.org/1.84.0/core/prelude/v1/attr.derive.html
This is inconsistent with the other edition preludes, which use doc(no_inline).
This may cause problems with future editions, which need to figure out how to structure this similar problem.

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.

@rustbot

@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

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.

@rustbot

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

Unrolled build for rust-lang#136886

Remove the common prelude module

Rollup merge of rust-lang#136886 - ehuss:remove-prelude-common, r=jhp…

Remove the common prelude module

Rollup merge of rust-lang#136886 - ehuss:remove-prelude-common, r=jhp…

Remove the common prelude module

Navigation Menu

Repository navigation

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

4 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

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

Description

Activity

traviscross commented on Jan 28, 2025

traviscross commented on Jan 28, 2025

traviscross commented on Feb 11, 2025

4 remaining items

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions