Add VolatileRef::borrow and VolatileRef::borrow_mut

[mkroening]

These methods are useful when you want to borrow a VolatileRef but want to avoid the additional indirection and lifetime of &mut VolatileRef<'a, T> by creating a VolatileRef<'_, T> instead.

borrow and borrow_mut mirror as_ptr and as_mut_ptr respectively, but yield volatile references instead of pointers.

[phil-opp]

Thanks for the PR! These methods are definitely useful.

Maybe reborrow is a better name? I think the name borrow is associated with creating a & or &mut reference already. Also, there is the core::borrow::Borrow trait that returns a &Borrowed reference too.

Also, could you add a note to the docs that the methods create a VolatileRef with a shorter lifetime? Just to make it clearer how the methods differ from the identity function and why they are useful.

[mkroening]

Maybe reborrow is a better name? I think the name borrow is associated with creating a & or &mut reference already. Also, there is the core::borrow::Borrow trait that returns a &Borrowed reference too.

I intentionally drew parallels to core::borrow::Borrow here. Implementations of Borrow for &T and &mut T, as well as the implementation of BorrowMut for &mut T do exactly the kind of reborrowing, that we are doing here. The only reason, I could not implement the trait instead, is that the trait returns &T and &mut T respectively. Since VolatileRef<'_, T> is just another reference type, I think the current names are quite fitting.

If you disagree, I can change the name, though.

Edit: I think this is similar to how we use as_ptr and as_mut_ptr to refer to VolatilePtr instead of *.

Also, could you add a note to the docs that the methods create a VolatileRef with a shorter lifetime? Just to make it clearer how the methods differ from the identity function and why they are useful.

I amended the commit, although I think it can still be improved. I struggle with making this concise but also not too confusing.

[phil-opp]

Thanks for the doc updates, looks good!

Good point about the Borrow impl for &T, this is indeed quite similar, given that we're also providing a reference-like type. Let's keep the names then!