Merge #71

71: Do not display UnpinStruct in the document by default r=taiki-e a=taiki-e

There are some problems as mentioned in #70 

This causes the problem that by default the actual Unpin bounds cannot be known from the document if the original struct/enum itself is public (see #53 (comment) and rust-lang/rust#63281 for more).

This can be enabled using `--cfg pin_project_show_unpin_struct` in RUSTFLAGS.

```toml
# in Cargo.toml
[package.metadata.docs.rs]
rustdoc-args = ["--cfg", "pin_project_show_unpin_struct"]
```

cc @Aaron1011 @seanmonstar @LucioFranco

Co-authored-by: Taiki Endo <te316e89@gmail.com>

azure-pipelines.yml

@@ -49,7 +49,7 @@ jobs:
         toolchain: nightly
     - script: |
         cargo clean
-        RUSTFLAGS='--cfg compiletest' cargo test -p pin-project --all-features --test compiletest
+        RUSTFLAGS='--cfg compiletest --cfg pin_project_show_unpin_struct' cargo test -p pin-project --all-features --test compiletest
       displayName: compiletest
 
 - job: clippy

pin-project-internal/Cargo.toml

@@ -35,6 +35,3 @@ lazy_static = { version = "1.3", optional = true }
 
 [dev-dependencies]
 pin-project = { version = "0.4.0-alpha.8", path = ".." }
-
-[build-dependencies]
-rustc_version = "0.2.3"

pin-project-internal/build.rs

@@ -1,37 +1,20 @@
-// Based on https://stackoverflow.com/a/49250753/1290530
-
 use std::env;
 
-use rustc_version::{version_meta, Channel};
-
 fn main() {
-    // Set cfg flags depending on release channel
-    match version_meta().unwrap().channel {
-        // Enable our feature on nightly, or when using a
-        // locally build rustc.
-        //
-        // This is intended to avoid the issue that cannot know the actual
-        // trait implementation bounds of the `Unpin` implementation from the
-        // document of generated code.
-        // See [taiki-e/pin-project#53] and [rust-lang/rust#63281] for more details.
-        //
-        // [taiki-e/pin-project#53]: https://github.com/taiki-e/pin-project/pull/53#issuecomment-525906867
-        // [rust-lang/rust#63281]: https://github.com/rust-lang/rust/issues/63281
-        //
-        // You can opt-out of this in one of the followg ways:
-        // * Use `--cfg pin_project_stable_docs` in RUSTFLAGS.
-        //   ```toml
-        //   # in Cargo.toml
-        //   [package.metadata.docs.rs]
-        //   rustdoc-args = ["--cfg", "pin_project_stable_docs"]
-        //   ```
-        // * Use `-Zallow-features` in RUSTFLAGS to disallow unstable features.
-        Channel::Nightly | Channel::Dev
-            if feature_allowed("proc_macro_def_site") && !cfg!(pin_project_stable_docs) =>
-        {
-            println!("cargo:rustc-cfg=proc_macro_def_site");
-        }
-        _ => {}
+    // While this crate supports stable Rust, it currently requires
+    // nightly Rust in order for rustdoc to correctly document auto-generated
+    // `Unpin` impls. This does not affect the runtime functionality of this crate,
+    // nor does it affect the safety of the api provided by this crate.
+    //
+    // This is disabled by default and can be enabled using
+    // `--cfg pin_project_show_unpin_struct` in RUSTFLAGS.
+    //
+    // Refs:
+    // * https://github.com/taiki-e/pin-project/pull/53#issuecomment-525906867
+    // * https://github.com/taiki-e/pin-project/pull/70
+    // * https://github.com/rust-lang/rust/issues/63281
+    if cfg!(pin_project_show_unpin_struct) && feature_allowed("proc_macro_def_site") {
+        println!("cargo:rustc-cfg=proc_macro_def_site");
     }
 }
 

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

@@ -192,14 +192,17 @@ impl Context {
                 {
                     proc_macro::Span::def_site().into()
                 }
-
                 #[cfg(not(proc_macro_def_site))]
                 {
                     Span::call_site()
                 }
             };
 
-            let struct_ident = format_ident!("__UnpinStruct{}", orig_ident, span = make_span());
+            let struct_ident = if cfg!(proc_macro_def_site) {
+                format_ident!("UnpinStruct{}", orig_ident, span = make_span())
+            } else {
+                format_ident!("__UnpinStruct{}", orig_ident)
+            };
             let always_unpin_ident = format_ident!("AlwaysUnpin{}", orig_ident, span = make_span());
 
             // Generate a field in our new struct for every
@@ -292,6 +295,7 @@ impl Context {
                 ///
                 /// [taiki-e/pin-project#53]: https://github.com/taiki-e/pin-project/pull/53#issuecomment-525906867
                 /// [rust-lang/rust#63281]: https://github.com/rust-lang/rust/issues/63281
+                #[allow(dead_code)]
                 #vis struct #struct_ident #full_generics #where_clause {
                     __pin_project_use_generics: #always_unpin_ident <(#(#type_params),*)>,
 

src/lib.rs

@@ -6,12 +6,6 @@
 //! * [`pinned_drop`] - An attribute for annotating a function that implements `Drop`.
 //! * [`project`] - An attribute to support pattern matching.
 //!
-//! NOTE: While this crate supports stable Rust, it currently requires
-//! nightly Rust in order for rustdoc to correctly document auto-generated
-//! `Unpin` impls. This does not affect the runtime functionality of this crate,
-//! nor does it affect the safety of the api provided by this crate.
-//!
-//!
 //! ## Examples
 //!
 //! [`pin_project`] attribute creates a projection struct covering all the fields.

tests/compiletest.rs

@@ -1,4 +1,5 @@
 #![cfg(compiletest)]
+#![cfg(pin_project_show_unpin_struct)]
 #![cfg(feature = "project_attr")]
 #![warn(rust_2018_idioms, single_use_lifetimes)]
 

tests/ui/pin_project/proper_unpin.stderr

@@ -1,15 +1,15 @@
-error[E0277]: the trait bound `T: std::marker::Unpin` is not satisfied in `__UnpinStructFoo<T, U>`
+error[E0277]: the trait bound `T: std::marker::Unpin` is not satisfied in `UnpinStructFoo<T, U>`
   --> $DIR/proper_unpin.rs:20:5
    |
 17 | fn is_unpin<T: Unpin>() {}
    | ----------------------- required by `is_unpin`
 ...
 20 |     is_unpin::<Foo<T, U>>(); //~ ERROR E0277
-   |     ^^^^^^^^^^^^^^^^^^^^^ within `__UnpinStructFoo<T, U>`, the trait `std::marker::Unpin` is not implemented for `T`
+   |     ^^^^^^^^^^^^^^^^^^^^^ within `UnpinStructFoo<T, U>`, the trait `std::marker::Unpin` is not implemented for `T`
    |
    = help: consider adding a `where T: std::marker::Unpin` bound
    = note: required because it appears within the type `Inner<T>`
-   = note: required because it appears within the type `__UnpinStructFoo<T, U>`
+   = note: required because it appears within the type `UnpinStructFoo<T, U>`
    = note: required because of the requirements on the impl of `std::marker::Unpin` for `Foo<T, U>`
 
 error: aborting due to previous error

tests/ui/pin_project/unpin_sneaky.rs

@@ -8,6 +8,6 @@ struct Foo {
     inner: u8,
 }
 
-impl Unpin for __UnpinStructFoo {} //~ ERROR E0412,E0321
+impl Unpin for UnpinStructFoo {} //~ ERROR E0412,E0321
 
 fn main() {}

tests/ui/pin_project/unpin_sneaky.stderr

@@ -1,18 +1,18 @@
-error[E0412]: cannot find type `__UnpinStructFoo` in this scope
+error[E0412]: cannot find type `UnpinStructFoo` in this scope
   --> $DIR/unpin_sneaky.rs:11:16
    |
-11 | impl Unpin for __UnpinStructFoo {} //~ ERROR E0412,E0321
-   |                ^^^^^^^^^^^^^^^^ not found in this scope
+11 | impl Unpin for UnpinStructFoo {} //~ ERROR E0412,E0321
+   |                ^^^^^^^^^^^^^^ not found in this scope
 help: possible candidate is found in another module, you can import it into scope
    |
-3  | use crate::__UnpinStructFoo;
+3  | use crate::UnpinStructFoo;
    |
 
 error[E0321]: cross-crate traits with a default impl, like `std::marker::Unpin`, can only be implemented for a struct/enum type, not `[type error]`
   --> $DIR/unpin_sneaky.rs:11:1
    |
-11 | impl Unpin for __UnpinStructFoo {} //~ ERROR E0412,E0321
-   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ can't implement cross-crate trait with a default impl for non-struct/enum type
+11 | impl Unpin for UnpinStructFoo {} //~ ERROR E0412,E0321
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ can't implement cross-crate trait with a default impl for non-struct/enum type
 
 error: aborting due to 2 previous errors