diff --git a/src/doc/nomicon/src/phantom-data.md b/src/doc/nomicon/src/phantom-data.md index 72fa2e2a77764..32539c2d01f6d 100644 --- a/src/doc/nomicon/src/phantom-data.md +++ b/src/doc/nomicon/src/phantom-data.md @@ -82,5 +82,23 @@ standard library made a utility for itself called `Unique` which: * wraps a `*const T` for variance * includes a `PhantomData` -* auto-derives Send/Sync as if T was contained -* marks the pointer as NonZero for the null-pointer optimization +* auto-derives `Send`/`Sync` as if T was contained +* marks the pointer as `NonZero` for the null-pointer optimization + +## Table of `PhantomData` patterns + +Here’s a table of all the wonderful ways `PhantomData` could be used: + +| Phantom type | `'a` | `T` | +|-----------------------------|-----------|---------------------------| +| `PhantomData` | - | variant (with drop check) | +| `PhantomData<&'a T>` | variant | variant | +| `PhantomData<&'a mut T>` | variant | invariant | +| `PhantomData<*const T>` | - | variant | +| `PhantomData<*mut T>` | - | invariant | +| `PhantomData` | - | contravariant (*) | +| `PhantomData T>` | - | variant | +| `PhantomData T>` | - | invariant | +| `PhantomData>` | invariant | - | + +(*) If contravariance gets scrapped, this would be invariant.