Book: Understanding what is written

[lehtoj]

There is only so much you can do to make what you write understandable to people coming from various backgrounds, and not all of them speak English as native. I however do consider myself having above average reading comprehension, but there are still things in the book that throw me completely off.

Below is a quote from chapter 15.2.

Deref coercion converts a reference to a type that implements Deref into a reference to a type that Deref can convert the original type into.

When I stumbled upon that particular sentence this morning, if I had been carrying the physical book, the book would've gone flying out of sheer frustration. There are however many such occurrences throughout the book, this is not an isolated case.

I vented a bit on #rust-beginners, and svartalf gave me this. I thought this is a very good example of the common pitfall of how programming books are written.

How can we improve the Rust book to make it overall easier to comprehend?

[carols10cents]

Hi! I'm sorry the book has you frustrated. It's really tricky to phrase complex technical ideas in English. If I knew of better ways, I would have used them!

Do you have any specific suggestions on how to improve this sentence?

If you can point out the other places that were frustrating, that would be helpful as well. It's really hard to know what other people find incomprehensible after I've read it a million times through and it all sounds fine to me, so we need help from fresh eyes. Thanks!

[andywswan]

I would have gladly helped with a translation of this phrase to the common tong if only I understood it.

[carols10cents]

What parts are most confusing? Could someone lay out what the possible interpretations of this sentence are that you've considered, so that I can understand better where disambiguation is needed?

[L0uisc]

"Deref coercion converts a reference referencing a type that implements Deref into a reference to a type that Deref can convert the original type into." ?

It might be understood as "Deref coercion converts [a reference -- object] to a type that implements Deref (did the reference get converted into a type that implements Deref? "To" and "into" are very similar for non-native speakers sometimes.) into (Oh no! The sentence goes on! What is "into" doing here? I'm lost) ..."

[carols10cents]

[a reference -- object]

I'm not sure what you're saying here, are you saying "a reference is an object" or "a reference to an object" or something else?

I'm starting to think adding an example at this point might help. Would the sentence this issue is about make sense if it was followed with the sentence below?

For example, deref coercion can convert &String to &str because String implements the Deref trait such that it returns str.

[eddyp]

How about this?

Deref coercion works only on types which implement the Deref trait. Deref coertion converts such a type into a reference to an another type that Deref can convert back into the original type.

Even after writing this I am unsure this is the intended meaning. If it is, then the recursive definition is what is causing part of the confusion.

@lehtoj @andywswan @L0uisc does this wording sound better?

@carols10cents is this wording accurate from a technical PoV?

[sd234678]

@carols10cents I think the example seems helpful in clarifying the sentence. I'm a native English speaker but the sentence given does take a moment to get one's head around and I think the example helps to increase the speed at which that happens.

@eddyp I like the splitting off of the first sentence in your revision but surely to then convert it back it wouldn't be the Deref trait doing the work. Unless you meant the dereferenced type by "original type" but then that's another ambiguity introduced.

[L0uisc]

I'm not sure what you're saying here, are you saying "a reference is an object" or "a reference to an object" or something else?

Sorry for replying so late. I meant object in the English grammar sense, not the programming sense. Is it a reference that gets converted into a type which implements Deref or is it a reference to a type implementing Deref which gets converted into another type? That is the confusion as I understand it. The pronouns "to" and "into" are often confused by non-native speakers.

[L0uisc]

I think this could possibly work:

Deref coercion works only on types which implement the Deref trait. Deref coercion converts such a type into a reference to another type. For example, deref coercion can convert &String to &str because String implements the Deref trait such that it returns str.

[eddyp]

@L0uisc now I even understood it, yay!