Deprecate project* attributes

CHANGELOG.md

@@ -6,6 +6,33 @@ This project adheres to [Semantic Versioning](https://semver.org).
 
 ## [Unreleased]
 
+* [Deprecated `#[project]`, `#[project_ref]`, and `#[project_replace]` attributes due to some unfixable limitations.][244]
+
+  Consider naming the projected type by passing an argument with the same name as the method to the #[pin_project] attribute instead.
+
+  ```rust
+  use pin_project::pin_project;
+  use std::pin::Pin;
+
+  #[pin_project(project = EnumProj)]
+  enum Enum<T> {
+      Variant(#[pin] T),
+  }
+
+  fn func<T>(x: Pin<&mut Enum<T>>) {
+      match x.project() {
+          EnumProj::Variant(y) => {
+              let _: Pin<&mut T> = y;
+          }
+      }
+  }
+  ```
+
+  See [#225][225] for more details.
+
+[225]: https://github.com/taiki-e/pin-project/pull/225
+[244]: https://github.com/taiki-e/pin-project/pull/244
+
 ## [0.4.20] - 2020-06-07
 
 * [You can now use project_replace argument without Replace argument.][243]

pin-project-internal/build.rs

@@ -9,11 +9,17 @@ fn main() {
         None => return,
     };
 
-    // Underscore const names stabilized in Rust 1.37:
-    // https://github.com/rust-lang/rust/pull/61347/
+    // Underscore const names requires Rust 1.37:
+    // https://github.com/rust-lang/rust/pull/61347
     if minor >= 37 {
         println!("cargo:rustc-cfg=underscore_consts");
     }
+
+    // #[deprecated] on proc-macro requires Rust 1.40:
+    // https://github.com/rust-lang/rust/pull/65666
+    if minor >= 40 {
+        println!("cargo:rustc-cfg=deprecated_proc_macro");
+    }
 }
 
 fn rustc_minor_version() -> Option<u32> {

pin-project-internal/src/lib.rs

@@ -546,6 +546,7 @@ pub fn pinned_drop(args: TokenStream, input: TokenStream) -> TokenStream {
 /// ## Examples
 ///
 /// ```rust
+/// # #![allow(deprecated)]
 /// use pin_project::{pin_project, project};
 /// use std::pin::Pin;
 ///
@@ -576,6 +577,7 @@ pub fn pinned_drop(args: TokenStream, input: TokenStream) -> TokenStream {
 /// ## Examples
 ///
 /// ```rust
+/// # #![allow(deprecated)]
 /// use pin_project::{pin_project, project};
 /// use std::pin::Pin;
 ///
@@ -616,6 +618,7 @@ pub fn pinned_drop(args: TokenStream, input: TokenStream) -> TokenStream {
 /// ## Examples
 ///
 /// ```rust
+/// # #![allow(deprecated)]
 /// use pin_project::{pin_project, project};
 /// use std::pin::Pin;
 ///
@@ -650,6 +653,7 @@ pub fn pinned_drop(args: TokenStream, input: TokenStream) -> TokenStream {
 /// ## Examples
 ///
 /// ```rust
+/// # #![allow(deprecated)]
 /// # mod dox {
 /// use pin_project::pin_project;
 ///
@@ -676,6 +680,16 @@ pub fn pinned_drop(args: TokenStream, input: TokenStream) -> TokenStream {
 /// }
 /// # }
 /// ```
+#[cfg_attr(
+    deprecated_proc_macro,
+    deprecated(
+        since = "0.4.21",
+        note = "consider naming projected type by passing `project` \
+                argument to #[pin_project] attribute instead, see release note \
+                <https://github.com/taiki-e/pin-project/releases/tag/v0.4.21> \
+                for details"
+    )
+)]
 #[proc_macro_attribute]
 pub fn project(args: TokenStream, input: TokenStream) -> TokenStream {
     let input = syn::parse_macro_input!(input);
@@ -691,6 +705,16 @@ pub fn project(args: TokenStream, input: TokenStream) -> TokenStream {
 /// See [`#[project]`][`project`] attribute for more details.
 ///
 /// [`project`]: ./attr.project.html
+#[cfg_attr(
+    deprecated_proc_macro,
+    deprecated(
+        since = "0.4.21",
+        note = "consider naming projected type by passing `project_ref` \
+                argument to #[pin_project] attribute instead, see release note \
+                <https://github.com/taiki-e/pin-project/releases/tag/v0.4.21> \
+                for details"
+    )
+)]
 #[proc_macro_attribute]
 pub fn project_ref(args: TokenStream, input: TokenStream) -> TokenStream {
     let input = syn::parse_macro_input!(input);
@@ -706,6 +730,16 @@ pub fn project_ref(args: TokenStream, input: TokenStream) -> TokenStream {
 /// See [`#[project]`][`project`] attribute for more details.
 ///
 /// [`project`]: ./attr.project.html
+#[cfg_attr(
+    deprecated_proc_macro,
+    deprecated(
+        since = "0.4.21",
+        note = "consider naming projected type by passing `project_replace` \
+                argument to #[pin_project] attribute instead, see release note \
+                <https://github.com/taiki-e/pin-project/releases/tag/v0.4.21> \
+                for details"
+    )
+)]
 #[proc_macro_attribute]
 pub fn project_replace(args: TokenStream, input: TokenStream) -> TokenStream {
     let input = syn::parse_macro_input!(input);

src/lib.rs

@@ -55,12 +55,15 @@ pub use pin_project_internal::pin_project;
 #[doc(inline)]
 pub use pin_project_internal::pinned_drop;
 
+#[allow(deprecated)]
 #[doc(inline)]
 pub use pin_project_internal::project;
 
+#[allow(deprecated)]
 #[doc(inline)]
 pub use pin_project_internal::project_ref;
 
+#[allow(deprecated)]
 #[doc(inline)]
 pub use pin_project_internal::project_replace;
 

tests/project.rs

@@ -1,5 +1,6 @@
 #![warn(rust_2018_idioms, single_use_lifetimes)]
 #![allow(dead_code)]
+#![allow(deprecated)]
 
 // Ceurrently, `#[attr] if true {}` doesn't even *parse* on MSRV,
 // which means that it will error even behind a `#[rustversion::since(..)]`

tests/project_ref.rs

@@ -1,5 +1,6 @@
 #![warn(rust_2018_idioms, single_use_lifetimes)]
 #![allow(dead_code)]
+#![allow(deprecated)]
 
 use pin_project::{pin_project, project_ref};
 use std::pin::Pin;

tests/project_replace.rs

@@ -1,5 +1,6 @@
 #![warn(rust_2018_idioms, single_use_lifetimes)]
 #![allow(dead_code)]
+#![allow(deprecated)]
 
 use pin_project::{pin_project, project_replace};
 use std::{marker::PhantomData, pin::Pin};

tests/ui/project/ambiguous-let.rs

@@ -1,3 +1,5 @@
+#![allow(deprecated)]
+
 use pin_project::{pin_project, project};
 
 #[pin_project]

tests/ui/project/ambiguous-let.stderr

@@ -1,5 +1,5 @@
 error: Both initializer expression and pattern are replaceable, you need to split the initializer expression into separate let bindings to avoid ambiguity
-  --> $DIR/ambiguous-let.rs:16:9
+  --> $DIR/ambiguous-let.rs:18:9
    |
-16 |     let Struct(x) = match Pin::new(&mut foo).project() {
+18 |     let Struct(x) = match Pin::new(&mut foo).project() {
    |         ^^^^^^^^^

tests/ui/project/invalid.rs

@@ -1,3 +1,5 @@
+#![allow(deprecated)]
+
 mod argument {
     use pin_project::{pin_project, project};