Make the Commands::add docs more representative of actual use cases

[alice-i-cecile]

How can Bevy's documentation be improved?

The current docs show a contrived example: in real use cases this would be commands.insert_bundle.

Replace this example with two examples:

1. A custom command.
2. Using a closure that operates on &mut World to perform a simple task.

[tigregalis]

What do you mean by the second example of using a closure?

Here's my attempt at the first. This can probably be cut down, maybe removing the need for an app and hiding some of the implementation, but I'm not too familiar with the API, so was hoping for some guidance (then I'll submit a PR). The key thing I wanted to demonstrate was the ability to concurrently submit data, then write to the world using that data at the end of the stage.

use bevy::{prelude::*, utils::HashMap, ecs::system::Command};

/// A custom `Command` for sending (deferred) vote counts concurrently from multiple `System`s
#[derive(Debug)]
struct SendVoteCount {
    candidate: String,
    count: usize,
}

/// A `Resource` which will aggregate the vote counts when `Commands` are flushed at the end of the `Stage`
#[derive(Default)]
struct Votes(HashMap<String, usize>);

impl Command for SendVoteCount {
    fn write(self, world: &mut World) {
        let mut counts = world.get_resource_or_insert_with(Votes::default);
        counts.0.entry(self.candidate).and_modify(|e| *e += self.count).or_insert(self.count);
    }
}

fn count_votes_melbourne(mut commands: Commands) {
    commands.add(SendVoteCount {
        candidate: "Albo".into(),
        count: 9001,
    });
    commands.add(SendVoteCount {
        candidate: "Scomo".into(),
        count: 4242,
    });
}

fn count_votes_brisbane(mut commands: Commands) {
    commands.add(SendVoteCount {
        candidate: "Clive".into(),
        count: 3,
    });
    commands.add(SendVoteCount {
        candidate: "Scomo".into(),
        count: 1997,
    });
    commands.add(SendVoteCount {
        candidate: "Albo".into(),
        count: 203,
    });
}

fn display_count(votes: Res<Votes>) {
    println!("{:?}", votes.0);
}

fn main() {
    App::new()
        .add_system(count_votes_melbourne)
        .add_system(count_votes_brisbane)
        .add_system_to_stage(CoreStage::PostUpdate, display_count)
        .run();
}

[alice-i-cecile]

First example looks great.

With respect to using a closure, Command now has a blanket implementation for all functions that take &mut World as their only argument.

You can use an anonymous function (closure) + Commands::add to conveniently perform arbitrary logic on the world in a one-off fashion.