Improve document of UnpinStruct

taiki-e · Sep 3, 2019 · 5f7c6e3 · 5f7c6e3
1 parent fa58920
commit 5f7c6e3
Show file tree

Hide file tree

Showing 2 changed files with 34 additions and 7 deletions.
diff --git a/pin-project-internal/build.rs b/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");
         }
         _ => {}

diff --git a/pin-project-internal/src/pin_project/mod.rs b/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),*)>,