Improve the PhantomData table (#417)

Author: danielhenrymantilla

src/phantom-data.md

@@ -106,7 +106,14 @@ that that `Vec<T>` _owns_ values of type `T` (more precisely: may use values of
 in its `Drop` implementation), and Rust will thus not allow them to _dangle_ should a
 `Vec<T>` be dropped.
 
-**Adding an extra `_owns_T: PhantomData<T>` field is thus _superfluous_ and accomplishes nothing**.
+When a type already has a `Drop impl`, **adding an extra `_owns_T: PhantomData<T>` field
+is thus _superfluous_ and accomplishes nothing**, dropck-wise (it still affects variance
+and auto-traits).
+
+  - (advanced edge case: if the type containing the `PhantomData` has no `Drop` impl at all,
+    but still has drop glue (by having _another_ field with drop glue), then the
+    dropck/`#[may_dangle]` considerations mentioned herein do apply as well: a `PhantomData<T>`
+    field will then require `T` to be droppable whenever the containing type goes out of scope).
 
 ___
 
@@ -234,14 +241,18 @@ standard library made a utility for itself called `Unique<T>` which:
 
 Here’s a table of all the wonderful ways `PhantomData` could be used:
 
-| Phantom type                | `'a`      | `T`                         | `Send`    | `Sync`    |
-|-----------------------------|-----------|-----------------------------|-----------|-----------|
-| `PhantomData<T>`            | -         | covariant (with drop check) | `T: Send` | `T: Sync` |
-| `PhantomData<&'a T>`        | covariant | covariant                   | `T: Sync` | `T: Sync` |
-| `PhantomData<&'a mut T>`    | covariant | invariant                   | `T: Send` | `T: Sync` |
-| `PhantomData<*const T>`     | -         | covariant                   | -         | -         |
-| `PhantomData<*mut T>`       | -         | invariant                   | -         | -         |
-| `PhantomData<fn(T)>`        | -         | contravariant               | `Send`    | `Sync`    |
-| `PhantomData<fn() -> T>`    | -         | covariant                   | `Send`    | `Sync`    |
-| `PhantomData<fn(T) -> T>`   | -         | invariant                   | `Send`    | `Sync`    |
-| `PhantomData<Cell<&'a ()>>` | invariant | -                           | `Send`    | -         |
+| Phantom type                | variance of `'a` | variance of `T`   | `Send`/`Sync`<br/>(or lack thereof)       | dangling `'a` or `T` in drop glue<br/>(_e.g._, `#[may_dangle] Drop`) |
+|-----------------------------|:----------------:|:-----------------:|:-----------------------------------------:|:------------------------------------------------:|
+| `PhantomData<T>`            | -                | **cov**ariant     | inherited                                 | disallowed ("owns `T`")                          |
+| `PhantomData<&'a T>`        | **cov**ariant    | **cov**ariant     | `Send + Sync`<br/>requires<br/>`T : Sync` | allowed                                          |
+| `PhantomData<&'a mut T>`    | **cov**ariant    | **inv**ariant     | inherited                                 | allowed                                          |
+| `PhantomData<*const T>`     | -                | **cov**ariant     | `!Send + !Sync`                           | allowed                                          |
+| `PhantomData<*mut T>`       | -                | **inv**ariant     | `!Send + !Sync`                           | allowed                                          |
+| `PhantomData<fn(T)>`        | -                | **contra**variant | `Send + Sync`                             | allowed                                          |
+| `PhantomData<fn() -> T>`    | -                | **cov**ariant     | `Send + Sync`                             | allowed                                          |
+| `PhantomData<fn(T) -> T>`   | -                | **inv**ariant     | `Send + Sync`                             | allowed                                          |
+| `PhantomData<Cell<&'a ()>>` | **inv**ariant    | -                 | `Send + !Sync`                            | allowed                                          |
+
+  - Note: opting out of the `Unpin` auto-trait requires the dedicated [`PhantomPinned`] type instead.
+
+[`PhantomPinned`]: ../core/marker/struct.PhantomPinned.html