linebender / druid

A data-first Rust-native UI design toolkit.
https://linebender.org/druid/
Apache License 2.0
9.44k stars 569 forks source link

Fix doc visibility issues. #2356

Closed xStrom closed 1 year ago

xStrom commented 1 year ago

@cbondurant reported in #2355 that the docs for Widget and LensExt are missing. Indeed that is the case, as is for Lens, WidgetId, and WidgetExt. I think I checked these just a month ago, and regardless I'm confident that these used to work way earlier, with no code/attribute changes since then.

My best guess is that rustdoc changed how #[doc(hidden)] is inherited. The way we use this attribute is to hide the docs in the widget module but then show them in the re-exported root module. This no longer works and the docs are hidden in the root too. Interestingly the reverse is still possible, we could hide the docs in the root but have them show up in the widget module.

In this PR I decided to just have the docs visible in both the widget module and the root module. We're only talking a few traits here and they're quite fundamental.

Additionally, I made two adjacent changes.

  1. I hid the docs for all deprecated items. We already did this for a bunch, now it is consistent.
  2. I made sure that all re-exported Druid items (e.g. Env) show up as inline docs, not as re-exports.

Fixes #2355

xStrom commented 1 year ago

I wonder if this was an intentional change in rustdoc.

I looked a tiny bit into the Rust changelog. I saw two entries that might be of relevance.

Not sure if one of those is the culprit, or perhaps some other (possibly undocumented) change.

I also wonder

  • whether adding doc(inline) changes things at all? (i.e. if something is doc(inline) at the top-level and doc(hidden) in a submodule, what happens?)

It's hidden in both then.

  • whether making it pub(crate) in the submodule and then doc(inline) at top-level whould have the desired effect?

Also I guess the pub(crate) variant would be a breaking change, so it isn't worth the trouble even if it works...

Yeah I thought of this for a moment but decided against it because it is a breaking change. I tested it now for completeness and was greeted by this:

error[E0365]: `Widget` is only public within the crate, and cannot be re-exported outside