Move required components doc to type doc#16575
Move required components doc to type doc#16575alice-i-cecile merged 5 commits intobevyengine:mainfrom
Conversation
alice-i-cecile
added
C-Docs
|
Neat, I had no idea this would work. I prefer this: I think it's more discoverable. |
|
This should probably have a heading or a horizontal rule separating the section from the rest of the docs. Currenly it blends in too much, and sometimes looks like it's a part of some other text even though it should be separate. See image
With a horizontal rule (just using See image
I think this might be a clear enough separation between "type docs" and "docs automatically embedded by Bevy". We could also use a heading, which would look like this: See image
The benefit here is that it shows up in the Sections outline on the left, so it's quicker to navigate to the Required Components section for components with long docs. You can also link to the heading, which could be nice so that you can send a direct link if people are asking about a specific component's required components for whatever reason. The (minor) downside of the heading is that it must be a top-level h1 heading, because otherwise it could be shown "beneath" other sections in the outline, which would be wrong. Being an h1 heading makes it quite prominent, for better or for worse. I think I'm mildly in favor of the heading because of it being shown in the outline, being linkable, and overall looking cleaner, but the horizontal rule could work fine too. Edit: Made the images collapsible since they were taking so much space :P |
By the way, if anyone is wondering if these auto-generated docs show up in VSCode when hovering over a type, they do!
|
|
@SpecificProtagonist I'm very much interested in this: can you make sure CI is green and then ping me for final review? |
|
Oh wow, another nice side effect here is that this makes autocomplete for
Previously you got no suggestions and had to remember if it's |
Jondolf
added
S-Ready-For-Final-Review
Huh, I can confirm that. Sounds like a missing Rust-Analyzer feature (or a bug) - the information is available in derive macro declaration. I'll open an issue in the RA repo (and maybe try to fix it myself). |
Co-authored-by: JMS55 <[email protected]>
BD103
added
the
M-Release-Note
|
I'd like to nominate this for release notes. I think this feature is going to be very valuable to users migrating to required components, especially when it comes to visibility in libraries and plugins. |
# Objective #16575 moved required component docs from the `Component` impl to type docs. However, it doesn't actually link to what [required components](https://docs.rs/bevy/0.15.0/bevy/ecs/component/trait.Component.html#required-components) are and how they work. ## Solution Link to [required components](https://docs.rs/bevy/0.15.0/bevy/ecs/component/trait.Component.html#required-components)! ## Testing I tested the link for some components in different Bevy crates. I did not test in external third party crates, but I would assume that it should work there too. --- ## Showcase  Note: The tooltip doesn't show the `#required-components` anchor for some reason, but it is there. --------- Co-authored-by: Alice Cecile <[email protected]> Co-authored-by: SpecificProtagonist <[email protected]>
…6687) # Objective bevyengine#16575 moved required component docs from the `Component` impl to type docs. However, it doesn't actually link to what [required components](https://docs.rs/bevy/0.15.0/bevy/ecs/component/trait.Component.html#required-components) are and how they work. ## Solution Link to [required components](https://docs.rs/bevy/0.15.0/bevy/ecs/component/trait.Component.html#required-components)! ## Testing I tested the link for some components in different Bevy crates. I did not test in external third party crates, but I would assume that it should work there too. --- ## Showcase  Note: The tooltip doesn't show the `#required-components` anchor for some reason, but it is there. --------- Co-authored-by: Alice Cecile <[email protected]> Co-authored-by: SpecificProtagonist <[email protected]>
# Objective Make documentation of a component's required components more visible by moving it to the type's docs ## Solution Change `#[require]` from a derive macro helper to an attribute macro. Disadvantages: - this silences any unused code warnings on the component, as it is used by the macro! - need to import `require` if not using the ecs prelude (I have not included this in the migration guilde as Rust tooling already suggests the fix) --- ## Showcase  --------- Co-authored-by: Alice Cecile <[email protected]> Co-authored-by: JMS55 <[email protected]>
…6687) # Objective bevyengine#16575 moved required component docs from the `Component` impl to type docs. However, it doesn't actually link to what [required components](https://docs.rs/bevy/0.15.0/bevy/ecs/component/trait.Component.html#required-components) are and how they work. ## Solution Link to [required components](https://docs.rs/bevy/0.15.0/bevy/ecs/component/trait.Component.html#required-components)! ## Testing I tested the link for some components in different Bevy crates. I did not test in external third party crates, but I would assume that it should work there too. --- ## Showcase  Note: The tooltip doesn't show the `#required-components` anchor for some reason, but it is there. --------- Co-authored-by: Alice Cecile <[email protected]> Co-authored-by: SpecificProtagonist <[email protected]>
# Objective Component `require()` IDE integration is fully broken, as of #16575. ## Solution This reverts us back to the previous "put the docs on Component trait" impl. This _does_ reduce the accessibility of the required components in rust docs, but the complete erasure of "required component IDE experience" is not worth the price of slightly increased prominence of requires in docs. Additionally, Rust Analyzer has recently started including derive attributes in suggestions, so we aren't losing that benefit of the proc_macro attribute impl.
|
Thank you to everyone involved with the authoring or reviewing of this PR! This work is relatively important and needs release notes! Head over to bevyengine/bevy-website#1962 if you'd like to help out. |
6 participants
Objective
Make documentation of a component's required components more visible by moving it to the type's docs
Solution
Change
#[require]from a derive macro helper to an attribute macro.Disadvantages:
requireif not using the ecs prelude (I have not included this in the migration guilde as Rust tooling already suggests the fix)Showcase