mirror of https://lore.kernel.org/lkml/
 help / color / mirror / Atom feed
* [PATCH 0/3] rust: pin-init: reduce visibility of projection methods to declutter rustdoc
@ 2026-11-18 14:31 Gary Guo
  2026-11-18 14:31 ` [PATCH 1/3] rust: pin-init: internal: allow `clippy::large_unopt_stack_frames` Gary Guo
                   ` (2 more replies)
  0 siblings, 3 replies; 4+ messages in thread
From: Gary Guo @ 2026-11-18 14:31 UTC (permalink / raw)
  To: Benno Lossin, Miguel Ojeda, Boqun Feng, Björn Roy Baron,
	Andreas Hindborg, Alice Ryhl, Trevor Gross, Danilo Krummrich,
	Daniel Almeida, Tamir Duberstein, Alexandre Courbot,
	Onur Özkan
  Cc: rust-for-linux, linux-kernel, Gary Guo

Currently all types that use `#[pin_data]` will have projection method
generated and visible in rustdoc. But for many types, all fields are
private and thus these projection methods are not useful as public APIs.

Thus, compute a least upper bound (LUB) of field visibility and use that as
visibility for projection methods instead. This means that if none of the
fields are accessible publicly, the projection methods won't be as well and
thus will be hidden from rustdoc.

We could also just mark these methods as `#[doc(hidden)]` -- but LSPs will
hide these methods too -- and bthese are indeed APIs that people would want
to use.

Signed-off-by: Gary Guo <gary@garyguo.net>
---
Gary Guo (3):
      rust: pin-init: internal: allow `clippy::large_unopt_stack_frames`
      rust: pin-init: internal: use visibility of the most visible field for projection
      rust: pin-init: internal: hide `HasPinData` impl

 rust/pin-init/internal/src/init.rs     |  2 +-
 rust/pin-init/internal/src/pin_data.rs | 36 ++++++++++++++++----------
 rust/pin-init/internal/src/util.rs     | 47 +++++++++++++++++++++++++++++++++-
 3 files changed, 69 insertions(+), 16 deletions(-)
---
base-commit: b7218f1996f8491dbe28632b70f444cb73f554df
change-id: 20261118-dev-project-vis-ff83ea9e6926

Best regards,
--  
Gary Guo <gary@garyguo.net>


^ permalink raw reply	[flat|nested] 4+ messages in thread

* [PATCH 1/3] rust: pin-init: internal: allow `clippy::large_unopt_stack_frames`
  2026-11-18 14:31 [PATCH 0/3] rust: pin-init: reduce visibility of projection methods to declutter rustdoc Gary Guo
@ 2026-11-18 14:31 ` Gary Guo
  2026-11-18 14:31 ` [PATCH 2/3] rust: pin-init: internal: use visibility of the most visible field for projection Gary Guo
  2026-11-18 14:31 ` [PATCH 3/3] rust: pin-init: internal: hide `HasPinData` impl Gary Guo
  2 siblings, 0 replies; 4+ messages in thread
From: Gary Guo @ 2026-11-18 14:31 UTC (permalink / raw)
  To: Benno Lossin, Miguel Ojeda, Boqun Feng, Björn Roy Baron,
	Andreas Hindborg, Alice Ryhl, Trevor Gross, Danilo Krummrich,
	Daniel Almeida, Tamir Duberstein, Alexandre Courbot,
	Onur Özkan
  Cc: rust-for-linux, linux-kernel, Gary Guo

From: Gary Guo <gary@garyguo.net>

Since Rust 1.102, Clippy renames `large_stack_frames` to
`large_unopt_stack_frames` and make it warn by default. This is a good
thing as in such cases pin-init should be used rather than potentially
leave unoptimized large moves on stack. However, this also triggers in
unexecutable code paths that pin-init generates for field duplication and
exhaustiveness checks. Allow it on the generated check closure.

Signed-off-by: Gary Guo <gary@garyguo.net>
---
 rust/pin-init/internal/src/init.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rust/pin-init/internal/src/init.rs b/rust/pin-init/internal/src/init.rs
index ded2b5283376..c78f8d3ca309 100644
--- a/rust/pin-init/internal/src/init.rs
+++ b/rust/pin-init/internal/src/init.rs
@@ -572,7 +572,7 @@ fn make_field_check(
     };
 
     quote_spanned! { Span::mixed_site() =>
-        #[allow(unreachable_code)]
+        #[allow(unreachable_code, clippy::large_unopt_stack_frames)]
         // We use unreachable code to perform field checks. They're still checked by the compiler.
         // SAFETY: this code is never executed.
         let _ = || unsafe {

-- 
2.54.0


^ permalink raw reply	[flat|nested] 4+ messages in thread

* [PATCH 2/3] rust: pin-init: internal: use visibility of the most visible field for projection
  2026-11-18 14:31 [PATCH 0/3] rust: pin-init: reduce visibility of projection methods to declutter rustdoc Gary Guo
  2026-11-18 14:31 ` [PATCH 1/3] rust: pin-init: internal: allow `clippy::large_unopt_stack_frames` Gary Guo
@ 2026-11-18 14:31 ` Gary Guo
  2026-11-18 14:31 ` [PATCH 3/3] rust: pin-init: internal: hide `HasPinData` impl Gary Guo
  2 siblings, 0 replies; 4+ messages in thread
From: Gary Guo @ 2026-11-18 14:31 UTC (permalink / raw)
  To: Benno Lossin, Miguel Ojeda, Boqun Feng, Björn Roy Baron,
	Andreas Hindborg, Alice Ryhl, Trevor Gross, Danilo Krummrich,
	Daniel Almeida, Tamir Duberstein, Alexandre Courbot,
	Onur Özkan
  Cc: rust-for-linux, linux-kernel, Gary Guo

From: Gary Guo <gary@garyguo.net>

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 <gary@garyguo.net>
---
 rust/pin-init/internal/src/pin_data.rs | 35 +++++++++++++++----------
 rust/pin-init/internal/src/util.rs     | 47 +++++++++++++++++++++++++++++++++-
 2 files changed, 67 insertions(+), 15 deletions(-)

diff --git a/rust/pin-init/internal/src/pin_data.rs b/rust/pin-init/internal/src/pin_data.rs
index 08e11128d353..bcbdf33f65ae 100644
--- a/rust/pin-init/internal/src/pin_data.rs
+++ b/rust/pin-init/internal/src/pin_data.rs
@@ -13,7 +13,7 @@
     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 #check_name #combined_impl_generics (long: #long_ty) -> #short_ty #whr {
 
 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 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 @@ impl #impl_generics #ident #ty_generics
             /// 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 @@ impl #impl_generics #ident #ty_generics
             /// 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 @@ impl #impl_generics #ident #ty_generics
             /// 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/rust/pin-init/internal/src/util.rs b/rust/pin-init/internal/src/util.rs
index 4d3331b852b4..55ac0586cc56 100644
--- a/rust/pin-init/internal/src/util.rs
+++ b/rust/pin-init/internal/src/util.rs
@@ -6,7 +6,7 @@
 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 @@ fn visit_type_bare_fn_mut(&mut self, bare_fn: &mut syn::TypeBareFn) {
         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 visibility (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 complex, 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
+                }
+            }
+        }
+    }
+}

-- 
2.54.0


^ permalink raw reply	[flat|nested] 4+ messages in thread

* [PATCH 3/3] rust: pin-init: internal: hide `HasPinData` impl
  2026-11-18 14:31 [PATCH 0/3] rust: pin-init: reduce visibility of projection methods to declutter rustdoc Gary Guo
  2026-11-18 14:31 ` [PATCH 1/3] rust: pin-init: internal: allow `clippy::large_unopt_stack_frames` Gary Guo
  2026-11-18 14:31 ` [PATCH 2/3] rust: pin-init: internal: use visibility of the most visible field for projection Gary Guo
@ 2026-11-18 14:31 ` Gary Guo
  2 siblings, 0 replies; 4+ messages in thread
From: Gary Guo @ 2026-11-18 14:31 UTC (permalink / raw)
  To: Benno Lossin, Miguel Ojeda, Boqun Feng, Björn Roy Baron,
	Andreas Hindborg, Alice Ryhl, Trevor Gross, Danilo Krummrich,
	Daniel Almeida, Tamir Duberstein, Alexandre Courbot,
	Onur Özkan
  Cc: rust-for-linux, linux-kernel, Gary Guo

From: Gary Guo <gary@garyguo.net>

`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 <gary@garyguo.net>
---
 rust/pin-init/internal/src/pin_data.rs | 1 +
 1 file changed, 1 insertion(+)

diff --git a/rust/pin-init/internal/src/pin_data.rs b/rust/pin-init/internal/src/pin_data.rs
index bcbdf33f65ae..df1de7b27e1b 100644
--- a/rust/pin-init/internal/src/pin_data.rs
+++ b/rust/pin-init/internal/src/pin_data.rs
@@ -2081,6 +2081,7 @@ impl #impl_generics __ThePinData #ty_generics
 
         // 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
         {

-- 
2.54.0


^ permalink raw reply	[flat|nested] 4+ messages in thread

end of thread, other threads:[~2026-11-18 14:31 UTC | newest]

Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2026-11-18 14:31 [PATCH 0/3] rust: pin-init: reduce visibility of projection methods to declutter rustdoc Gary Guo
2026-11-18 14:31 ` [PATCH 1/3] rust: pin-init: internal: allow `clippy::large_unopt_stack_frames` Gary Guo
2026-11-18 14:31 ` [PATCH 2/3] rust: pin-init: internal: use visibility of the most visible field for projection Gary Guo
2026-11-18 14:31 ` [PATCH 3/3] rust: pin-init: internal: hide `HasPinData` impl Gary Guo

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox

all inboxes | Powered by JetHome®