Document `hyper::body` module with how to use different body types

[IsaacCloos]

🙋🏻‍♂️

If this issue is available, I'd love to draft a solution.

---

Browsing through the body module I compiled this list of todos. Of course, please add more as you see fit:

• [ ] Extend module overview with "top-level" perspective of available body types https://github.com/hyperium/hyper/blob/d894439e009aa75103f6382a7ba98fb17da72f02/src/body/mod.rs#L1-L15

• [ ] Quality doc comments with clear definitions and informative examples https://github.com/hyperium/hyper/blob/d894439e009aa75103f6382a7ba98fb17da72f02/src/body/incoming.rs#L25-L43

• [ ] Get Incoming doc-comment-quality on par with Sender https://github.com/hyperium/hyper/blob/d894439e009aa75103f6382a7ba98fb17da72f02/src/body/incoming.rs#L19-L23 https://github.com/hyperium/hyper/blob/d894439e009aa75103f6382a7ba98fb17da72f02/src/body/incoming.rs#L45-L63

• [X] ~Extend coverage to these Sender pieces~ https://github.com/hyperium/hyper/blob/d894439e009aa75103f6382a7ba98fb17da72f02/src/body/incoming.rs#L16-L17

---

I see that Incoming's body / self implementations are sparse on documentation. Is there interest in spreading coverage there as well?

[seanmonstar]

This looks right to me! Though, the Sender type is now 100% internal, so it's documentation doesn't need to be changed much. I expect some sort of similar channel type will exist in hyper-util, but that's a separate ticket.

Extend module overview with "top-level" perspective of available body types

Yea, I'd probably link to the http-body-util crate as a "read more", and provide a brief overview here about the "kinds" of bodies that could exist (and likely already do in the util crate).

[IsaacCloos]

I'm marinating a draft for this right now, and a few more questions have come to me:

1. Can the scope of this ticket be updated to include documenting the Body implementing structs in http-body-util? I wish I had really given thought to the full user experience before ascertaining the possibilities of this issue above. ~Forget all that!~ I think some real good can come from adding documentation (desc, example, panics, notes) to prefabs like Full, StreamBody, Limited ext.

Yea, I'd probably link to the http-body-util crate as a "read more", and provide a brief overview here about the "kinds" of bodies that could exist (and likely already do in the util crate).

In my honest opinion, sending them over would still leave them wanting more information right now. I'd like to start working in that direction, but want to stay within the parameters of the ticket.

2. http-body-util is loaded with body "types" that cover a good chunk of usages that the average hyper user would need. I have an instinct to reach into hyper to find these "default profiles" (if you will), but of course they are relegated to a utility crate. For my education, why does hyper not re-export these types if, for example, the server feature is enabled?

aside: bytes and http-body are re-exported tastefully:

https://github.com/hyperium/hyper/blob/8552543fd29d5bdbce4c7bad352f35a16a9b1ab8/src/body/mod.rs#L17-L20

3. Finally! Are there any specific body types you'd like to see mentioned and/or demonstrated that AREN'T covered in the util? I'm just trying to get all my ducks in a row, and make sure I'm nailing the issue criteria.

Thanks again for your time, and sorry for the question barrage 😅

[seanmonstar]

I have an instinct to reach into hyper to find these "default profiles" (if you will), but of course they are relegated to a utility crate. For my education, why does hyper not re-export these types if, for example, the server feature is enabled?

The primary reason is to disconnect their stability from hyper's stability. For instance, if we wanted to change whether Full had a different default error type, we wouldn't want that to require hyper 2.0.

Are there any specific body types you'd like to see mentioned and/or demonstrated that AREN'T covered in the util?

Probably eventually. For instance, see #2858 of something that would be nice to have, but we aren't blocking 1.0 on having it.