Use third form in method's docs + small code refactoring

[olegnn]

Use third person form in method's docs everywhere. Added some missing comments. Small refactoring. Other docs fixes.

[carllerche]

Thanks. This is a great change. I skimmed and the goal of the doc changes is good.

It would be easier to get this PR merged if the code changes are submitted in a separate PR. I didn't look at all of them yet (ran out of time), but I found one (BytesCodec(())) where the private field exists explicitly to support adding fields in the future w/o a breaking change.

Anyway, if you are able to split out the code changes separately, that would make things easier. Otherwise, I will try to review more later.

[olegnn]

@carllerche I fixed breaking changes.
Could you take a look? Otherwise I will close this PR because it gets more and more conflicts with master.

[dekellum]

I would certainly agree that consistency for the tokio project is helpful, but if you don't mind me (an interested 3rd party) asking: what's the rationale for 3rd person form?

I personally favor 1st person as in:

/// Return `Bar` if available.
fn foo() -> Option<Bar>;

One could interpret the sentence as in:

I (the fn foo!) return Bar if available

Maybe that is too colloquial or folksy for some? I favor brevity in this regard, I think.

Edit: And as proof of my preference: #2129 (which might also conflict with this):

https://docs.rs/tokio/0.2.10/tokio/task/fn.yield_now.html

[carllerche]

Sorry for the delay. Let me look again. I'll deal w/w conflicts

[carllerche]

Thanks for sticking with this 👍 I reverted the code changes even if they were purely stylistic. With a doc PR of this size, it makes it much easier to split up code changes from docs. If you wish to open a PR w/ the code changes, we can work on that next 👍