Improve documentation for constructors of pinned Boxes
#97655
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
rustbot
added
the
T-libs
|
Hey! It looks like you've submitted a new PR for the library teams! If this PR contains changes to any Examples of
|
|
r? @thomcc (rust-highfive has picked a reviewer for you, use r? to override) |
rust-highfive
added
the
S-waiting-on-review
|
@bors r+ rollup |
|
📌 Commit 6e2ac5d has been approved by |
bors
added
S-waiting-on-bors
matthiaskrgr
added a commit
to matthiaskrgr/rust
that referenced
this pull request
Jun 2, 2022
…n-docs, r=thomcc Improve documentation for constructors of pinned `Box`es 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](rust-lang#97397). 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](https://internals.rust-lang.org/t/pre-rfc-function-variants/16732/7?u=steffahn); 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.
bors
added a commit
to rust-lang-ci/rust
that referenced
this pull request
Jun 3, 2022
…askrgr Rollup of 5 pull requests Successful merges: - rust-lang#97502 (rustdoc: Add more test coverage) - rust-lang#97627 (update explicit impls error msg) - rust-lang#97640 (Fix wrong suggestion for adding where clauses) - rust-lang#97645 (don't use a `span_note` for ignored impls) - rust-lang#97655 (Improve documentation for constructors of pinned `Box`es) Failed merges: r? `@ghost` `@rustbot` modify labels: rollup
# for free
to join this conversation on GitHub.
Already have an account?
# to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Adds a cross-references between
Box::pinandBox::into_pin(and other related methods, i.e. the equivalentFromimplementation, and the unstablepin_inmethod), in particular now thatinto_pinwas stabilized. The main goal is to further improve visibility of the fact thatBox<T> -> Pin<Box<T>>conversion exits in the first place, and thatBox::pin(x)is – essentially – just a convenience function forBox::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 useBox::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 withBox::new" are things like cloning aBox, orBox::from_raw. If/whentry_newwould get stabilized, it would become a very good concrete example use-case ofBox::into_pinIMO.