Documentation improvements

[shaladdle]

@jonhoo @tikue

• Explain | syntax
• Write more about services and clients and when you might return what errors. Have some examples.
• Make it more clear that service implementations must be Clone/Send/'static
  • Add to the readme
  • Add to the macro documentation if it's not there
• Warn of the dangers of mixing FutureService with SyncClient
  • Namely, if the client runs on the same thread as the service's reactor, things hang
• choose crates.io categories
• Clearly specify the costs of sync services

[jonhoo]

Is it still true that services have to be Clone when using FutureService? As far as I can tell, the tokio event-loop will only handle one event internally at a time, and so the service won't need to be cloned?

[tikue]

Currently, this is still true. Some of this code needs to be cleaned up -- for instance, there's a Send bound on FutureService that only exists on the off chance the user wants to start the service via a reactor::core::Remote (a Handle wouldn't require Send). So the bottom line is there is work to do here, but I think if you just wrap your service in an Rc for now it should be fine.

[jonhoo]

Hmm, why is that (that Clone is necessary that is)? Is it fundamental? If not, is there a chance that FutureService methods might start taking a &mut self in the future?

[jonhoo]

We briefly discussed this a while ago but I can't find the discussion right now. I believe from that discussion that it wasn't particularly tied to FutureService though?

[tikue]

To be honest, I don't know why anymore! the tokio_service::Service trait used to have a Send bound, which meant services needed to either be Sync (and wrapped in an Arc) or Clone, and the latter is a generalization of the former. However, I believe the Send bound was removed from Service so this all needs to be revisited. This is one of the things I want to sort out before the next release, and I really want to ship it this week, so stay tuned (or feel free to investigate it independently; PRs always welcome).

[tikue]

(btw, let's move this conversation to #86)

[jonhoo]

Just leaving a note that we also ought to include a generated service somewhere so that the docs contain an easy-to-reference list of things like methods of FutureService.