Document the project_replace() method.

Author: Diggsey

pin-project-internal/src/lib.rs

@@ -226,6 +226,63 @@ use utils::{Immutable, Mutable, Owned};
 ///
 /// See also [`pinned_drop`] attribute.
 ///
+/// ### `project_replace()`
+///
+/// In addition to the `project()` and `project_ref()` methods which are always
+/// provided when you use the `#[pin_project]` attribute, there is a third method,
+/// `project_replace()` which can be useful in some situations. It is equivalent
+/// to [`Pin::set`], except that the unpinned fields are moved and returned,
+/// instead of being dropped in-place.
+///
+/// ```
+/// # #[rustversion::since(1.36)]
+/// # fn dox() {
+/// # use std::pin::Pin;
+/// # type ProjectionOwned = ();
+/// # trait Dox {
+/// fn project_replace(self: Pin<&mut Self>, other: Self) -> ProjectionOwned;
+/// # }
+/// # }
+/// ```
+///
+/// The `ProjectionOwned` type is identical to the `Self` type, except that
+/// all pinned fields have been replaced by equivalent `PhantomData` types.
+///
+/// This method is opt-in, because it is only supported for `Sized` types, and
+/// because it is incompatible with the `#[pinned_drop]` attribute described
+/// above. It can be enabled by using `#[pin_project(Replace)]`.
+///
+/// For example:
+///
+/// ```rust
+/// use pin_project::{pin_project, project_replace};
+///
+/// #[pin_project(Replace)]
+/// pub enum Foo<T> {
+///     A {
+///         #[pin]
+///         pinned_field: i32,
+///         unpinned_field: T,
+///     },
+///     B,
+/// }
+///
+/// #[project_replace]
+/// fn main() {
+///     let mut x = Box::pin(Foo::A { pinned_field: 42, unpinned_field: "hello" });
+///
+///     #[project_replace]
+///     match x.as_mut().project_replace(Foo::B) {
+///         Foo::A { unpinned_field, .. } => assert_eq!(unpinned_field, "hello"),
+///         Foo::B => unreachable!(),
+///     }
+/// }
+/// ```
+///
+/// The [`project_replace`] attributes are necessary whenever destructuring the return
+/// type of `project_replace()`, and work in exactly the same way as the
+/// [`project`] and [`project_ref`] attributes.
+///
 /// ## Supported Items
 ///
 /// The current pin-project supports the following types of items.
@@ -320,6 +377,7 @@ use utils::{Immutable, Mutable, Owned};
 /// [`UnsafeUnpin`]: https://docs.rs/pin-project/0.4/pin_project/trait.UnsafeUnpin.html
 /// [`project`]: ./attr.project.html
 /// [`project_ref`]: ./attr.project_ref.html
+/// [`project_replace`]: ./attr.project_replace.html
 /// [`pinned_drop`]: ./attr.pinned_drop.html
 #[proc_macro_attribute]
 pub fn pin_project(args: TokenStream, input: TokenStream) -> TokenStream {

pin-project-internal/src/pin_project/derive.rs

@@ -398,7 +398,7 @@ impl<'a> Context<'a> {
             proj_items.extend(quote_spanned! { replace =>
                 #[allow(dead_code)] // This lint warns unused fields/variants.
                 #vis struct #proj_own_ident #orig_generics #where_clause_own_fields
-            })
+            });
         }
 
         let proj_mut_body = quote! {
@@ -453,7 +453,7 @@ impl<'a> Context<'a> {
         let proj_generics = &self.proj.generics;
         let where_clause = &self.proj.where_clause;
 
-        let proj_items = quote! {
+        let mut proj_items = quote! {
             #[allow(clippy::mut_mut)] // This lint warns `&mut &mut <ty>`.
             #[allow(dead_code)] // This lint warns unused fields/variants.
             #vis enum #proj_ident #proj_generics #where_clause {
@@ -463,12 +463,17 @@ impl<'a> Context<'a> {
             #vis enum #proj_ref_ident #proj_generics #where_clause {
                 #proj_ref_variants
             }
-            #[allow(dead_code)] // This lint warns unused fields/variants.
-            #vis enum #proj_own_ident #orig_generics #orig_where_clause {
-                #proj_own_variants
-            }
         };
 
+        if let Some(replace) = self.replace {
+            proj_items.extend(quote_spanned! { replace =>
+                #[allow(dead_code)] // This lint warns unused fields/variants.
+                #vis enum #proj_own_ident #orig_generics #orig_where_clause {
+                    #proj_own_variants
+                }
+            });
+        }
+
         let proj_mut_body = quote! {
             match self.get_unchecked_mut() {
                 #proj_arms