Document methods relative to projection
- Dominant language
- Rust
- Stars
- 48.2k
- Forks
- 4.8k
- Avg merge
- 3d 16h
- Merged PRs (30d)
- 171
Description
Following https://github.com/bevyengine/bevy/issues/8492, a bunch of methods were renamed, it basically erased a lot of references to "projection" and replaced them with "clip". I didn't see this PR until after it happened, but I find the documentation (not the migration guide) surrounding it a bit lacking (not saying it's the fault/responsibility of the PR/its author, some of it was also the case before):
- I'm not sure it's clarified anywhere what is a "clip". I assume it's the space/box where stuff end up after the projection just before being rendered, but having next to no knowledge about rendering but knowledge in mathematics, "projection" is a much more understandable term for me and I don't think I'm the only one, it would be nice to have references to it in the comments of methods with "clip" in their name, like https://github.com/bevyengine/bevy/issues/8492 suggested, and/or have a definition of "clip" somewhere
- None of the methods of the trait `CameraProjection` have comments
- The documentation of the methods of the struct `Frustum` talk about `clip_from_world`. I assume it is referring to the method that comes from `ExtractedView`, but it is not clear (I know rustdoc doesn't help with not being able to reference stuff not from dependencies :( but still it could help to say it comes from ExtractedView and/or explain a bit what that method gives
- `ExtractedView` and `ViewUniform` aren't documented. We don't know where they're from (I assume `ExtractedView` is added as a component to the camera but not from `Camera3dBundle`?) or their purpose. Even if it's an internal thing, a brief description might help, especially since the Frustum's doc references it.
- Other types referenced in this PR are not documented like `MeshTransform`
Even if those things wouldn't matter much for someone that just codes a simple game, it might matter to plugin writers and people who want to understand how the rendering side of Bevy works.
Contributor guide
Research direction
Start by reviewing the documentation changes discussed in issue #8492 and the APIs named here: CameraProjection, Frustum, ExtractedView, ViewUniform, and MeshTransform. Clarify what “clip” means relative to projection, document the CameraProjection methods and referenced types, and explain the purpose or source of the rendering types. Done means plugin authors can understand these APIs from their documentation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100