From d2b515a58ce604a454f5c616bd760aa96e6b38c7 Mon Sep 17 00:00:00 2001
From: Daniel Henry-Mantilla <daniel.henry.mantilla@gmail.com>
Date: Mon, 7 Aug 2023 20:06:31 +0200
Subject: [PATCH 1/3] Improve the `PhantomData` table

  - simplify and clarify the auto-traits (_c.f._, #411)
      - No more `-` in the auto-traits part
  - move `dropck` to its own dedicated column
  - Name the `'a` and `T` columns with "variance"
  - Emphasize the `cov` _vs._ `inv` _vs._ `contra` distinctions
  - Add a mention to the `PhantomPinned` type.
---
 src/phantom-data.md | 26 +++++++++++++++-----------
 1 file changed, 15 insertions(+), 11 deletions(-)

diff --git a/src/phantom-data.md b/src/phantom-data.md
index 449d9e77..1cfd38fa 100644
--- a/src/phantom-data.md
+++ b/src/phantom-data.md
@@ -234,14 +234,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

From b372cea91f131d1c4b6e838a2b1f9e6decb45cae Mon Sep 17 00:00:00 2001
From: Daniel Henry-Mantilla <daniel.henry.mantilla@gmail.com>
Date: Mon, 7 Aug 2023 20:23:04 +0200
Subject: [PATCH 2/3] Clarify the "achieves nothing" statement

by properly scoping it to dropck shenanigans
---
 src/phantom-data.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/phantom-data.md b/src/phantom-data.md
index 1cfd38fa..c82859e6 100644
--- a/src/phantom-data.md
+++ b/src/phantom-data.md
@@ -106,7 +106,9 @@ 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).
 
 ___
 

From 8f6451a364f27197de45d5ecfd90901aab291687 Mon Sep 17 00:00:00 2001
From: Daniel Henry-Mantilla <daniel.henry.mantilla@gmail.com>
Date: Mon, 7 Aug 2023 20:26:08 +0200
Subject: [PATCH 3/3] Add non-`#[may_dangle]` mention to dropck mechanic

---
 src/phantom-data.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/src/phantom-data.md b/src/phantom-data.md
index c82859e6..cd2428d9 100644
--- a/src/phantom-data.md
+++ b/src/phantom-data.md
@@ -110,6 +110,11 @@ When a type already has a `Drop impl`, **adding an extra `_owns_T: PhantomData<T
 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).
+
 ___
 
 But this situation can sometimes lead to overly restrictive code. That's why the