Add documentation to more From::from implementations.

[kpreid]

For users looking at documentation through IDE popups, this gives them relevant information rather than the generic trait documentation wording “Performs the conversion”. For users reading the documentation for a specific type for any reason, this informs them when the conversion may allocate or copy significant memory versus when it is always a move or cheap copy.

Notes on specific cases:

• The new documentation for From<T> for T explains that it is not a conversion at all.
• Also documented impl<T, U> Into<U> for T where U: From<T>, the other central blanket implementation of conversion.
• The new documentation for construction of maps and sets from arrays of keys mentions the handling of duplicates. Future work could be to do this for all code paths that convert an iterable to a map or set.
• I did not add documentation to conversions of a specific error type to a more general error type.
• I did not add documentation to unstable code.

This change was prepared by searching for the text "From<... for" and so may have missed some cases that for whatever reason did not match. I also looked for Into impls but did not find any worth documenting by the above criteria.

[rust-highfive]

r? @Mark-Simulacrum

(rust-highfive has picked a reviewer for you, use r? to override)

[kpreid]

The above test failure appears to be due to renaming the parameter of <T as From<T>>::from from t to value, which is not at all a necessary part of this change. Pushed a version that doesn't do that.

[Mark-Simulacrum]

Hm. I I seem to recall a thread a while back discussing what we want out of the documentation comments on impls like this. I personally don't know that repeating the signature of the impl pretty much directly in the documentation is helpful to those reading it; if editors are able to show that documentation line it seems like they could be convinced to show the signature of the method (which I would guess is more useful, particularly for mostly trivial functions like this). Maybe we should have some policy work in this area so that we can better guide PRs like this -- I certainly have opinions, but it feels like individual PRs being approved/rejected based on the particular reviewer is not a great experience.

This PR also adds the new documented constraint for deduplicating keys for the Set/Map From impls which seem pretty obviously like what we'd want to do, but I'd like at least one member of T-libs-api to weigh in there.

r? @dtolnay

[kpreid]

Hm. I I seem to recall a thread a while back discussing what we want out of the documentation comments on impls like this. I personally don't know that repeating the signature of the impl pretty much directly in the documentation is helpful to those reading it; if editors are able to show that documentation line it seems like they could be convinced to show the signature of the method (which I would guess is more useful, particularly for mostly trivial functions like this). Maybe we should have some policy work in this area so that we can better guide PRs like this -- I certainly have opinions, but it feels like individual PRs being approved/rejected based on the particular reviewer is not a great experience.

For what it's worth, I agree that repeating the signature in the documentation by itself is not especially useful. However,

1. I think it can be useful to have that sentence as a foundation on which to build commentary on further properties, such as whether the conversion does or does not (re)allocate. And even a trivial sentence can communicate “There's nothing more to say than this” instead of “This is undocumented”.
2. Almost all of the From impls which already have documentation do have such wording, if I remember correctly.

This PR also adds the new documented constraint for deduplicating keys for the Set/Map From impls which seem pretty obviously like what we'd want to do, but I'd like at least one member of T-libs-api to weigh in there.

I believe this has been previously discussed in the context of new conversions to maps/sets, with the general consensus being “it would definitely be a breaking change to do anything else, and consistency is good”.

Personally, I'm not a fan of silently discarding data, particularly since From is generally talked about as being a non-lossy conversion (though its documentation doesn't say that!), and I mentioned the deduplication behavior in this change because it's exactly the sort of information that I think From impls should have to enable users to be well-informed about what their code actually does, in terms of edge cases and side effects.

[bors]

☔ The latest upstream changes (presumably #90067) made this pull request unmergeable. Please resolve the merge conflicts.

[dtolnay]

Could you please pull the BTreeMap and BTreeSet documentation about the behavior on duplicates out to a separate PR? I'll bring that up with T-libs-api. I agree with Mark it's likely this is the behavior we want to commit to but I don't think I can do that unilaterally.

For the rest, I'll bump this over to T-libs to work out whether the cost/benefit of maintaining this kind of documentation is the right tradeoff for them.

Thanks!

[kpreid]

I have removed the wording about duplicate items.

[yaahc]

Looks good, thank you again for the help!

@bors r+ rollup

[bors]

📌 Commit 6fd5cf5 has been approved by yaahc