Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve documentation for constructors of pinned Boxes #97655

Merged
merged 1 commit into from
Jun 3, 2022

Conversation

steffahn
Copy link
Member

@steffahn steffahn commented Jun 2, 2022

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.

@rustbot rustbot added the T-libs Relevant to the library team, which will review and decide on the PR/issue. label Jun 2, 2022
@rust-highfive
Copy link
Collaborator

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
Copy link
Collaborator

r? @thomcc

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

@rust-highfive rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jun 2, 2022
@thomcc
Copy link
Member

thomcc commented Jun 2, 2022

@bors r+ rollup

@bors
Copy link
Contributor

bors commented Jun 2, 2022

📌 Commit 6e2ac5d has been approved by thomcc

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jun 2, 2022
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
@bors bors merged commit 5b64aab into rust-lang:master Jun 3, 2022
@rustbot rustbot added this to the 1.63.0 milestone Jun 3, 2022
@steffahn steffahn deleted the better-pin-box-construction-docs branch June 3, 2022 11:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-libs Relevant to the library team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants