Documentation strings for commands.rs - spawn, despawn, with, with_bundle, insert, insert_one

[Ecsodikas]

I wrote some documentation for the methods on Commands that I find myself using often. And as I started learning bevy those are methods I would have liked to just have a small example directly in the docs, so I made them. Let me know if something is not correct or if something could be written better. Maybe I wrote it too beginner friendly and lost some of the use cases of the methods that I have not encountered yet.

If someone tells me what the undocumented methods do, I'm happy to add those doc strings aswell. :)

[cart]

Thanks for docs! This will definitely help new people learn how to use commands (which is a common issue)

[cart]

This is incorrect. This doesn't create an entity with a given component, but rather with a given DynamicBundle (which is a "set" of components).

It is worth showing two examples here: a spawn example using tuples:

commands.spawn((MyComponentA, MyComponentB))

And an example using a derived Bundle

#[derive(Bundle)]
struct MyBundle {
  a: MyComponentA,
  b: MyComponentB,
}

commands.spawn(MyBundle {
  a: MyComponentA,
  b: MyComponentB,
})

[cart]

And lets call out that the two examples are equivalent.

[cart]

Lets rephrase this to "Adds the given component to the current entity"

[cart]

"Adds a component bundle to an already existing entity"

[cart]

nit: "an already"

[cart]

you can't spawn single components like this. it must be a tuple. Can we replace it with:

commands.spawn((MyComponent,));

Lets fix this in the other examples too.

[Ecsodikas]

Ah, damn. I was deceived by 'SpriteComponents' but it is a Bundle. I always wondered why there was a trailing 's'. Now I know. Should be fine now. (hopefully)

[cart]

Yeah you arent the first person. I'm thinking about replacing the "_Components" suffix with "_Bundle" for clarity.

[cart]

Awesome lets merge this!

[cart]

Ah first we need to resolve the formatting conflicts (you can see the suggested fixes in the build logs)

Looks like you just need to remove the extra newlines from the docs.

[Ecsodikas]

I believe it is not in my power to fix the remaining 5 build actions. Looks like the nightly version of rust is not installed successfully.

[CleanCut]

I bet CI would succeed now. It's been a month of nightlies. 😄

[cart]

Its interesting that norun still caused doctest failures. I'm thinking we should probably just add unit structs and hide them from the docs using this approach: https://doc.rust-lang.org/rustdoc/documentation-tests.html#hiding-portions-of-the-example

That way we still get protection against breakage.

[memoryruins]

The examples will need to be wrapped in some boilerplate since the code is still fully built with no_run and doc tests are treated as external to the current crate, e.g.

/// Despawns only the specified entity, ignoring any other consideration.
/// # Example
/// ```no_run
/// # use bevy_ecs::{Commands, Entity};
/// # fn system(mut commands: Commands) {
/// # let entity_to_despawn = Entity::new(0);
/// commands.despawn(entity_to_despawn);
/// # }
/// ```
pub fn despawn(&mut self, entity: Entity) -> &mut Self {

Another option is to use ignore, but that has no protection from breakage and shows a warning on each example in the docs, so it's usually not preferable.

[cart]

Cool then no-run w/ the additional boilerplate hidden seems like the right call

[Ecsodikas]

Aye, I'm going to build some boilerplate then. I hope I get some spare time on my sunday.

[DJMcNab]

Is there a status update on this @eXodiquas?

[cart]

Closed in favor of #976