Merge #62

62: Improve document of UnpinStruct r=Aaron1011 a=taiki-e

Improve document and add a way to opt-out mentioned in #53 (comment).

The reason for needing support for ways other than `-Zallow-features` is that it also affects the use of other dependency unstable features.

Related:  #54 #56 (comment)

Generated document:

<img width="1001" alt="struct-1" src="https://user-images.githubusercontent.com/43724913/64136451-95494280-ce2c-11e9-81ce-6a02c315332f.png">
<img width="1015" alt="struct-2" src="https://user-images.githubusercontent.com/43724913/64136462-a6924f00-ce2c-11e9-9d1c-3cdca2d9b158.png">

Ways to opt-out of this:

https://github.com/taiki-e/pin-project/blob/5f7c6e35c2a9f3dfbc01a63e6206875d1bfb986b/pin-project-internal/build.rs#L21-L28

Co-authored-by: Taiki Endo <[email protected]>

pin-project-internal/build.rs

@@ -8,9 +8,27 @@ 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, unless `-Zallow-features`
-        // in RUSTFLAGS disallows unstable features.
-        Channel::Nightly | Channel::Dev if feature_allowed("proc_macro_def_site") => {
+        // 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");
         }
         _ => {}

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

@@ -233,10 +233,19 @@ impl Context {
                 // '__UnpinStruct' type must also be public. However, we take
                 // steps to ensure that the user can never actually reference
                 // this 'public' type. These steps are described below
-                /// A struct generated by pin-project to provide an appropriate
-                /// `Unpin` implementation, this type's `Unpin` implementation
-                /// uses exactly the same conditions as the original type's
-                /// `Unpin` implementation.
+                //
+                /// A struct generated by pin-project to correctly document the
+                /// automatically generated `Unpin` implementation.
+                ///
+                /// This struct exists to correctly document the actual trait
+                /// implementation bounds of the `Unpin` implementation of the
+                /// original type. Note that users cannot access this struct,
+                /// even if it is public.
+                ///
+                /// 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
                 #vis struct #struct_ident #full_generics #where_clause {
                     __pin_project_use_generics: #always_unpin_ident <(#(#type_params),*)>,