rust-lang / rust-lang/rust

Rustdoc ignores `no_inline` when re-exporting modules from other crates

Open
#131,180 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-cross-crate-reexports C-bug T-rustdoc
Dominant language
Rust
Stars
119k
Forks
16.1k
PR merge metrics
PR metrics pending

Description

This one is going to be a bit difficult to explain, so, here's an example of a rather large workspace experiencing this bug: https://github.com/clarfonthey/bevy/tree/no-inline-bug

Essentially, if a crate example has a module including no_inline exports like so:

pub mod prelude {
    #[doc(no_inline)]
    pub use crate::{thing1, thing2};
}

Then rustdoc will correctly show these as re-exports in the documentation for that module, on that crate. The exports will be shown as crate::thing1 and crate::thing2.

However, if you re-export that module on another crate, then you would expect these items to continue to show up as re-exports, just as example::thing1 and example::thing2 instead of relative to crate::. However, instead Rustdoc simple inlines these.

In the example given, the bevy crate contains pub use bevy_internal::* without any special doc attributes. You'll find that thus, bevy::prelude will inline all of its contents instead of showing them as re-exports, despite the fact that bevy_internal::prelude does show them as re-exports.

Meta

rustc --version --verbose:

rustc 1.83.0-nightly (fb4aebddd 2024-09-30)
binary: rustc
commit-hash: fb4aebddd18d258046ddb51fd41589295259a0fa
commit-date: 2024-09-30
host: x86_64-unknown-linux-gnu
release: 1.83.0-nightly
LLVM version: 19.1.0

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the behavior in the linked bevy workspace, comparing rustdoc output for bevy_internal::prelude with the re-exported bevy::prelude. Trace how #[doc(no_inline)] is handled when modules cross crate boundaries. Done means the re-exported module preserves no_inline behavior and has regression coverage.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
compilers, documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.