Improve API documentation

[ebkalderon]

I enjoy reading through the Rust standard library documentation, and I want our documentation experience to be of similarly high quality. Some things to think about:

1. Every crate and module should have some kind of top-level description describing its purpose, and maybe a longer code example of how to use it.
2. Each function/method/struct/etc. should have a brief one-line doc comment of what it does. Make sure you mention any cases where it might panic, if any. Brief code snippets demonstrating its usage are great!

If you have more ideas on how to make Amethyst's generated documentation great, leave your thoughts below and I'll update this list later on.

[Xaeroxe]

So this is going to be what I call a "never close" issue because there isn't any specific point at which we can say "this is done" it's also arguably an implicit goal of the project to write good documentation, so I'm not sure if this should be kept open, but I'll ping @amethyst/engine-devs and ask, what should we do with this?

[minecrawler]

how about just using the project? With the task board, it is clear which parts of the docs are being worked on, which parts are in the backlog and so on. That might be better for overview and you could close this issue