Re: [PATCH v1] rust: add improved version of `ForeignOwnable::borrow_mut`

[Alice Ryhl <aliceryhl@google.com>]

Andreas Hindborg <nmi@metaspace.dk> writes:
>> +    /// Borrows a foreign-owned object mutably.
>> +    ///
>> +    /// This method provides a way to access a foreign-owned value from Rust mutably. It provides
>> +    /// you with exactly the same abilities as an `&mut Self` when the value is Rust-owned, except
>> +    /// that this method does not let you swap the foreign-owned object for another. (That is, it
>> +    /// does not let you change the address of the void pointer that the foreign code is storing.)
> 
> How about this:
> 
> "For a smart pointer P<T> this method provides mutable access to T if
> &mut P<T> would allow mutable access to T. Otherwise it provides
> immutable access to T."
> 
> The point is that the method provides access to the pointee, not the
> smart pointer itself. In fact it is perfectly fine to do a mem::swawp()
> for the pointee in the case of Box and depending on interpretation the
> sentence "does not let you swap the foreign-owned object for another" is
> confusing.

Yeah, I agree that the phrasing is somewhat confusing.

How about this:

/// This method provides a way to access a foreign-owned value from Rust mutably. It provides
/// you with exactly the same abilities as an `&mut Self` when the value is Rust-owned, except
/// that the address of the object must not be changed.
///
/// Note that for types like [`Arc`], an `&mut Arc<T>` only gives you immutable access to the
/// inner value, so this method also only provides immutable access in that case.
///
/// In the case of `Box<T>`, this method gives you the ability to modify the inner `T`, but it
/// does not let you change the box itself. That is, you cannot change which allocation the box
/// points at.

Alice