From bfc2f5de85c86b7d60a26d16b9991d9763b4c07e Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Tue, 31 Mar 2015 20:18:32 -0400 Subject: [PATCH] =?UTF-8?q?Improvements=20to=20PhantomData's=20docs=20?= =?UTF-8?q?=F0=9F=91=BB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes #22914 --- src/libcore/marker.rs | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/src/libcore/marker.rs b/src/libcore/marker.rs index 3f4b39da4b3bb..a07b37a802629 100644 --- a/src/libcore/marker.rs +++ b/src/libcore/marker.rs @@ -346,17 +346,16 @@ impl MarkerTrait for T { } #[stable(feature = "rust1", since = "1.0.0")] pub trait PhantomFn { } -/// `PhantomData` is a way to tell the compiler about fake fields. -/// Phantom data is required whenever type parameters are not used. -/// The idea is that if the compiler encounters a `PhantomData` -/// instance, it will behave *as if* an instance of the type `T` were -/// present for the purpose of various automatic analyses. +/// `PhantomData` allows you to describe that a type acts as if it stores a value of type `T`, +/// even though it does not. This allows you to inform the compiler about certain safety properties +/// of your code. +/// +/// Though they both have scary names, `PhantomData` and "phantom types" are unrelated. 👻👻👻 /// /// # Examples /// /// When handling external resources over a foreign function interface, `PhantomData` can -/// prevent mismatches by enforcing types in the method implementations, although the struct -/// doesn't actually contain values of the resource type. +/// prevent mismatches by enforcing types in the method implementations: /// /// ``` /// # trait ResType { fn foo(&self); }; @@ -397,11 +396,6 @@ pub trait PhantomFn { } /// commonly necessary if the structure is using an unsafe pointer /// like `*mut T` whose referent may be dropped when the type is /// dropped, as a `*mut T` is otherwise not treated as owned. -/// -/// FIXME. Better documentation and examples of common patterns needed -/// here! For now, please see [RFC 738][738] for more information. -/// -/// [738]: https://github.com/rust-lang/rfcs/blob/master/text/0738-variance.md #[lang="phantom_data"] #[stable(feature = "rust1", since = "1.0.0")] pub struct PhantomData;