rust-lang / rust-lang/rust

Resolving remaining concerns with `Pin` docs

Open
#119,714 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-docs C-enhancement T-libs
Dominant language
Rust
Stars
119k
Forks
16.1k
PR merge metrics
PR metrics pending

Description

https://github.com/rust-lang/rust/pull/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.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the current Pin documentation and the five linked review threads from rust-lang/rust#116129. Re-evaluate whether each concern still applies, then revise the documentation so it explains Unpin, structural pinning, the final design, and the pinboard analogy accurately and clearly.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.