bevyengine / bevyengine/bevy

Explain `'w` and `'s` lifetimes better in documentation

Open
#6,953 2 comments 4 reactions 0 assignees View on GitHub
A-ECS C-Docs
Dominant language
Rust
Stars
48.2k
Forks
4.8k
Avg merge
3d 22h
Merged PRs (30d)
161

Description

## How can Bevy's documentation be improved?

There are a lot of types in `bevy_ecs` that has the `'w` and `'s` lifetimes:

- `EventReader`
- `EventWriter`
- `QueryIter`
- `QueryManyIter`
- `QueryCombinationIter`
- `SystemParamItem`
- `ParamSet`
- `Commands`
- `EntityCommands`
- and more...

The best explanation found for these lifetimes are in [`SystemParam`](https://docs.rs/bevy/latest/bevy/ecs/system/trait.SystemParam.html#derive)

Solutions I could think of right now:

1. Rename `'w` and `'s` to `'world` and `'state`. This is not ideal since this will make the code more verbose.
2. Link users to the `SystemParam` documentation. There are a lot of types to document and imo would add more noise to their documentation.
3. Put the documentation in the README, perhaps under a new "Advanced topics" sections.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.