Polish the API docs

[seanmonstar]

This is issue about what appears at https://docs.rs/hyper. As a general rule, we should incrementally improve them with the following in mind:

• Types should have a description of what they are used for, not just a repeat of the type name.
• Methods should almost always include a code example.
• Modules should explain concepts of what its types are meant to be used for, and how to combine those types with others.
• If a question comes up more than once from a user, it should be somewhere in the API docs.
  • If it is there, and people still ask, it's probably in the wrong place, or not written clearly.

Items to document

• lib 👀
• body
  • Document body module: Reference http-body-util #3299
  • doc(body:incoming): reference http-body-incoming for more explain #3383
• client
  • module: for the example, also link to the client guide.
  • conn: 👀
• ext
  • module: explain that the types in here go in request or response extensions
  • struct Protocol: explain that it is for http/2, what it does, that it must be used with associated builder options, show example
  • struct ReasonPhrase
• ffi: add unstable tag
• rt
  • module: better overview, subsections explaining executors, timers, and IO
• server
  • conn module: mention hyper-util providing an AutoConnection and builder
  • conn::http1 module: provide an overview, and a getting started section
  • struct conn::http1::Builder: Provide an example constructing one and setting some options.
  • struct conn::http1::Connection: Explain that this is returned from Builder::serve_connection, and that it is essential an impl Future that must be polled (or awaited) for anything to happen.
  • conn::http2 module: provide an overview, and a getting started section
• service 👀
• upgrade 👀

[A248]

Hi, maybe it would be useful to mention the repository https://github.com/hyperium/hyperium.github.io, for the sake of future contributors who come to this issue looking to contribute to the documentation.

[seanmonstar]

@A248 Ah, what I meant by "API docs" is those that are within the source code here, that get rendered at docs.rs/hyper. The website repository is the subject of #3068.

[seanmonstar]

I'm going through the currently rendered docs (of rc4) and writing down some notes in the top comment about what needs to be improved. By making them separate items in a task list, it should be easy to convert any single one into an issue. If you'd like to fix any, start a pull request mentioning it, and I'll click the button to convert the task into an issue.

An item tagged with 👀 means I haven't yet analyzed the module or its types.