Hide doc(hidden) items from auto suggestions

[EFanZh]

For example, rust-analyzer suggests using futures::FutureExt, which is not publicly documented: https://docs.rs/futures/0.3.12/futures/?search=FutureExt.

[jhpratt]

This could probably be lumped in with #824.

[jonas-schievink]

futures::FutureExt is publicly documented and not marked #[doc(hidden)], so it should appear in completions. However it does look like flyimport suggestions ignore #[doc(hidden)], even after #9715.

[EFanZh]

@jonas-schievink The source code says futures::FutureExt is marked #[doc(hidden)]: https://docs.rs/futures/0.3.16/src/futures/lib.rs.html#107-108.

[lnicola]

The re-export is hidden, not the trait.

[flodiebold]

Soo if the reexport is hidden, does that mean we don't want to import futures::FutureExt and should use futures::future::FutureExt? 🤔 And we shouldn't autocomplete FutureExt when the user writes futures::?

[lnicola]

That's what I would expect.

[flodiebold]

What's the intention of these reexports then?

[flodiebold]

This example imports futures::StreamExt, for example.

[Veykril]

And we shouldn't autocomplete FutureExt when the user writes futures::?

That's blocked on recording imports in the hir then I believe. cc #9197

[lnicola]

TBH, I think the intention was to use the re-export (otherwise why would it be there, and it's a common pattern to export shorter paths). But on the other hand, it makes sense for the documentation to sit next to the implementation, so I'm not sure what would be best here.

[flodiebold]

Yeah, I think my point is that it seems the situation with doc(hidden) isn't quite as clear as it seemed. Some reexports are doc(hidden) because they're not supposed to be used, but these ones are. Although, if they're supposed to be used, probably they'd ideally also be documented, just maybe in a different way? Maybe it's a missing rustdoc feature 🤔

[lnicola]

Yeah, I feel the same way. Maybe there should be another attribute saying "use this other path instead of this one".

CC @jyn514 maybe.

Just so you won't have to re-read the whole thing, the problem is that most of the time, #[doc(hidden)] means "we need to make this public, but don't use it". On the other hand, we have cases like futures::future::FutureExt, which is documented, but is re-exported as futures::FutureExt. The later should probably be used to expose shorter paths, but it's #[doc(hidden)] in order to avoid confusing the users with duplicate documented traits.

Two solutions I can think of would be:

1. mark futures::future::FutureExt as "don't offer suggestions to import this, but allow re-exports", then we'd display the documentation of the original trait on the re-export.
2. mark futures::FutureExt as "ignore the #[doc(hidden)] here, but pass through the docs"

[jyn514]

Yeah, I think my point is that it seems the situation with doc(hidden) isn't quite as clear as it seemed. Some reexports are doc(hidden) because they're not supposed to be used, but these ones are. Although, if they're supposed to be used, probably they'd ideally also be documented, just maybe in a different way? Maybe it's a missing rustdoc feature thinking

This seems like a bug in the crate? Why would you annotate the item with doc(hidden) if you don't intend for it to be used? IMO the proper fix here is to remove doc(hidden) from futures::Future and add doc(no_inline) instead (which should be the default anyway since it's in the same crate).

[seanmonstar]

As another example, warp re-exports a lot of it's filters at the root, to allow for convenient usage (warp::post(), warp::header(), warp::cors(), etc). However, I manipulate the docs by making all of those doc(hidden), since I don't want the main doc page to have a huge list of functions. Instead, the docs are structures to take a user to a filters or replies, and even then, filters are subdivided by types.

All the examples in warp show using the shorter import. I don't see that as a bug in warp, but as a way to direct the way a user finds the docs, in an attempt to not overwhelm them.

[jyn514]

@seanmonstar I have the same question though: why not use doc(no_inline)? That still shows the imports are available without adding all their docs to the main page. Currently it sounds like the docs for hyper aren't consistent with the examples.

[seanmonstar]

I don't want the main doc page to have a huge list of functions.

This is why.