Suggestion: `BufMut::advance_mut` should make `cnt > self.remaining_mut()` unsound

[paolobarbolini]

The current documentation for BufMut::advance_mut suggests that the implementation should handle cases where cnt > self.remaining_mut(). However, since this function is already unsafe and requires the caller to ensure that the declared length has been properly initialized, it seems contradictory to also suggest the implementation handle out-of-bounds lengths.
This requirement was added in #70, and did not exist before. It looks like an artifact of the pre-MaybeUninit days.

The suggestion should instead be to add debug_assert! to catch obviously unsound implementations while avoiding unnecessary runtime overhead in release builds.

[Darksonn]

I'm not convinced this is possible due to the semver hack. Bytes v1 will re-export bytes_v2::BufMut, so we cannot make any change we want to due to backwards compat.

[Kixunil]

I agree it's impossible but I also agree that an already unsafe function required to handle invalid inputs is unfortunate.

[paolobarbolini]

I'm not convinced this is possible due to the semver hack. Bytes v1 will re-export bytes_v2::BufMut, so we cannot make any change we want to due to backwards compat.

Could we change the docs to say something along the lines of:

• Implementors: keep doing what you're doing
• Callers: assume it's unsound to have cnt > self.remaining_mut()

[Kixunil]

That would be a nice way to transition into it becoming unsound at some point (with breaking change).