Fixed incorrect usage of 'Borrowing'.

[brian-dawn]

To keep consistency with the word "borrowing" I suppose an alternate way to write this could be "Having an object borrow an immutable pointer freezes it and prevents mutation".

[emberian]

I don't think it was incorrect. The borrow/loan metaphor has it that you create a loan by borrowing. The borrowed object has no say in the matter. I think the current phrasing is fine.

[brian-dawn]

By incorrect usage I mean that in English you cannot "borrow to" someone, you "borrow from" and "lend to". When I read these docs my brain inserted "from" and ignored that it said "to" because I had read "borrowing" which led to confusion.

[huonw]

... I feel like this is incorrect. The action of borrowing a pointer to an object is external (i.e. &x is going to the object x and borrowing a reference, where as lending would be something like x.lend_reference(|ptr| { /* use ptr */ })).

[huonw]

I guess changing it to "Borrowing an immutable reference from an object" would be ok, but I don't think that quite captures the behaviour like "borrowing an immutable reference to an object" does. I think the confusion here is because the "to" is attached to the "pointer", i.e. it is what the pointer points to, not associated with the word "borrowing".

One could even phrase it as "Borrowing an immutable reference (which points to some object) freezes that object".

[huonw]

To put it another way, with the lending wording, it sounds like the immutable reference is being placed in some object, and somehow that makes that object immutable, which is false. Specifically, it makes it sound like the following is the behaviour of &:

struct Foo<'self> { x: Option<&'self int> }

let mut x = 1;
let mut y = Foo { x: None };
y.x = Some(&x); // `y` is frozen, but `x` isn't.

whereas the opposite is true, only x is frozen in the above code.

[brian-dawn]

I didn't mean to start a big discussion on this matter, but if someone was confused by the language of the tutorial (like the "to" being attached to the pointer, which I'm still not sure I understand) wouldn't that imply that maybe the language was wrong?

I don't know Rust well enough to ascertain what the best method of saying it is, but I still feel like "borrowing [...] to" is not very obvious, nor is it correct English. What does it mean? "lending to" or "borrowing from" because it feels like there is a mistake there, and as a newbie I had to try to decode what it meant grammatically. Documentation should never have to be interpreted in such a way.

I guess I am confused why "lending" implies anything different than "borrowing" considering they mean the same thing you just choose one based on the direction, to vs from. If I am misunderstanding my apologies.

[huonw]

I agree 100% that it should be changed; I just don't think this change is correct, especially since it makes it more confusing about what exactly is getting frozen (is the the place that is storing the reference, or the thing that the reference points to?).

Maybe it could be changed to "If one takes an immutable reference to an object, then that object is frozen and mutation is prevented." which removes the lending/borrowing confusion.