Query::get_component should mention that the compenent must be part of the query

[nicopap]

How can Bevy's documentation be improved?

Query::get_component doesn't mention that it can only return components that are part of the query itself.

The method itself is very niche, as it's mostly an optimization to avoid accessing several components when only one is necessary.

But the documentation mentions none of this. The only caveat is the following paragraph:

In case of a nonexisting entity or mismatched component, a QueryEntityError is returned instead.

It's not enough!

Code seen in the wild (discord conversation):

fn prepare_player(
    mut commands: Commands,
    players: Query<Entity, With<backend::Player>>,
) {
    for player in &players {      
        let transform = *players.get_component::<Transform>(player).expect("Entity does not contain transform!");
    }
}

This code will always panic! Independently of whether the Entity in question has a Transform component or not. Since players doesn't have access to the Transform component, it cannot return a reference to it.

What should be done

The method should get additional wording saying "can only return components present in the query" (better phrasing pending). This should be slapped at the front of the doc, maybe part of the first paragraph.

[mockersf]

It seems the doc is wrong, get_component returns a QueryComponentError, not a QueryEntityError.

In the case mentioned in this issue, it should return a QueryComponentError::MissingReadAccess which has quite a good documentation already (in main only for now)

[Selene-Amanita]

Looks like I forgot to fix that when implementing #8692 yeah.

I have changes right now to fix this alongside #8917. I'll create a pull request tomorrow to fix both.