Improve EntityMap API (#5231)

# Objective

`EntityMap` lacks documentation, don't have `len()` / `is_empty` and `insert` doesn't work as in the regular HashMap`.

## Solution

* Add `len()` method.
* Return previously mapped entity from `insert()` as in the regular `HashMap`.
* Add documentation.

---

## Changelog

* Add `EntityMap::len()`.
* Return previously mapped entity from `EntityMap::insert()` as in the regular `HashMap`.
* Add documentation for `EntityMap` methods.

crates/bevy_ecs/src/entity/map_entities.rs

@@ -23,24 +23,38 @@ pub trait MapEntities {
     fn map_entities(&mut self, entity_map: &EntityMap) -> Result<(), MapEntitiesError>;
 }
 
+/// A mapping from one set of entities to another.
+///
+/// The API generally follows [`HashMap`], but each [`Entity`] is returned by value, as they are [`Copy`].
+///
+/// This is typically used to coordinate data transfer between sets of entities, such as between a scene and the world or over the network.
+/// This is required as [`Entity`] identifiers are opaque; you cannot and do not want to reuse identifiers directly.
 #[derive(Default, Debug)]
 pub struct EntityMap {
     map: HashMap<Entity, Entity>,
 }
 
 impl EntityMap {
-    pub fn insert(&mut self, from: Entity, to: Entity) {
+    /// Inserts an entities pair into the map.
-        self.map.insert(from, to);
+    ///
+    /// If the map did not have `from` present, [`None`] is returned.
+    ///
+    /// If the map did have `from` present, the value is updated, and the old value is returned.
+    pub fn insert(&mut self, from: Entity, to: Entity) -> Option<Entity> {
+        self.map.insert(from, to)
     }
 
-    pub fn remove(&mut self, entity: Entity) {
+    /// Removes an `entity` from the map, returning the mapped value of it if the `entity` was previously in the map.
-        self.map.remove(&entity);
+    pub fn remove(&mut self, entity: Entity) -> Option<Entity> {
+        self.map.remove(&entity)
     }
 
+    /// Gets the given entity's corresponding entry in the map for in-place manipulation.
     pub fn entry(&mut self, entity: Entity) -> Entry<'_, Entity, Entity> {
         self.map.entry(entity)
     }
 
+    /// Returns the corresponding mapped entity.
     pub fn get(&self, entity: Entity) -> Result<Entity, MapEntitiesError> {
         self.map
             .get(&entity)
@@ -48,11 +62,23 @@ impl EntityMap {
             .ok_or(MapEntitiesError::EntityNotFound(entity))
     }
 
+    /// An iterator visiting all keys in arbitrary order.
     pub fn keys(&self) -> impl Iterator<Item = Entity> + '_ {
         self.map.keys().cloned()
     }
 
+    /// An iterator visiting all values in arbitrary order.
     pub fn values(&self) -> impl Iterator<Item = Entity> + '_ {
         self.map.values().cloned()
     }
+
+    /// Returns the number of elements in the map.
+    pub fn len(&self) -> usize {
+        self.map.len()
+    }
+
+    /// Returns true if the map contains no elements.
+    pub fn is_empty(&self) -> bool {
+        self.map.is_empty()
+    }
 }