Improve SpatialBundle docs
#9673
Conversation
| /// * To get the global transform of an entity, you should get its [`GlobalTransform`]. | ||
| /// * For hierarchies to work correctly, you must have all four components. | ||
| /// * You may use the [`SpatialBundle`] to guarantee this. | ||
| /// It consists of transform components, |
There was a problem hiding this comment.
I think this whole paragraph is unhelpful and prone to getting outdated.
Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
alice-i-cecile
added
the
S-Ready-For-Final-Review
|
Something that is a little confusing to me: why is It may also be worthwhile to leave a tiny bit of info about what kind of |
I believe it's because the purpose this bundle is actually for rendering. Therefore, visibility has a fundamental role in answering the question "where should this be drawn?"
That detail would be better suited for Transform.scale |
# Objective This PR aims to fix a handful of problems with the `SpatialBundle` docs: The docs describe the role of the single components of the bundle, overshadowing the purpose of `SpatialBundle` itself. Also, those items may be added, removed or changed over time, as it happened with bevyengine#9497, requiring a higher maintenance effort, which will often result in errors, as it happened. ## Solution Just describe the role of `SpatialBundle` and of the transform and visibility concepts, without mentioning the specific component types. Since the bundle has public fields, the reader can easily click them and read the documentation if they need to know more. I removed the mention of numbers of components since they were four, now they are five, and who knows how many they will be in the future. In this process, I removed the bullet points, which are no longer needed, and were contextually wrong in the first place, since they were meant to list the components, but ended up describing use-cases and requirements for hierarchies. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
Objective
This PR aims to fix a handful of problems with the
SpatialBundledocs:The docs describe the role of the single components of the bundle, overshadowing the purpose of
SpatialBundleitself. Also, those items may be added, removed or changed over time, as it happened with #9497, requiring a higher maintenance effort, which will often result in errors, as it happened.Solution
Just describe the role of
SpatialBundleand of the transform and visibility concepts, without mentioning the specific component types. Since the bundle has public fields, the reader can easily click them and read the documentation if they need to know more. I removed the mention of numbers of components since they were four, now they are five, and who knows how many they will be in the future. In this process, I removed the bullet points, which are no longer needed, and were contextually wrong in the first place, since they were meant to list the components, but ended up describing use-cases and requirements for hierarchies.