tokio-rs / bytes

Utilities for working with bytes
MIT License
1.86k stars 278 forks source link

Confusing documentation around `Arc<[u8]>` compatibility #685

Open BTOdell opened 5 months ago

BTOdell commented 5 months ago

The latest documentation of the crate reads:

For Bytes implementations which point to a reference counted shared storage (e.g. an Arc<[u8]>),
sharing will be implemented by increasing the reference count.

Reference: https://docs.rs/bytes/latest/bytes/struct.Bytes.html#sharing

This lead me to assume that Bytes should provide a from conversion function from an Arc<[u8]> to a Bytes instance where the backing storage is an Arc. However, it doesn't appear that this from function exists.

I don't think it's a good idea for documentation to reference imaginary scenarios that aren't implemented by the library as it sets up false expectations with regard to how the library works and what features it provides.

Sytten commented 4 months ago

It in fact quite useful, but it should do a better job at being compatible