Merge #196

196: Improve docs of BatchController r=azriel91 a=vorner

* Clarify safety of the `create` method.
* Link directly to the example on github; this saves some time searching
  for it and it also avoids confusion in which repository the example
  lives, as the trait is re-exported in `specs`.

Related to amethyst/specs#689.

Please do check that what I state here is correct. It's gathered from reading other documentation and trying to understand it as a user of the library, but I didn't write the code.

I'm not updating the changelog, since there's no actual code change, just some documentation improvements. If you think this still requires an entry, I'll add it.

Also, am I right to assume that if I register a batch that contains some thread-local systems, they'll still be handled as `!Send` internally and nothing will allow the user to move them to a different thread, etc?

Co-authored-by: Michal 'vorner' Vaner <[email protected]>

src/dispatch/batch.rs

@@ -70,7 +70,8 @@ pub trait BatchController<'a, 'b> {
     ///
     /// So this mechanism allows you to fetch safely the specified `Resource`
     /// in the `BatchController`.
-    /// The example "examples/batch_dispatching.rs" show how to use it.
+    /// The example
+    /// [examples/batch_dispatching.rs](https://github.com/amethyst/shred/blob/master/examples/batch_dispatching.rs) show how to use it.
     ///
     /// Note that it's not required to specify the sub systems resources here
     /// because they are handled automatically.
@@ -90,6 +91,10 @@ pub trait BatchController<'a, 'b> {
     /// to uphold quarantees of `Send` only when it's created with
     /// correctly constructed `BatchAccessor`.
     /// `BatchAccessor` is meant for tracking which resourced are being used by the controller.
+    ///
+    /// In particular, this is not to be called directly by a user code. The `DispatcherBuilder`
+    /// upholds all the guarantees internally. There's no requirement on *implementer* of this
+    /// method.
     unsafe fn create(accessor: BatchAccessor, dispatcher: Dispatcher<'a, 'b>) -> Self;
 }