IO with Tokio Suggestions

[goriunov]

I have went through the sections in io with tokio and it looks really good. There are few things which i found slightly hard to track for new comers.

1. In the first section tokio io overview we have an example which implements socket.split(); and copy combinators and later on we get an explanation of that things but i think it would be great if i could see the same example but without using any combinators and directly use AsyncRead and AsyncWrite this will give a better overview for split and copy and how it works.

2. Shutdown documentation link from Using AsyncRead and AsyncWrite directly is wrong and would be good to have some example how to use it in the docs as well.

3. Some examples are incomplete ex:Transports as i can not just copy and past code and play with that around. As it will not run without main function and for someone who is new to the tokio it will be a bit hard to complete code for LinesCodec to run it properly. (it is also related to other examples)

Thank you very much for your work :)

[carllerche]

cc @jonhoo

[jonhoo]

I'm on my way out the door, and may not be able to get to this until after the weekend, but some brief thoughts:

• First, thanks for the feedback! This is how we make documentation great!
• I completely agree with you that it's unfortunate that the first example uses stuff we haven't introduced yet. I don't quite know what the example should be though (maybe there shouldn't be one). Arguably, the example that's currently in the overview should be moved wholesale to after we've talked about combinators and splitting to show how they're used together.
• Yeah, shutdown is a little weird. @carllerche maybe you have a concrete example in mind there?
• Ah, yes, I suppose we should amend the example given to have a tiny main that actually uses the LinesCodec! This seems like a good separate issue we could track and mark with good-first-issue :D