rust-lang / rust-lang/rust

Minor clarity concern for drop section of `pin` module docs

Open
#128,847 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

Location

pin module docs under the Drop guarantee section https://doc.rust-lang.org/stable/std/pin/index.html#drop-guarantee

https://github.com/rust-lang/rust/blob/2048386fe2898febe7315c0feb915458e41c7aa5/library/core/src/pin.rs#L554-L560

Summary

As presented, this example using Option is a bit unclear to me since setting it to None, at least with the most obvious approach of my_option = None, would typically involve running drop for v such that it would not lead to UB. I guess this line is technically discussing when a value can be invalidated at a location and not specifically when it is invalidated in a way that breaks Pin's invariants by avoiding drop? Or it is implied that the option is being overwritten without dropping the old value?

Regardless, it is a bit confusing to encounter an example in this context that doesn't appear to be able to cause UB, especially since the next line is "Similarly," followed by an example where undefined behavior can occur.

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 with library/core/src/pin.rs around lines 554-560 and the Drop guarantee section of the pin module documentation. Compare the Option example with the following “Similarly” example and determine what wording or example change resolves the concern about dropping and invalidation. Done means the explanation clearly distinguishes ordinary assignment from invalidation that violates Pin’s invariants.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.