Rollup merge of #40069 - Rufflewind:master, r=steveklabnik

Add Gankro's table to nomicon/src/phantom-data.md

Original: https://github.com/rust-lang/rust/issues/30069#issuecomment-159928136

Testing confirms that:

  - `PhantomData<fn() -> T>` does not actually enable drop checking.
  - `PhantomData<fn(T) -> T>` is neither variant nor contravariant.

1 files changed, 20 insertions, 2 deletions

diff --git a/src/doc/nomicon/src/phantom-data.md b/src/doc/nomicon/src/phantom-data.md
index 72fa2e2a777..32539c2d01f 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<T>` which:
 
 * wraps a `*const T` for variance
 * includes a `PhantomData<T>`
-* 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<T>`            | -         | variant (with drop check) |
+| `PhantomData<&'a T>`        | variant   | variant                   |
+| `PhantomData<&'a mut T>`    | variant   | invariant                 |
+| `PhantomData<*const T>`     | -         | variant                   |
+| `PhantomData<*mut T>`       | -         | invariant                 |
+| `PhantomData<fn(T)>`        | -         | contravariant (*)         |
+| `PhantomData<fn() -> T>`    | -         | variant                   |
+| `PhantomData<fn(T) -> T>`   | -         | invariant                 |
+| `PhantomData<Cell<&'a ()>>` | invariant | -                         |
+
+(*) If contravariance gets scrapped, this would be invariant.