PhantomData confusing documentation

[dimbleby]

Location

https://doc.rust-lang.org/std/marker/struct.PhantomData.html#ownership-and-the-drop-check, via

rust/library/core/src/marker.rs

Line 728 in 21e6de7

/// `T` in very rare circumstances. This in turn has effects on the Rust compiler's [drop check]

Summary

#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"?

[wuwbobo2021]

A problematic test case inspired by jni-rs/jni-rs#558:

use std::marker::PhantomData;

// In a real-world project, S1 may wrap a pointer of some data to be freed on Drop of S1.
struct S1<'a> {
    ph: PhantomData<&'a ()>
}

// In a real-world project, S2 may point to some raw data which will be freed on Drop of S1.
struct S2<'a> {
    ph: PhantomData<&'a ()>
}

// Uncomment 'a to avoid the strange problem!
impl<'a> S1<'a> {
    fn get_s2(& /*'a*/ self) -> S2<'a> {
        S2 { ph: PhantomData }
    }
}

fn main() {
    // Oh no, this compiles!
    let s2 = {
        let s1 = S1 { ph: PhantomData };
        s1.get_s2()
    };
    drop(s2);
}

Is this behavior documented somewhere?

[dimbleby]

@wuwbobo2021 this issue covers the specific line of documentation that it describes in the summary, please don't try to use it as a catch-all for PhantomData questions