Extend snake_to_camel plugin to replace {} in the doc string with the original snake-cased ident. (#50)

* Extend snake_to_camel plugin to replace {} in the doc string with the origin snake-cased ident.

Also, track tokio-rs master.

This is really ad-hoc, undiscoverable, and unintuitive, but there's no way to programmatically create doc strings
in regular code, and I want to produce better doc strings for the associated types.

Given `fn foo_bar`:

Before: `/// The type of future returned by the function of the same name.`
After: ``/// The type of future returned by `{}`.``
    => `/// The type of future returned by foo_bar.`

* Fix some docs

* Use a helper fn on pipeline::Frame instead of handrolled match.

* Don't hide docs for ClientFuture.

It's exposed in the Connect impl of FutureService -- the tradeoff for not generating *another* item -- and hiding it breaks doc links.

* Formatting

* Rename snake_to_camel plugin => tarpc-plugins

* Update README

* Mangle a lot of names in macro expansion.

To lower the chance of any issues, prefix idents in service expansion with __tarpc_service.
In future_enum, prefix with __future_enum. The pattern is basically __macro_name_ident.

Any imported enum variant will conflict with a let binding or a function arg, so we basically
can't use any generic idents at all. Example:

    enum Req { request(..) }
    use self::Req::request;

    fn make_request(request: Request) { ... }

                    ^^^^^^^ conflict here

Additionally, suffix generated associated types with Fut to avoid conflicts with camelcased rpcs.
Why someone would do that, I don't know, but we shouldn't allow that wart.

src/protocol/reader.rs

@@ -5,39 +5,12 @@
 
 use byteorder::{BigEndian, ReadBytesExt};
 use bytes::{MutBuf, Take};
-use std::io::{self, Read};
+use futures::Async;
+use std::io;
 use std::mem;
-use super::MapNonBlock;
+use tokio_proto::TryRead;
 use tokio_proto::pipeline::Frame;
-
-pub trait TryRead {
-    fn try_read_buf<B: MutBuf>(&mut self, buf: &mut B) -> io::Result<Option<usize>>
-        where Self: Sized
-    {
-        // Reads the length of the slice supplied by buf.mut_bytes into the buffer
-        // This is not guaranteed to consume an entire datagram or segment.
-        // If your protocol is msg based (instead of continuous stream) you should
-        // ensure that your buffer is large enough to hold an entire segment
-        // (1532 bytes if not jumbo frames)
-        let res = self.try_read(unsafe { buf.mut_bytes() });
-
-        if let Ok(Some(cnt)) = res {
-            unsafe {
-                buf.advance(cnt);
-            }
-        }
-
-        res
-    }
-
-    fn try_read(&mut self, buf: &mut [u8]) -> io::Result<Option<usize>>;
-}
-
-impl<T: Read> TryRead for T {
-    fn try_read(&mut self, dst: &mut [u8]) -> io::Result<Option<usize>> {
-        self.read(dst).map_non_block()
-    }
-}
+use util::Never;
 
 #[derive(Debug)]
 pub struct U64Reader {
@@ -74,7 +47,7 @@ enum NextReadAction<R> {
     Stop(Result<R, io::Error>),
 }
 
-trait MutBufExt: MutBuf {
+trait MutBufExt: MutBuf + Sized {
     type Inner;
 
     fn take(&mut self) -> Self::Inner;
@@ -138,7 +111,7 @@ impl ReadState {
 
     pub fn next<R: TryRead>(&mut self,
                             socket: &mut R)
-                            -> io::Result<Option<Frame<Vec<u8>, io::Error>>> {
+                            -> io::Result<Async<Frame<Vec<u8>, Never, io::Error>>> {
         loop {
             let next = match *self {
                 ReadState::Len(ref mut len) => {
@@ -151,7 +124,7 @@ impl ReadState {
                                     NextReadState::Next(ReadState::Data(Take::new(buf,
                                                                                   len as usize)))
                                 }
-                                Err(e) => return Ok(Some(Frame::Error(e))),
+                                Err(e) => return Ok(Async::Ready(Frame::Error(e))),
                             }
                         }
                     }
@@ -162,18 +135,18 @@ impl ReadState {
                         NextReadAction::Stop(result) => {
                             match result {
                                 Ok(buf) => NextReadState::Reset(buf),
-                                Err(e) => return Ok(Some(Frame::Error(e))),
+                                Err(e) => return Ok(Async::Ready(Frame::Error(e))),
                             }
                         }
                     }
                 }
             };
             match next {
-                NextReadState::Same => return Ok(None),
+                NextReadState::Same => return Ok(Async::NotReady),
                 NextReadState::Next(next) => *self = next,
                 NextReadState::Reset(packet) => {
                     *self = ReadState::init();
-                    return Ok(Some(Frame::Message(packet)));
+                    return Ok(Async::Ready(Frame::Message(packet)));
                 }
             }
         }