From 69ac00aac0a90eaa2de178e89ff9aca257ae0de5 Mon Sep 17 00:00:00 2001 From: Pyry Kontio Date: Mon, 2 Mar 2015 06:14:45 +0200 Subject: [PATCH 1/3] Adding a PhantomData example. --- src/libcore/marker.rs | 30 +++++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/src/libcore/marker.rs b/src/libcore/marker.rs index 868a671b9560e..17f06c3683503 100644 --- a/src/libcore/marker.rs +++ b/src/libcore/marker.rs @@ -351,7 +351,35 @@ pub trait PhantomFn { } /// instance, it will behave *as if* an instance of the type `T` were /// present for the purpose of various automatic analyses. /// -/// For example, embedding a `PhantomData` will inform the compiler +/// # Example +/// 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. +/// +///``` +///pub struct ExternalResource { +/// resource_handle: *mut (), +/// resource_type: PhantomData, +///} +/// +///impl ExternalResource { +/// pub fn new() -> ExternalResource { +/// let size_of_res = mem::size_of::(); +/// ExternalResource { +/// resource_handle: foreign_lib::new(size_of_res), +/// resource_type: PhantomData, +/// } +/// } +/// +/// pub fn do_stuff(&self, param: ParamType) { +/// let foreign_params = convert_params::(param); +/// foreign_lib::do_stuff(self.resource_handle, foreign_params); +/// } +///} +///``` +/// +/// Another example: embedding a `PhantomData` will inform the compiler /// that one or more instances of the type `T` could be dropped when /// instances of the type itself is dropped, though that may not be /// apparent from the other structure of the type itself. This is From ecf345457126c1373ef635754a369f433f310b7d Mon Sep 17 00:00:00 2001 From: Pyry Kontio Date: Wed, 4 Mar 2015 23:32:03 +0200 Subject: [PATCH 2/3] Fixed nits. --- src/libcore/marker.rs | 47 ++++++++++++++++++++++--------------------- 1 file changed, 24 insertions(+), 23 deletions(-) diff --git a/src/libcore/marker.rs b/src/libcore/marker.rs index 17f06c3683503..351b2cd18f39a 100644 --- a/src/libcore/marker.rs +++ b/src/libcore/marker.rs @@ -351,33 +351,34 @@ pub trait PhantomFn { } /// instance, it will behave *as if* an instance of the type `T` were /// present for the purpose of various automatic analyses. /// -/// # Example +/// # Examples +/// /// When handling external resources over a foreign function interface, -/// PhantomData can prevent mismatches by enforcing types in +/// `PhantomData` can prevent mismatches by enforcing types in /// the method implementations, although the struct doesn't actually /// contain values of the resource type. /// -///``` -///pub struct ExternalResource { -/// resource_handle: *mut (), -/// resource_type: PhantomData, -///} -/// -///impl ExternalResource { -/// pub fn new() -> ExternalResource { -/// let size_of_res = mem::size_of::(); -/// ExternalResource { -/// resource_handle: foreign_lib::new(size_of_res), -/// resource_type: PhantomData, -/// } -/// } -/// -/// pub fn do_stuff(&self, param: ParamType) { -/// let foreign_params = convert_params::(param); -/// foreign_lib::do_stuff(self.resource_handle, foreign_params); -/// } -///} -///``` +``` +struct ExternalResource { + resource_handle: *mut (), + resource_type: PhantomData, +} + +impl ExternalResource { + fn new() -> ExternalResource { + let size_of_res = mem::size_of::(); + ExternalResource { + resource_handle: foreign_lib::new(size_of_res), + resource_type: PhantomData, + } + } + + fn do_stuff(&self, param: ParamType) { + let foreign_params = convert_params::(param); + foreign_lib::do_stuff(self.resource_handle, foreign_params); + } +} +``` /// /// Another example: embedding a `PhantomData` will inform the compiler /// that one or more instances of the type `T` could be dropped when From 6eb5a375cb9e65bd60b778119a9e77bde37b6900 Mon Sep 17 00:00:00 2001 From: Pyry Kontio Date: Wed, 4 Mar 2015 23:34:37 +0200 Subject: [PATCH 3/3] Oops, added missing ///s. --- src/libcore/marker.rs | 42 +++++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/src/libcore/marker.rs b/src/libcore/marker.rs index 351b2cd18f39a..a1e4f53218356 100644 --- a/src/libcore/marker.rs +++ b/src/libcore/marker.rs @@ -358,27 +358,27 @@ pub trait PhantomFn { } /// the method implementations, although the struct doesn't actually /// contain values of the resource type. /// -``` -struct ExternalResource { - resource_handle: *mut (), - resource_type: PhantomData, -} - -impl ExternalResource { - fn new() -> ExternalResource { - let size_of_res = mem::size_of::(); - ExternalResource { - resource_handle: foreign_lib::new(size_of_res), - resource_type: PhantomData, - } - } - - fn do_stuff(&self, param: ParamType) { - let foreign_params = convert_params::(param); - foreign_lib::do_stuff(self.resource_handle, foreign_params); - } -} -``` +///``` +///struct ExternalResource { +/// resource_handle: *mut (), +/// resource_type: PhantomData, +///} +/// +///impl ExternalResource { +/// fn new() -> ExternalResource { +/// let size_of_res = mem::size_of::(); +/// ExternalResource { +/// resource_handle: foreign_lib::new(size_of_res), +/// resource_type: PhantomData, +/// } +/// } +/// +/// fn do_stuff(&self, param: ParamType) { +/// let foreign_params = convert_params::(param); +/// foreign_lib::do_stuff(self.resource_handle, foreign_params); +/// } +///} +///``` /// /// Another example: embedding a `PhantomData` will inform the compiler /// that one or more instances of the type `T` could be dropped when