From 28da4dbf56c64af9ffc9ff9ee0a2aeeef99cc51e Mon Sep 17 00:00:00 2001 From: Joonatan Saarhelo Date: Sat, 18 Jan 2020 17:18:37 +0200 Subject: [PATCH] improve documentation of BincodeRead --- src/de/read.rs | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/src/de/read.rs b/src/de/read.rs index ffc5ae2..33313c0 100644 --- a/src/de/read.rs +++ b/src/de/read.rs @@ -6,16 +6,21 @@ use std::{io, slice}; /// /// It is highly recommended to use bincode with `io::Read` or `&[u8]` before /// implementing a custom `BincodeRead`. +/// +/// The forward_read_* methods are necessary because some byte sources want +/// to pass a long-lived borrow to the visitor and others want to pass a +/// transient slice. pub trait BincodeRead<'storage>: io::Read { - /// Forwards reading `length` bytes of a string on to the serde reader. + /// Check that the next `length` bytes are a valid string and pass + /// it on to the serde reader. fn forward_read_str(&mut self, length: usize, visitor: V) -> Result where V: serde::de::Visitor<'storage>; - /// Return the first `length` bytes of the internal byte buffer. + /// Transfer ownership of the next `length` bytes to the caller. fn get_byte_buffer(&mut self, length: usize) -> Result>; - /// Forwards reading `length` bytes on to the serde reader. + /// Pass a slice of the next `length` bytes on to the serde reader. fn forward_read_bytes(&mut self, length: usize, visitor: V) -> Result where V: serde::de::Visitor<'storage>;