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
  • [x] #3299
  • [x] #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
  • [x] struct ReasonPhrase
• [x] ffi: add unstable tag
• [ ] rt
  • [ ] module: better overview, subsections explaining executors, timers, and IO
• [ ] server
  • [x] conn module: mention hyper-util providing an AutoConnection and builder
  • [ ] conn::http1 module: provide an overview, and a getting started section
  • [x] struct conn::http1::Builder: Provide an example constructing one and setting some options.
  • [x] 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.