Document the consequences of various PhantomData forms

[elinorbgr]

To work around the parameter T is never used [E0392] error, one if often suggested to use PhantomData.

However, the documentation of PhantomData explains that various forms are possible, but is quite vague about the consequences of the choice of a form (and also only handles a small subset of the possible forms).

From my understanding given this reddit thread I opened these various forms can have different consequences (regarding dopck and/or lifetime variance ?):

• PhantomData<T>
• PhantomData<&'a T>
• PhantomData<&'a mut T>
• PhantomData<*const T>
• PhantomData<*mut T>
• PhantomData<fn(T) -> ()>
• PhantomData<fn() -> T>
• PhantomData<fn(T) -> T>

But I have no real idea about what using one or another changes.

[GuillaumeGomez]

cc @Manishearth
cc @steveklabnik

[Manishearth]

cc @gankro

[elinorbgr]

I had forgotten to check the rustonomicon, and this page seems relevant.

Could be worth explaining the relation of PhantomData with variance and add a link to it in the doc, maybe ?

[Gankra]

• PhantomData<T> - drop check, variant over T
• PhantomData<&'a T> - variant over 'a, variant over T
• PhantomData<&'a mut T> - variant over 'a, invariant over T
• PhantomData<*const T> - variant over T
• PhantomData<*mut T> - invariant over T
• PhantomData<fn(T) -> ()> - contravariant over T, assuming we keep that -- invariant otherwise
• PhantomData<fn() -> T> - drop check, variant over T (a function that produces T from nothing is isomorphic to T)
• PhantomData<fn(T) -> T> - invariant over T?

The standard widget for "invariant over 'a" is Cell<&'a ()>.

[durka]

I wonder if there is already a crate that provides aliases to those various forms of PhantomData, appropriately named for a bit more self-documentation. If not I have a sudden desire to publish one :)

[Gankra]

I wouldn't recommend it -- it's what we used to have, but it was really confusing and no one could remember. The current system of "use what you semantically have" works a lot better.

[bluss]

According to the dropck rfc, PhantomData<fn() -> T> has no ownership / dropck implications. link

[steveklabnik]

Yeah, so I'm not sure what the best way is to expand this. The first sentence is

PhantomData allows you to describe that a type acts as if it stores a value of type T, even though it does not.

Which does cover all of these forms. It's just that.

[Manishearth]

Yeah, but it doesn't explain why you would use it, or what features can be inherited from those types.

There's some dropck and variance stuff, but there's nowhere that people can go to to read about it.

[Gankra]

Well, there's stuff in the nomicon.

[Manishearth]

We should link to it from the phantomdata docs then