From 78ad86878425d5cfbbaded88627083d85e452a21 Mon Sep 17 00:00:00 2001 From: Gary Guo Date: Tue, 17 Nov 2026 17:44:05 +0000 Subject: [PATCH 1/2] internal: use most visibility of the most visible field for projection Currently, we use the struct visibility for projection methods. This means that if a public struct uses `#[pin_data]`, the projection methods will be defined on them with public visibility despite the projection struct having no publicly accessible field. This both exposes the implementation detail of such structs, and add noise to the generated documentation. Use the combined field visibility for this instead, where that of the most visible field is used instead. Signed-off-by: Gary Guo --- internal/src/pin_data.rs | 35 ++++++++++++--------- internal/src/util.rs | 47 +++++++++++++++++++++++++++- tests/ui/expand/pin-data.expanded.rs | 10 +++--- tests/ui/expand/pin-data.rs | 2 +- 4 files changed, 73 insertions(+), 21 deletions(-) diff --git a/internal/src/pin_data.rs b/internal/src/pin_data.rs index 08e11128..30ebeb00 100644 --- a/internal/src/pin_data.rs +++ b/internal/src/pin_data.rs @@ -13,7 +13,7 @@ use syn::{ visit_mut::VisitMut, Attribute, Field, Fields, GenericArgument, GenericParam, Generics, Ident, Index, Item, ItemStruct, Lifetime, LifetimeParam, Member, Meta, PathArguments, PathSegment, Token, Type, - TypeParamBound, TypePath, WhereClause, WherePredicate, + TypeParamBound, TypePath, Visibility, WhereClause, WherePredicate, }; use crate::{ @@ -1332,14 +1332,21 @@ fn generate_variance_check(info: &StructInfo) -> TokenStream { fn generate_projections(info: &StructInfo) -> TokenStream { let ItemStruct { - vis, - ident, - generics, - .. + ident, generics, .. } = &info.struct_; let this_lt = Lifetime::new("'__this", Span::mixed_site()); let this_lt_generics: Generics = parse_quote!(<#this_lt>); + // Compute the least upper bound of field visibility. + // + // This will be used for generated projection methods instead of the visibility of the struct; + // if the struct visibility is used, the projection method will be exist on public structs that + // use `#[pin_data]` but the caller can do nothing with it (as all fields of the projection + // struct will be invisible). + let field_vis_lub = info.fields.iter().fold(Visibility::Inherited, |accum, f| { + accum.semilattice_join(&f.field.vis) + }); + // Wrap in `CombinedGenerics` because it's ty generics will always output `<>`, so it can be // used with `for`. let field_lts = CombinedGenerics(vec![ @@ -1541,7 +1548,7 @@ fn generate_projections(info: &StructInfo) -> TokenStream { let (projection_def, projection_init) = if info.is_tuple_struct { ( quote! { - #vis struct __Projection #generics_with_this_lt ( + #field_vis_lub struct __Projection #generics_with_this_lt ( #(#fields_decl)* ::core::marker::PhantomData<&'__this mut #ident #ty_generics>, ) #whr; @@ -1556,7 +1563,7 @@ fn generate_projections(info: &StructInfo) -> TokenStream { } else { ( quote! { - #vis struct __Projection #generics_with_this_lt + #field_vis_lub struct __Projection #generics_with_this_lt #whr { #(#fields_decl)* @@ -1576,7 +1583,7 @@ fn generate_projections(info: &StructInfo) -> TokenStream { let (projection_lt_def, projection_lt_init) = if info.is_tuple_struct { ( quote! { - #vis struct #projection_lt #generics_with_this_field_lt ( + #field_vis_lub struct #projection_lt #generics_with_this_field_lt ( #(#fields_decl_lt)* ::core::marker::PhantomData<&'__this mut #ident #ty_generics>, ) #whr; @@ -1591,7 +1598,7 @@ fn generate_projections(info: &StructInfo) -> TokenStream { } else { ( quote! { - #vis struct #projection_lt #generics_with_this_field_lt + #field_vis_lub struct #projection_lt #generics_with_this_field_lt #whr { #(#fields_decl_lt)* @@ -1750,7 +1757,7 @@ fn generate_projections(info: &StructInfo) -> TokenStream { let (projection_ref_lt_def, projection_ref_lt_init) = if info.is_tuple_struct { ( quote!( - #vis struct #projection_ref_lt #generics_with_this_field_ref_lt( + #field_vis_lub struct #projection_ref_lt #generics_with_this_field_ref_lt( #(#fields_ref_decl_lt)* ::core::marker::PhantomData<&'__this #ident #ty_generics>, ) #whr; @@ -1765,7 +1772,7 @@ fn generate_projections(info: &StructInfo) -> TokenStream { } else { ( quote! { - #vis struct #projection_ref_lt #generics_with_this_field_ref_lt + #field_vis_lub struct #projection_ref_lt #generics_with_this_field_ref_lt #whr { #(#fields_ref_decl_lt)* @@ -1813,7 +1820,7 @@ fn generate_projections(info: &StructInfo) -> TokenStream { /// These fields are **not** structurally pinned: #(#[doc = #not_structurally_pinned_fields_docs])* #[inline] - #vis fn project<'__this>( + #field_vis_lub fn project<'__this>( self: ::core::pin::Pin<&'__this mut Self>, ) -> __Projection #ty_generics_with_this_lt { // SAFETY: we only give access to `&mut` for fields not structurally pinned. @@ -1829,7 +1836,7 @@ fn generate_projections(info: &StructInfo) -> TokenStream { /// These fields are **not** structurally pinned: #(#[doc = #not_structurally_pinned_fields_docs])* #[inline] - #vis fn with_project<'__this, R>( + #field_vis_lub fn with_project<'__this, R>( self: ::core::pin::Pin<&'__this mut Self>, f: impl for #field_lt_ty_generics ::core::ops::FnOnce( #projection_lt #ty_generics_with_this_field_lt @@ -1848,7 +1855,7 @@ fn generate_projections(info: &StructInfo) -> TokenStream { /// These fields are **not** structurally pinned: #(#[doc = #not_structurally_pinned_fields_docs])* #[inline] - #vis fn with_project_ref<'__this, R>( + #field_vis_lub fn with_project_ref<'__this, R>( self: ::core::pin::Pin<&'__this Self>, f: impl for #field_lt_ty_generics ::core::ops::FnOnce( #projection_ref_lt #ty_generics_with_this_field_ref_lt diff --git a/internal/src/util.rs b/internal/src/util.rs index 4d3331b8..48e65106 100644 --- a/internal/src/util.rs +++ b/internal/src/util.rs @@ -6,7 +6,7 @@ use proc_macro2::{Ident, TokenStream}; use quote::{format_ident, ToTokens}; use syn::{ parse_quote, visit::Visit, visit_mut::VisitMut, Attribute, BoundLifetimes, GenericParam, - Generics, Index, Lifetime, Member, Token, Type, TypePath, + Generics, Index, Lifetime, Member, Token, Type, TypePath, VisRestricted, Visibility, }; use crate::DiagCtxt; @@ -498,3 +498,48 @@ impl TypeExt for Type { ret } } + +pub(crate) trait VisibilityExt { + /// Returns the least upper bound of `self` and `other`. + /// + /// If the exact upper bound cannot be determined, this may return a greater visiblity (more + /// visible). + fn semilattice_join(self, other: &Self) -> Visibility; +} + +impl VisibilityExt for Visibility { + fn semilattice_join(self, other: &Self) -> Visibility { + match (&self, other) { + (Visibility::Public(_), _) | (_, Visibility::Inherited) => self, + (_, Visibility::Public(_)) | (Visibility::Inherited, _) => other.clone(), + // `pub(in some::module)` is too common, so if we get this case just bail out and return + // `pub(crate)`. + (Visibility::Restricted(a), Visibility::Restricted(b)) + if a.in_token.is_some() || b.in_token.is_some() => + { + Visibility::Restricted(VisRestricted { + pub_token: a.pub_token, + paren_token: a.paren_token, + in_token: None, + path: parse_quote!(crate), + }) + } + (Visibility::Restricted(a), Visibility::Restricted(b)) => { + let a = a.path.get_ident().unwrap(); + let b = b.path.get_ident().unwrap(); + + if a == "crate" { + self + } else if b == "crate" { + other.clone() + } else if a == "super" { + self + } else if b == "super" { + other.clone() + } else { + self + } + } + } + } +} diff --git a/tests/ui/expand/pin-data.expanded.rs b/tests/ui/expand/pin-data.expanded.rs index 47bec118..b18f058f 100644 --- a/tests/ui/expand/pin-data.expanded.rs +++ b/tests/ui/expand/pin-data.expanded.rs @@ -1,6 +1,6 @@ use core::marker::PhantomPinned; use pin_init::*; -struct Foo { +pub struct Foo { array: [u8; 1024 * 1024], _pin: PhantomPinned, } @@ -88,7 +88,7 @@ const _: () = { } #[doc(hidden)] #[allow(non_snake_case, explicit_outlives_requirements)] - struct __PinDataLt { + pub struct __PinDataLt { array: ::pin_init::__internal::PhantomInvariant<[u8; 1024 * 1024]>, _pin: ::pin_init::__internal::PhantomInvariant, __pin_phantom: ::core::marker::PhantomData, @@ -138,7 +138,7 @@ const _: () = { } } #[doc(hidden)] - struct __ThePinData { + pub struct __ThePinData { __phantom: ::pin_init::__internal::PhantomInvariant, } impl ::core::clone::Clone for __ThePinData { @@ -151,7 +151,7 @@ const _: () = { impl __ThePinData { /// Type inference helper function. #[inline(always)] - fn __make_closure<__F, __E>(self, f: __F) -> __F + pub fn __make_closure<__F, __E>(self, f: __F) -> __F where __F: ::core::ops::FnOnce( *mut Foo, @@ -161,7 +161,7 @@ const _: () = { f } #[inline(always)] - fn __with_lt(self) -> __PinDataLt { + pub fn __with_lt(self) -> __PinDataLt { unsafe { ::core::mem::zeroed() } } } diff --git a/tests/ui/expand/pin-data.rs b/tests/ui/expand/pin-data.rs index 8b60e500..9c2bd7d8 100644 --- a/tests/ui/expand/pin-data.rs +++ b/tests/ui/expand/pin-data.rs @@ -2,7 +2,7 @@ use core::marker::PhantomPinned; use pin_init::*; #[pin_data] -struct Foo { +pub struct Foo { array: [u8; 1024 * 1024], #[pin] _pin: PhantomPinned, From c03348cac1fb889592d71024b4afed092001a93c Mon Sep 17 00:00:00 2001 From: Gary Guo Date: Wed, 18 Nov 2026 11:34:02 +0000 Subject: [PATCH 2/2] internal: hide `HasPinData` impl `HasPinData` is an implementation detail of pin-init to communicate from `#[pin_data]` macro to `pin_init!()` macro on how to initialize the struct. Thus, `HasPinData` is marked as `#[doc(hidden)]`; however, Rustdoc still renders the impl. Thus, also mark impl as `#[doc(hidden)]` Signed-off-by: Gary Guo --- internal/src/pin_data.rs | 1 + tests/ui/expand/many_generics.expanded.rs | 1 + tests/ui/expand/pin-data.expanded.rs | 1 + tests/ui/expand/pinned_drop.expanded.rs | 1 + tests/ui/expand/tuple_struct.expanded.rs | 1 + 5 files changed, 5 insertions(+) diff --git a/internal/src/pin_data.rs b/internal/src/pin_data.rs index 30ebeb00..4711abca 100644 --- a/internal/src/pin_data.rs +++ b/internal/src/pin_data.rs @@ -2081,6 +2081,7 @@ fn generate_the_pin_data(info: &StructInfo) -> TokenStream { // SAFETY: We have added the correct projection functions above to `__ThePinData` and // we also use the least restrictive generics possible. + #[doc(hidden)] unsafe impl #impl_generics ::pin_init::__internal::HasPinData for #struct_name #ty_generics #whr { diff --git a/tests/ui/expand/many_generics.expanded.rs b/tests/ui/expand/many_generics.expanded.rs index 9fe9affc..67546ca6 100644 --- a/tests/ui/expand/many_generics.expanded.rs +++ b/tests/ui/expand/many_generics.expanded.rs @@ -270,6 +270,7 @@ const _: () = { unsafe { ::core::mem::zeroed() } } } + #[doc(hidden)] unsafe impl< 'a, 'b: 'a, diff --git a/tests/ui/expand/pin-data.expanded.rs b/tests/ui/expand/pin-data.expanded.rs index b18f058f..1845341b 100644 --- a/tests/ui/expand/pin-data.expanded.rs +++ b/tests/ui/expand/pin-data.expanded.rs @@ -165,6 +165,7 @@ const _: () = { unsafe { ::core::mem::zeroed() } } } + #[doc(hidden)] unsafe impl ::pin_init::__internal::HasPinData for Foo { type PinData = __ThePinData; #[inline] diff --git a/tests/ui/expand/pinned_drop.expanded.rs b/tests/ui/expand/pinned_drop.expanded.rs index 81c6f58c..41bab60f 100644 --- a/tests/ui/expand/pinned_drop.expanded.rs +++ b/tests/ui/expand/pinned_drop.expanded.rs @@ -165,6 +165,7 @@ const _: () = { unsafe { ::core::mem::zeroed() } } } + #[doc(hidden)] unsafe impl ::pin_init::__internal::HasPinData for Foo { type PinData = __ThePinData; #[inline] diff --git a/tests/ui/expand/tuple_struct.expanded.rs b/tests/ui/expand/tuple_struct.expanded.rs index 071047f8..276c1c15 100644 --- a/tests/ui/expand/tuple_struct.expanded.rs +++ b/tests/ui/expand/tuple_struct.expanded.rs @@ -190,6 +190,7 @@ const _: () = { unsafe { ::core::mem::zeroed() } } } + #[doc(hidden)] unsafe impl<'a, T: Copy, const N: usize> ::pin_init::__internal::HasPinData for Foo<'a, T, N> { type PinData = __ThePinData<'a, T, N>;