Minor clarity concern for drop section of `pin` module docs
Nobody has claimed this yet.
- 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
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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