Improve documentation for constructors of pinned Boxes

[steffahn]

Adds a cross-references between Box::pin and Box::into_pin (and other related methods, i.e. the equivalent From implementation, and the unstable pin_in method), in particular now that into_pin was stabilized. The main goal is to further improve visibility of the fact that Box<T> -> Pin<Box<T>> conversion exits in the first place, and that Box::pin(x) is – essentially – just a convenience function for Box::into_pin(Box::new(x))

The motivating context why I think this is important is even experienced Rust users overlooking the existence this kind of conversion, e.g. in this thread on IRLO; and also the fact that that discussion brought up that there would be a bunch of Box-construction methods "missing" such as e.g. methods with fallible allocation a la "Box::try_pin", and similar; while those are in fact not necessary, because you can use Box::into_pin(Box::try_new(x)?) instead.

I have not included explicit mention of methods (e.g. try_new) in the docs of stable methods (e.g. into_pin). (Referring to unstable API in stable API docs would be bad style IMO.) Stable examples I have in mind with the statement "constructing a (pinned) Box in a different way than with Box::new" are things like cloning a Box, or Box::from_raw. If/when try_new would get stabilized, it would become a very good concrete example use-case of Box::into_pin IMO.

[rust-highfive]

Hey! It looks like you've submitted a new PR for the library teams!

If this PR contains changes to any rust-lang/rust public library APIs then please comment with r? rust-lang/libs-api @rustbot label +T-libs-api -T-libs to request review from a libs-api team reviewer. If you're unsure where your change falls no worries, just leave it as is and the reviewer will take a look and make a decision to forward on if necessary.

Examples of T-libs-api changes:

• Stabilizing library features
• Introducing insta-stable changes such as new implementations of existing stable traits on existing stable types
• Introducing new or changing existing unstable library APIs (excluding permanently unstable features / features without a tracking issue)
• Changing public documentation in ways that create new stability guarantees
• Changing observable runtime behavior of library APIs

[rust-highfive]

r? @thomcc

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

[thomcc]

@bors r+ rollup

[bors]

📌 Commit 6e2ac5d has been approved by thomcc