docs: clarify the behavior of Buf::chunk (#717)

src/buf/buf_impl.rs

@@ -141,9 +141,11 @@ pub trait Buf {
     ///
     /// # Implementer notes
     ///
-    /// This function should never panic. Once the end of the buffer is reached,
+    /// This function should never panic. `chunk()` should return an empty
-    /// i.e., `Buf::remaining` returns 0, calls to `chunk()` should return an
+    /// slice **if and only if** `remaining()` returns 0. In other words,
-    /// empty slice.
+    /// `chunk()` returning an empty slice implies that `remaining()` will
+    /// return 0 and `remaining()` returning 0 implies that `chunk()` will
+    /// return an empty slice.
     // The `chunk` method was previously called `bytes`. This alias makes the rename
     // more easily discoverable.
     #[cfg_attr(docsrs, doc(alias = "bytes"))]

src/buf/buf_mut.rs

@@ -165,7 +165,7 @@ pub unsafe trait BufMut {
     ///
     /// # Implementer notes
     ///
-    /// This function should never panic. `chunk_mut` should return an empty
+    /// This function should never panic. `chunk_mut()` should return an empty
     /// slice **if and only if** `remaining_mut()` returns 0. In other words,
     /// `chunk_mut()` returning an empty slice implies that `remaining_mut()` will
     /// return 0 and `remaining_mut()` returning 0 implies that `chunk_mut()` will