rustdoc: Prototype implement RFC 3842 with safety::requires attribute

[yilin0518]

Hi! I am a member of safer-rust, a group working toward safer patterns around unsafe Rust. In July 2025, we opened RFC 3842, which explores tagging public unsafe APIs with safety tags and #[safety] attribute.

To help move that discussion forward with something concrete, this PR adds a prototype of one piece of that direction, applied in a way that already works with the standard library today. For now, we implement the inert #[safety::requires(...)] attribute and a rustdoc pipeline that turns it into user-visible documentation before intra-doc links are resolved.

Concretely, the PR adds:

• an unstable rustdoc flag --safety-spec PATH, pointing at a small TOML file (package.name + [tag.*] templates with {placeholder} substitution);
• a new default pass inject-safety-docs, which reads #[safety::requires] on items (e.g. Tag(args…) expanded from TOML, or Tag = "…" for per-site text, including tags that appear in TOML and not in the TOML), and merges the generated Markdown into the item docs (typically under # Safety);
• In the #[safety::requires] attribute, we can use two forms: #[safety::requires(Tag(arg1, arg2, ...))] or #[safety::requires(Tag="description")]. The former requires the Tag must come from TOML. The latter can use costomized Tag name and use the description as its content. Also, the #[safety::requires(Tag="description")] transforms snake_case when the Tag doesn't exist in the TOML, replacing all underscores (_) with spaces and capitalizing the first letter.
• #![register_tool(safety)] in core, so we can add #[safety::requires] attributes in core and can be processed by rustdoc.
• bootstrap wiring so x.py doc library/... can pass a default spec path, while still allowing RUSTDOCFLAGS to override --safety-spec without duplicating the flag.

As an emperimental tool, we performed tests in core. We only modified one function(core::ptr::read_unaligned), adding corresponding #[safety::requires] attribute and removing the original safety contract. By using ./x.py doc library/core --stage 1, we can generate the same safety description.

Several days ago, we opened a zulip chat. Because this touches rustdoc (new unstable flag, default pass ordering, and doc merging) and core (tool registration for inert attributes), we would really appreciate any feedback from rust community. It would help us adjust the prototype and refocus the RFC discussion.

[rustbot]

These commits modify the Cargo.lock file. Unintentional changes to Cargo.lock can be introduced when switching branches and rebasing PRs.

If this was unintentional then you should revert the changes before this PR is merged.
Otherwise, you can ignore this comment.

[rustbot]

r? @notriddle

rustbot has assigned @notriddle.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

• Owners of files modified in this PR: rustdoc
• rustdoc expanded to 9 candidates
• Random selection from GuillaumeGomez, fmease, lolbinarycat, notriddle