From 99fba239db1962e8c039d3255e4e5417aef283ba Mon Sep 17 00:00:00 2001 From: Carl Lerche Date: Thu, 16 Mar 2017 12:11:10 -0700 Subject: Tweak docs (#76) --- src/buf/buf.rs | 3 ++- src/bytes.rs | 16 +++++++++++++++- 2 files changed, 17 insertions(+), 2 deletions(-) (limited to 'src') diff --git a/src/buf/buf.rs b/src/buf/buf.rs index 7b26904..42280e7 100644 --- a/src/buf/buf.rs +++ b/src/buf/buf.rs @@ -9,7 +9,8 @@ use std::{cmp, io, ptr}; /// A buffer stores bytes in memory such that read operations are infallible. /// The underlying storage may or may not be in contiguous memory. A `Buf` value /// is a cursor into the buffer. Reading from `Buf` advances the cursor -/// position. +/// position. It can be thought of as an efficient `Iterator` for collections of +/// bytes. /// /// The simplest `Buf` is a `Cursor` wrapping a `[u8]`. /// diff --git a/src/bytes.rs b/src/bytes.rs index 097487f..954c310 100644 --- a/src/bytes.rs +++ b/src/bytes.rs @@ -107,10 +107,24 @@ pub struct Bytes { /// /// `BytesMut` represents a unique view into a potentially shared memory region. /// Given the uniqueness guarantee, owners of `BytesMut` handles are able to -/// mutate the memory. +/// mutate the memory. It is similar to a `Vec` but with less copies and +/// allocations. /// /// For more detail, see [Bytes](struct.Bytes.html). /// +/// # Growth +/// +/// One key difference from `Vec` is that most operations **do not +/// implicitly grow the buffer**. This means that calling `my_bytes.put("hello +/// world");` could panic if `my_bytes` does not have enough capacity. Before +/// writing to the buffer, ensure that there is enough remaining capacity by +/// calling `my_bytes.remaining_mut()`. In general, avoiding calls to `reserve` +/// is preferable. +/// +/// The only exception is `extend` which implicitly reserves required capacity. +/// +/// # Examples +/// /// ``` /// use bytes::{BytesMut, BufMut}; /// -- cgit v1.2.3