Fix #2612: adjust readable trait to allow try_peek (#2714)

* Fix #2612: adjust readable trait to allow try_peek

Our implementation for Readable was inconsistent.
We had a try_unchecked variant for read but not for peek.
This resolves that by making a breaking change to the
Readable interface.

* fix doctests too

packages/generational-box/src/error.rs

@@ -4,6 +4,9 @@ use std::fmt::Display;
 
 use crate::GenerationalLocation;
 
+/// A result that can be returned from a borrow operation.
+pub type BorrowResult<T> = std::result::Result<T, BorrowError>;
+
 #[derive(Debug, Clone, PartialEq)]
 /// An error that can occur when trying to borrow a value.
 pub enum BorrowError {