From e64a123d002e56626580cb51ae7e729e6574ce59 Mon Sep 17 00:00:00 2001
From: Michal 'vorner' Vaner <vorner+github@vorner.cz>
Date: Sat, 17 Nov 2018 16:51:28 +0100
Subject: [PATCH] Bring more attention to short reads/slices on Buff/BuffMut
 (#231)

The property the Buff and BuffMut can return shorter slice is quite an
important detail. Nevertheless, while it is mentioned in the
documentation, the wording makes it relatively easy to overlook. This
tries to bring more attention to it.
---
 src/buf/buf.rs     | 3 ++-
 src/buf/buf_mut.rs | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/buf/buf.rs b/src/buf/buf.rs
index b72c8d9..dc20567 100644
--- a/src/buf/buf.rs
+++ b/src/buf/buf.rs
@@ -91,7 +91,8 @@ pub trait Buf {
     fn remaining(&self) -> usize;
 
     /// Returns a slice starting at the current position and of length between 0
-    /// and `Buf::remaining()`.
+    /// and `Buf::remaining()`. Note that this *can* return shorter slice (this allows
+    /// non-continuous internal representation).
     ///
     /// This is a lower level function. Most operations are done with other
     /// functions.
diff --git a/src/buf/buf_mut.rs b/src/buf/buf_mut.rs
index 71dbda9..7f3c1f7 100644
--- a/src/buf/buf_mut.rs
+++ b/src/buf/buf_mut.rs
@@ -121,7 +121,8 @@ pub trait BufMut {
     }
 
     /// Returns a mutable slice starting at the current BufMut position and of
-    /// length between 0 and `BufMut::remaining_mut()`.
+    /// length between 0 and `BufMut::remaining_mut()`. Note that this *can* be shorter than the
+    /// whole remainder of the buffer (this allows non-continuous implementation).
     ///
     /// This is a lower level function. Most operations are done with other
     /// functions.