mirror of
https://github.com/rust-lang/rust.git
synced 2026-05-17 05:25:37 +03:00
kennytm
f32f810e6e
Improve documentation for Borrow This is the first step in improving the documentation for all the reference conversion traits. It proposes new text for the trait documentation of `Borrow`. Since I feel it is a somewhat radical rewrite and includes a stricter contract for `Borrow` then the previous text—namely that *all* shared traits need to behave the same, not just a select few—, I wanted to get some feedback before continuing. Apart from the ‘normative’ description, the new text also includes a fairly extensive explanation of how the trait is used in the examples section. I included it because every time I look at how `HashMap` uses the trait, I need to think for a while as the use is a bit twisted. So, I thought having this thinking written down as part of the trait itself might be useful. One could argue that this should go into The Book, and, while I really like having everything important in the docs, I can see the text moved there, too. So, before I move on: is this new text any good? Do we feel it is correct, useful, comprehensive, and understandable? (This PR is in response to #44868 and #24140.)