Skip to content

Resolving remaining concerns with Pin docs #119714

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

Open
RalfJung opened this issue Jan 7, 2024 · 1 comment
Open

Resolving remaining concerns with Pin docs #119714

RalfJung opened this issue Jan 7, 2024 · 1 comment
Labels
A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools C-enhancement Category: An issue proposing an enhancement or a PR with one. T-libs Relevant to the library team, which will review and decide on the PR/issue. T-libs-api Relevant to the library API team, which will review and decide on the PR/issue.

Comments

@RalfJung
Copy link
Member

RalfJung commented Jan 7, 2024

#116129 was landed with some outstanding concerns, since it was considered to be an improvement over the status quo despite those concerns. Would be good to further improve the docs and resolve those concerns. :) The text also changed a bit since the concerns were originally raised, so we have to re-evaluate if they still apply.

  1. This thread is about the concern that the description of Unpin focuses too much on describing the effects of !Unpin rather than Unpin.
  2. This thread is about the docs basically re-telling the story of how we arrived at Pin, with various twists and turns, which might not be the best way to explain how to work with the final design. The historical part should possibly be moved further down in the docs.
  3. This thread is about the interaction of structural pinning and Unpin.
  4. This thread is about the claim that Unpin types will "not expose nor rely on any pinning guarantees", which is not quite correct.
  5. This thread is about the "pinboard" analogy not being evocative or necessarily very useful.
@rustbot rustbot added the needs-triage This issue may need triage. Remove it if it has been sufficiently triaged. label Jan 7, 2024
@fmease fmease added C-enhancement Category: An issue proposing an enhancement or a PR with one. T-libs-api Relevant to the library API team, which will review and decide on the PR/issue. A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools T-libs Relevant to the library team, which will review and decide on the PR/issue. and removed needs-triage This issue may need triage. Remove it if it has been sufficiently triaged. labels Jan 7, 2024
@Manishearth
Copy link
Member

I think for (1) someone should probably rearrange the Unpin docs to talk about Unpin first and then talk about !Unpin.

For (2) we should move that story to the end and reference it prominently.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools C-enhancement Category: An issue proposing an enhancement or a PR with one. T-libs Relevant to the library team, which will review and decide on the PR/issue. T-libs-api Relevant to the library API team, which will review and decide on the PR/issue.
Projects
None yet
Development

No branches or pull requests

4 participants