Code change:
#[stable(feature = "rust1", since = "1.0.0")] pub trait PhantomFn<A:?Sized,R:?Sized=()> { } <del> /// `PhantomData` is a way to tell the compiler about fake fields. /// Phantom data is required whenever type parameters are not used. /// The idea is that if the compiler encounters a `PhantomData<T>` /// instance, it will behave *as if* an instance of the type `T` were /// present for the purpose of various automatic analyses. </del> <ins> /// `PhantomData<T>` allows you to describe that a type acts as if it stores a value of type `T`, /// even though it does not. This allows you to inform the compiler about certain safety properties /// of your code. /// /// Though they both have scary names, `PhantomData<T>` and "phantom types" are unrelated. 👻👻👻 </ins> /// /// # Examples /// /// When handling external resources over a foreign function interface, `PhantomData<T>` can <del> /// prevent mismatches by enforcing types in the method implementations, although the struct /// doesn't actually contain values of the resource type. </del> <ins> /// prevent mismatches by enforcing types in the method implementations: </ins> /// /// ``` /// # trait ResType { fn foo(&self); };

Related discussion:
text: I need to give a Rust slice to a C API that will return an opaque handle (that actually contains a pointer to the slice), and the slice must outlive the handle. nicely suggested using for this, but the description of phantom data (and its RFC) for me is so far removed from my mental model/terminology of the problem, that it . "…tell the compiler about fake fields" — fake field doesn't sound like a thing I want to create. I'm not sure if a fake field is an actual Rust concept. I'm hoping it's a different way of saying a "pointer that Rust isn't keeping track of". "inform the compiler that one or more instances of the type T could be dropped" — but does it actually drop anything? I want to prevent value from being dropped, so this confuses me. The RFC is even worse, since it uses type variance terminology which is so confusing, that the most comprehensible description of them on Wikipedia is a 3D cube! !
allows you to describe that a type acts as if it stores a value of type , e.g. maybe one is having to use opaque pointers or otherwise disguise the fact that there is a contained in the value, or need to have a lifetime without having an actual reference to attach it to. This is what is meant by "fake field": a field doesn't actually store any data, but it behaves as if it does. If you have a lifetime, and the type is acting like a reference, then (or ) is the recommended approach. It's hard to be more specific without knowing your exact use-case, though. In any case, the major motivation for is to avoiding having to think in terms of co*variance, and instead just think of what the intended "storage" of a type is. The RFC is meant to serve as a technical reference to describe the behaviour unambiguously. I definitely agree that the current docs are not as helpful as they could be.
I see you've used lifetime as part of 's type. In my code I've used and got confusing error messages. That bit in the documentation would help a lot! (just saying is very unhelpful) BTW: the first paragraph in your comment is already clearer to me than the documentation :)
The example seems relevant.