bevyengine / bevyengine/bevy

More directly recommend `Commands`/`Query` `reborrow`ing when needing to pass to other functions.

Open
#15,657 2 comments 3 reactions 0 assignees View on GitHub
A-ECS C-Docs D-Straightforward S-Ready-For-Implementation
Dominant language
Rust
Stars
48.2k
Forks
4.8k
Avg merge
3d 16h
Merged PRs (30d)
171

Description

## How can Bevy's documentation be improved?

We should more clearly and directly recommend that developers write their helper functions to take `Commands` (and friends) directly, instead of passing as references (`&Commands`). And by doing so, these helpers can look just like systems. As an example:

```rust
fn my_system(commands: Commands, foo: Query<&Foo>) {
// we should recommend this:
good_helper(commands.reborrow(), foo.reborrow());
// instead of this:
bad_helper(&mut commands, &foo);
}

// This is kind of annoying:
fn bad_helper(commands: &mut Commands, foo: &Query<&Foo>) {
// ...
}

// This is easier to deal with:
fn good_helper(commands: Commands, foo: Query<&Foo>) {
// ...
}
```

We should recommend `reborrow`ing in the top level docs for `Commands` and `Query`.

Contributor guide

Open the contributing guide

Research direction

Start with the top-level documentation for Commands and Query, which the issue identifies as the intended locations. Review how these types are currently described and add a direct recommendation to pass them by value using reborrow(), with the provided helper-function example; done means both docs clearly recommend this pattern.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.