Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix doc visibility issues. #2356

Merged
merged 2 commits into from
Feb 9, 2023
Merged

Conversation

xStrom
Copy link
Member

@xStrom xStrom commented Feb 8, 2023

@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 xStrom added docs concerns documentation S-needs-review waits for review labels Feb 8, 2023
Copy link
Collaborator

@jneem jneem left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Odd, I wonder if this was an intentional change in rustdoc.

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?)
  • whether making it pub(crate) in the submodule and then doc(inline) at top-level whould have the desired effect?

But it's too late for me right now to experiment with this. Also I guess the pub(crate) variant would be a breaking change, so it isn't worth the trouble even if it works...

@xStrom
Copy link
Member Author

xStrom commented Feb 9, 2023

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

@xStrom xStrom removed the S-needs-review waits for review label Feb 9, 2023
@xStrom xStrom merged commit 115e46c into linebender:master Feb 9, 2023
@xStrom xStrom deleted the doc-fixes-again branch February 9, 2023 22:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs concerns documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Documentation for LensExt and Widget is missing from druid docs
2 participants