rust-lang / rust-lang/rust

PhantomData confusing documentation

Open
#125,540 2 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-docs
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 type T in 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

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.