Merge #477

477: Insertion documentation r=Xaeroxe a=Aceeri

Fixes #475

<!-- Reviewable:start -->
---
This change is [<img src="https://reviewable.io/review_button.svg" height="34" align="absmiddle" alt="Reviewable"/>](https://reviewable.io/reviews/slide-rs/specs/477)
<!-- Reviewable:end -->


Co-authored-by: Aceeri <[email protected]>

src/storage/mod.rs

@@ -397,6 +397,10 @@ where
 
     /// Inserts new data for a given `Entity`.
     /// Returns the result of the operation as a `InsertResult<T>`
+    ///
+    /// If a component already existed for the given `Entity`, then it will
+    /// be overwritten with the new component. If it did overwrite, then the
+    /// result will contain `Some(T)` where `T` is the previous component.
     pub fn insert(&mut self, e: Entity, mut v: T) -> InsertResult<T> {
         if self.entities.is_alive(e) {
             let id = e.id();

src/world/lazy.rs

@@ -24,6 +24,9 @@ pub struct LazyBuilder<'a> {
 
 impl<'a> Builder for LazyBuilder<'a> {
     /// Inserts a component using [`LazyUpdate`].
+    ///
+    /// If a component was already associated with the entity, it will 
+    /// overwrite the previous component.
     fn with<C>(self, component: C) -> Self
     where
         C: Component + Send + Sync,

src/world/mod.rs

@@ -41,6 +41,9 @@ impl<'a> Iterator for CreateIter<'a> {
 pub trait Builder {
     /// Appends a component and associates it with the entity.
     ///
+    /// If a component was already associated with the entity, it should 
+    /// overwrite the previous component.
+    ///
     /// # Panics
     ///
     /// Panics if the component hasn't been `register()`ed in the
@@ -95,6 +98,10 @@ pub struct EntityBuilder<'a> {
 }
 
 impl<'a> Builder for EntityBuilder<'a> {
+    /// Inserts a component for this entity.
+    ///
+    /// If a component was already associated with the entity, it will 
+    /// overwrite the previous component.
     #[inline]
     fn with<T: Component>(self, c: T) -> Self {
         {