Document and rename bevy::scene::Entity

[alice-i-cecile]

How can Bevy's documentation be improved?

This type (docs, source) appears to be used to store reflected entities, along with their components in scenes. However, it is a) completely lacking documentation b) very confusingly named: Entity is one of our most important types, and this is closely-related but distinct in important ways.

At a glance, this seems to be a reflection-powered serializable representation of an entity and its components. The entity: u32 field is likely for use with Entity::new() (the standard Entity type), and the entire DynamicScene type is used to spawn groups of entities which contain a number of entities, each with their own run-time defined set of components. These DynamicScenes can be written to file, but not read from.

Later in the same file, EntityMap is used, which contains a map between entities, in the standard bevy_ecs sense. This naming convention seems to be fine.

My first impulse would be to call this DynamicEntity, but please, bikeshed me if you disagree.

[cart]

Yup I generally try to treat Bevy as a "global namespace" and this very clearly breaks that rule of thumb.

[Davier]

DynamicEntity seems very appropriate.

These DynamicScenes can be written to file, but not read from.

We get a Handle<DynamicScene>> when loading a serialized scene from file:

bevy/examples/scene/scene.rs

Line 53 in ccee658

let scene_handle: Handle<DynamicScene> = asset_server.load("scenes/load_scene_example.scn.ron");

(However, we get a Handle<Scene> type when loading a glTF scene, which might be confusing).

[alice-i-cecile]

I've added the good-first-issue tag to this: if you're picking this up; feel free to add very basic docs in your PR. We can help amend them in the process, or expand them in future work and even basic docs are dramatically better than nothing :)