Rustdoc: ability to exclude "prelude" modules from search

documentation
1

In crates with prelude modules it often happens that searching for some item will yield multiple results, one for the actual item and one for its re-export in the prelude. This increases noise and makes it harder to find the actual definition of that item, in case you wanted to know its module and which other items are defined along with it. This gets even more noisy when the crate is split into multiple crates, each with its own prelude (see for example bevy, where each item is reported three times or more).

One possible solution for crate authors would be to mark the prelude as #[doc(hidden)], but this has the unfortunate downside that you won't be able to see the contents of the prelude in the documentation.

Would it be possible to tell rustdoc to hide either a specific item or all the items of a module from the search feature, while still producing documentation for them?

2 Likes
2

Perhaps search results should just exclude reexports if the original is already included?

2 Likes
3

How would that works when the current crate only contains re-exports?

For example a pattern I've seen is to have:

  • a main crate foo
  • a child crate foo_bar
  • an item foo_bar::Bar
  • a prelude foo_bar::prelude which re-exports foo_bar::Bar
  • a re-export of all foo_bar's items under foo::bar
  • a re-export of all foo_bar::prelude's items under foo::prelude

In the end the crate foo only contains re-exports of foo_bar::Bar, but I would like to prefer foo::bar::Bar over foo::prelude::Bar

4

I think part of the issue is bevy has inline re-exports in its prelude, which basically tells rustdoc to treat them as separate types. Compare searching for std::FromIterator which uses non-inlined re-exports to searching for bevy::AppTypeRegistry:

image

image

(I'm not sure if the order of re-export last is explicit in the search logic, or just happens to be based on the type layout/naming)

5

Bevy uses #[doc(hidden)] on all prelude re-exports. This was done in [Merged by Bors] - Hide re-exported docs by illuninocte · Pull Request #1985 · bevyengine/bevy · GitHub to fix Hide re-exported docs · Issue #1957 · bevyengine/bevy · GitHub which is exactly the issue here. Seems like it didn't help at all.

6

Hmmm, that seems like a rustdoc bug about cross-crate re-exports of modules containing doc(hidden) items, which was supposedly fixed last year but I guess there's something about bevy's particular setup which didn't get fixed

7

That PR should fix this problem. We just need to reach consensus on whether this is a good approach.

8

As an aside, prelude re-exports are also a problem with IDE auto-importing; I'm not sure how rust-analyzer handles it, but RustRover seems to be somewhat inconsistent – sometimes it (unhelpfully) auto-imports the prelude path, and sometimes it asks which one should be imported. I haven't tested whether RustRover uses #[doc(hidden)] to decide whether a path is eligible for auto-import.

9

On the contray to my experience with RA on neovim, RA always imports non-prelude path, so I thought it would never know there is a prelude to use.

But after seeing the experience sharing, I did some experiments, and found the inconsistency too:

  • on an item needing to import, code action from RA will only help to import the publicly defining path, which is what I've always seen
  • as for the other hint to import from prelude, these E04* error code indicates rustc wants to help to import the prelude path, which I seems to never notice until now :sweat_smile:

1143×614 64 KB

929×250 21.9 KB
788×898 61.9 KB

10

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.