PhantomData confusing documentation
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 119k
- Forks
- 16.1k
- PR merge metrics
- PR metrics pending
Description
Location
https://doc.rust-lang.org/std/marker/struct.PhantomData.html#ownership-and-the-drop-check, via https://github.com/rust-lang/rust/blob/21e6de7eb64c09102de3f100420a09edc1a2a8d7/library/core/src/marker.rs#L728
Summary
https://github.com/rust-lang/rust/pull/103413 updated the documentation for PhantomData to say
Currently, adding a field of type
PhantomData<T>indicates that your type owns data of typeTin very rare circumstances.
I don't understand. How rare must these circumstances be for me to use PhantomData? What should I do if my type always owns data of type T?
I guess this is not what was meant, but I am finding it hard to figure out what the intention was and propose an improvement.
Possibly just remove the phrase "in very rare circumstances"?
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 the Ownership and the drop check section in library/core/src/marker.rs, around the referenced line, and compare it with the documentation change in PR #103413. Clarify the meaning of the statement about PhantomData ownership so readers know when it applies and what to do when a type owns T; the documentation should no longer leave the reported question ambiguous.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100