docs(examples): add examples to Store documentation

To keep the code readable, the examples are not inlined with the code, but
kept in a separate location, using the (nightly) feature [`external_doc`].

To build and open the documentation, run:

    cargo +nightly doc --no-deps --open --features doc

To test the examples in the documentation, run:

    cargo +nightly test --doc --features doc

[`external_doc`]: https://doc.rust-lang.org/beta/unstable-book/language-features/external-doc.html

Author: JeanMertz

Diff for: Cargo.toml

@@ -5,3 +5,9 @@ authors = ["Jean Mertz <[email protected]>"]
 license = "MIT OR Apache-2.0"
 description = "Entity–Component–System library currently in development"
 edition = "2018"
+
+[features]
+doc = []
+
+[dev-dependencies]
+anymap = "0.12"

Diff for: doc/examples/store_accepts.md

@@ -0,0 +1,85 @@
+# Examples
+
+```rust
+#[derive(Debug)]
+struct ComponentStore(anymap::Map);
+
+impl Store for ComponentStore {
+    fn accepts<C: Component>(&self) -> bool {
+        self.0.contains::<Vec<C>>()
+    }
+
+    // other implementations hidden...
+    # fn new() -> Self { ComponentStore(anymap::Map::new()) }
+    # fn register<C: Component>(&mut self) {}
+    # fn push<C: Component>(&mut self, component: C) -> Result<(), String> { Ok(()) }
+    # fn get<C: Component>(&self) -> Option<&[C]> { None }
+    # fn get_mut<C: Component>(&mut self) -> Option<&mut [C]> { None }
+}
+
+# use things::{Component, Store};
+#
+# impl Default for ComponentStore {
+#     fn default() -> Self { Self::new() }
+# }
+```
+
+Using `accepts` without first [`register`]ing a component type will return
+false (as opposed to the [`Err`] we got when trying to [`push`] an instance of
+this type into the store):
+
+```rust
+# fn main() {
+# let mut store = ComponentStore::new();
+assert_eq!(store.accepts::<String>(), false)
+# }
+
+# use things::{Component, Store};
+#
+# #[derive(Debug)]
+# struct ComponentStore(anymap::Map);
+#
+# impl Store for ComponentStore {
+#     fn new() -> Self { ComponentStore(anymap::Map::new()) }
+#     fn register<C: Component>(&mut self) {}
+#     fn accepts<C: Component>(&self) -> bool { self.0.contains::<Vec<C>>() }
+#     fn push<C: Component>(&mut self, component: C) -> Result<(), String> { Ok(()) }
+#     fn get<C: Component>(&self) -> Option<&[C]> { None }
+#     fn get_mut<C: Component>(&mut self) -> Option<&mut [C]> { None }
+# }
+#
+# impl Default for ComponentStore {
+#     fn default() -> Self { Self::new() }
+# }
+```
+
+After [`register`]ing, `true` is returned:
+
+```rust
+# fn main() {
+# let mut store = ComponentStore::new();
+store.register::<String>();
+assert_eq!(store.accepts::<String>(), true)
+# }
+
+# use things::{Component, Store};
+#
+# #[derive(Debug)]
+# struct ComponentStore(anymap::Map);
+#
+# impl Store for ComponentStore {
+#     fn new() -> Self { ComponentStore(anymap::Map::new()) }
+#     fn register<C: Component>(&mut self) { self.0.insert(Vec::<C>::new()); }
+#     fn accepts<C: Component>(&self) -> bool { self.0.contains::<Vec<C>>() }
+#     fn push<C: Component>(&mut self, component: C) -> Result<(), String> { Ok(()) }
+#     fn get<C: Component>(&self) -> Option<&[C]> { None }
+#     fn get_mut<C: Component>(&mut self) -> Option<&mut [C]> { None }
+# }
+#
+# impl Default for ComponentStore {
+#     fn default() -> Self { Self::new() }
+# }
+```
+
+[`register`]: Store::register
+[`push`]: Store::push

Diff for: doc/examples/store_get.md

@@ -0,0 +1,108 @@
+# Examples
+
+```rust
+#[derive(Debug)]
+struct ComponentStore(anymap::Map);
+
+impl Store for ComponentStore {
+    fn get<C: Component>(&self) -> Option<&[C]> {
+        self.0.get::<Vec<C>>().map(|vec| vec.as_slice())
+    }
+
+    // other implementations hidden...
+    # fn new() -> Self { ComponentStore(anymap::Map::new()) }
+    # fn register<C: Component>(&mut self) {}
+    # fn accepts<C: Component>(&self) -> bool { true }
+    # fn push<C: Component>(&mut self, component: C) -> Result<(), String> { Ok(()) }
+    # fn get_mut<C: Component>(&mut self) -> Option<&mut [C]> { None }
+}
+
+# use things::{Component, Store};
+#
+# impl Default for ComponentStore {
+#     fn default() -> Self { Self::new() }
+# }
+```
+
+After implementing `get`, we [`register`] two component types [`u32`] and
+[`u64`], and [`push`] three components into the store:
+
+```rust
+# fn main() {
+let mut store = ComponentStore::new();
+
+store.register::<u32>();
+store.register::<u64>();
+
+store.push(1_u32);
+store.push(2_u64); // note: u64
+store.push(3_u32);
+# }
+
+# use things::{Component, Store};
+#
+# #[derive(Debug)]
+# struct ComponentStore(anymap::Map);
+#
+# impl Store for ComponentStore {
+#     fn new() -> Self { ComponentStore(anymap::Map::new()) }
+#     fn register<C: Component>(&mut self) { self.0.insert(Vec::<C>::new()); }
+#     fn accepts<C: Component>(&self) -> bool { true }
+#     fn push<C: Component>(&mut self, component: C) -> Result<(), String> {
+#         self.0.get_mut::<Vec<C>>().unwrap().push(component); Ok(())
+#     }
+#     fn get<C: Component>(&self) -> Option<&[C]> { None }
+#     fn get_mut<C: Component>(&mut self) -> Option<&mut [C]> { None }
+# }
+#
+# impl Default for ComponentStore {
+#     fn default() -> Self { Self::new() }
+# }
+```
+
+We can now fetch those components using `get`:
+
+```rust
+# fn main() {
+# let mut store = ComponentStore::new();
+#
+# store.register::<u32>();
+# store.register::<u64>();
+#
+# store.push(1_u32);
+# store.push(2_u64);
+# store.push(3_u32);
+
+let components = store.get::<u32>().unwrap();
+assert_eq!(components[0], 1);
+assert_eq!(components[1], 3);
+
+let components = store.get::<u64>().unwrap();
+assert_eq!(components[0], 2);
+# }
+
+# use things::{Component, Store};
+#
+# #[derive(Debug)]
+# struct ComponentStore(anymap::Map);
+#
+# impl Store for ComponentStore {
+#     fn new() -> Self { ComponentStore(anymap::Map::new()) }
+#     fn register<C: Component>(&mut self) { self.0.insert(Vec::<C>::new()); }
+#     fn accepts<C: Component>(&self) -> bool { true }
+#     fn push<C: Component>(&mut self, component: C) -> Result<(), String> {
+#         self.0.get_mut::<Vec<C>>().unwrap().push(component); Ok(())
+#     }
+#     fn get<C: Component>(&self) -> Option<&[C]> {
+#         self.0.get::<Vec<C>>().map(|vec| vec.as_slice())
+#     }
+#     fn get_mut<C: Component>(&mut self) -> Option<&mut [C]> { None }
+# }
+#
+# impl Default for ComponentStore {
+#     fn default() -> Self { Self::new() }
+# }
+```
+
+[`register`]: Store::register
+[`push`]: Store::push

Diff for: doc/examples/store_get_mut.md

@@ -0,0 +1,98 @@
+# Examples
+
+```rust
+#[derive(Debug)]
+struct ComponentStore(anymap::Map);
+
+impl Store for ComponentStore {
+    fn get_mut<C: Component>(&mut self) -> Option<&mut [C]> {
+        self.0.get_mut::<Vec<C>>().map(|vec| vec.as_mut_slice())
+    }
+
+    // other implementations hidden...
+    # fn register<C: Component>(&mut self) { self.0.insert(Vec::<C>::new()); }
+    # fn new() -> Self { ComponentStore(anymap::Map::new()) }
+    # fn accepts<C: Component>(&self) -> bool { true }
+    # fn get<C: Component>(&self) -> Option<&[C]> { None }
+    # fn push<C: Component>(&mut self, component: C) -> Result<(), String> { Ok(()) }
+}
+
+# use things::{Component, Store};
+#
+# impl Default for ComponentStore {
+#     fn default() -> Self { Self::new() }
+# }
+```
+
+After implementing `get_mut`, we [`register`] the component type [`u32`] and
+[`push`] a component into the store:
+
+```rust
+# fn main() {
+let mut store = ComponentStore::new();
+
+store.register::<u32>();
+store.push(1_u32);
+# }
+
+# use things::{Component, Store};
+#
+# #[derive(Debug)]
+# struct ComponentStore(anymap::Map);
+#
+# impl Default for ComponentStore {
+#     fn default() -> Self { Self::new() }
+# }
+#
+# impl Store for ComponentStore {
+#     fn new() -> Self { ComponentStore(anymap::Map::new()) }
+#     fn register<C: Component>(&mut self) { self.0.insert(Vec::<C>::new()); }
+#     fn accepts<C: Component>(&self) -> bool { true }
+#     fn push<C: Component>(&mut self, component: C) -> Result<(), String> {
+#         self.0.get_mut::<Vec<C>>().unwrap().push(component); Ok(())
+#     }
+#     fn get<C: Component>(&self) -> Option<&[C]> { None }
+#     fn get_mut<C: Component>(&mut self) -> Option<&mut [C]> { None }
+# }
+```
+
+After we've done so, we can manipulate the component using `get_mut`:
+
+```rust
+# fn main() {
+# let mut store = ComponentStore::new();
+# store.register::<u32>();
+# store.push(1_u32);
+
+store.get_mut::<u32>().unwrap().iter_mut().for_each(|i| *i += 1);
+
+assert_eq!(store.get::<u32>().unwrap()[0], 2);
+# }
+
+# use things::{Component, Store};
+#
+# #[derive(Debug)]
+# struct ComponentStore(anymap::Map);
+#
+# impl Store for ComponentStore {
+#     fn new() -> Self { ComponentStore(anymap::Map::new()) }
+#     fn register<C: Component>(&mut self) { self.0.insert(Vec::<C>::new()); }
+#     fn accepts<C: Component>(&self) -> bool { true }
+#     fn push<C: Component>(&mut self, component: C) -> Result<(), String> {
+#         self.0.get_mut::<Vec<C>>().unwrap().push(component); Ok(())
+#     }
+#     fn get<C: Component>(&self) -> Option<&[C]> {
+#         self.0.get::<Vec<C>>().map(|vec| vec.as_slice())
+#     }
+#     fn get_mut<C: Component>(&mut self) -> Option<&mut [C]> {
+#         self.0.get_mut::<Vec<C>>().map(|vec| vec.as_mut_slice())
+#     }
+# }
+#
+# impl Default for ComponentStore {
+#     fn default() -> Self { Self::new() }
+# }
+```
+
+[`register`]: Store::register
+[`push`]: Store::push