Add details on PhantomData

src/librustc_typeck/diagnostics.rs

@@ -2112,10 +2112,8 @@ For more information see the [opt-in builtin traits RFC](https://github.com/rust
 "##,
 
 E0392: r##"
-This error indicates that a type parameter has been declared but not actually
+This error indicates that a type or lifetime parameter has been declared
-used.
+but not actually used.  Here is an example that demonstrates the error:
-
-Here is an example that demonstrates the error:
 
 ```
 enum Foo<T> {
@@ -2123,8 +2121,8 @@ enum Foo<T> {
 }
 ```
 
-The first way to fix this error is by removing the type parameter, as
+If the type parameter was included by mistake, this error can be fixed
-shown below:
+by simply removing the type parameter, as shown below:
 
 ```
 enum Foo {
@@ -2132,7 +2130,8 @@ enum Foo {
 }
 ```
 
-The second method is to actually make use of the type parameter:
+Alternatively, if the type parameter was intentionally inserted, it must be
+used. A simple fix is shown below:
 
 ```
 enum Foo<T> {
@@ -2140,10 +2139,36 @@ enum Foo<T> {
 }
 ```
 
-See the 'Type Parameters' section of the reference for more details
+This error may also commonly be found when working with unsafe code.  For
-on this topic:
+example, when using raw pointers one may wish to specify the lifetime for
+which the pointed-at data is valid.  An initial attempt (below) causes this
+error:
 
-http://doc.rust-lang.org/reference.html#type-parameters-1
+```
+struct Foo<'a, T> {
+    x: *const T
+}
+```
+
+We want to express the constraint that Foo should not outlive `'a`, because
+the data pointed to by `T` is only valid for that lifetime.  The problem is
+that there are no actual uses of `'a`.  It's possible to work around this
+by adding a PhantomData type to the struct, using it to tell the compiler
+to act as if the struct contained a borrowed reference `&'a T`:
+
+```
+use std::marker::PhantomData;
+
+struct Foo<'a, T: 'a> {
+    x: *const T,
+    phantom: PhantomData<&'a T>
+}
+```
+
+PhantomData can also be used to express information about unused type parameters.
+You can read more about it in the API documentation:
+
+https://doc.rust-lang.org/std/marker/struct.PhantomData.html
 "##
 
 }