Document query errors

[Selene-Amanita]

Objective

Add documentation to Query and QueryState errors in bevy_ecs (QuerySingleError, QueryEntityError, QueryComponentError)

Solution

• Change display message for QueryEntityError::QueryDoesNotMatch: this error can also happen when the entity has a component which is filtered out (with Without<C>)
• Fix wrong reference in the documentation of Query::get_component and Query::get_component_mut from QueryEntityError to QueryComponentError
• Complete the documentation of the three error enum variants.
• Add examples for QueryComponentError::MissingReadAccess and QueryComponentError::MissingWriteAccess
• Add reference to QueryState in QueryEntityError's documentation.

---

Migration Guide

Expect QueryEntityError::QueryDoesNotMatch's display message to change? Not sure that counts.

[github-actions]

Welcome, new contributor!

Please make sure you've read our contributing guide and we look forward to reviewing your pull request shortly ✨

[Selene-Amanita]

(Just in case, here is the file I used to test the example:)

use bevy::app::App;
use bevy::ecs::{prelude::*, system::QueryComponentError};

#[derive(Component)]
struct OtherComponent;

#[derive(Component)]
struct RequestedComponent;

#[derive(Resource)]
struct SpecificEntity {
    entity: Entity,
}

fn get_missing_read_access_error(query: Query<&RequestedComponent>, res: Res<SpecificEntity>) {
    if let Err(QueryComponentError::MissingReadAccess) = query.get_component::<OtherComponent>(res.entity) {
        println!("query doesn't have read access to OtherComponent");
    }
}

fn get_missing_write_access_error(mut query: Query<&RequestedComponent>, res: Res<SpecificEntity>) {
    if let Err(QueryComponentError::MissingWriteAccess) = query.get_component_mut::<RequestedComponent>(res.entity) {
        println!("query doesn't have write access to RequestedComponent");
    }
}

fn main() {
    App::new()
        .add_startup_system(setup)
        .add_system(get_missing_read_access_error)
        .add_system(get_missing_write_access_error.after(get_missing_read_access_error))
        .run();
}

fn setup(
    mut commands: Commands,
) {
    let entity = commands.spawn((RequestedComponent, OtherComponent)).id();
    commands.insert_resource(SpecificEntity{entity})
}```

[Selene-Amanita]

Applied rustfmt (sorry I thought it was applied automatically somehow)

[harudagondi]

looks good to me

[alice-i-cecile]

Great work, these are much better. Thanks for improving these :)

[alice-i-cecile]

@Selene-Amanita it looks like your doc tests are failing: can you fix those up?

[Selene-Amanita]

@alice-i-cecile I fixed the check-docs check, I think.

I couldn't run cargo miri ("the 'miri' component which provides the command 'cargo-miri' is not available for the 'stable-x86_64-unknown-linux-gnu' toolchain") so hopefully this will work out too.

Btw should I use an assert inside the system in the doc test, to check that this scenario does yield the expected error?

[alice-i-cecile]

Yeah, I would put an assert inside the doc test: it'll act as both clarification and as an extra layer of safety for our ECS code.

Miri won't be doing anything special here: just making sure the tests all pass, so you don't need to worry about it.

[Selene-Amanita]

@alice-i-cecile

Okay! The checks did pass this time but I added assert_eq in 5559ce7.
Questions/remarks:

• cargo fmt doesn't apply formating to tests/examples in doc, right? Should I do something about it?
• I kept bevy_ecs::system::assert_is_system(get_missing_write_access_error);, should I delete it?
• I kept the println! and expanded it a bit for clarity
• I had to derive PartialEq and Debug for RequestedComponent otherwise I would have to make convoluted code

[alice-i-cecile]

cargo fmt doesn't apply formating to tests/examples in doc, right? Should I do something about it?

Mostly we just suffer here :( The tooling for doc tests is really subpar in general, which is a shame because they're very useful. Manually matching it is way more work than it's worth though.

I kept bevy_ecs::system::assert_is_system(get_missing_write_access_error);, should I delete it?

That's fine.

I kept the println! and expanded it a bit for clarity

Great!

I had to derive PartialEq and Debug for RequestedComponent otherwise I would have to make convoluted code

Good choice.

Merging!