mirrors/linux
2
0
Fork 0
mirror of https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git synced 2026-05-16 05:31:37 -04:00
Code Issues Packages Projects Releases Wiki Activity

rust: pin-init: doc: de-clutter documentation with fake-variadics

Browse Source 
Currently the doc for `Zeroable` and `ZeroableOption` are filled with the
generated impl of tuples and fn pointers. Use the internal
"fake_variadics" feature to improve the rendered quality.

This makes use of an internal feature, however this is of minimal risk as
it's for documentation only, not activated during normal build, gated
behind `USE_RUSTC_FEATURES`, and can be removed at any time. This feature
is already used by serde and bevy to improve documentation quality.

For compilers that cannot use this feature, we still hide most generated
impls, and the existence of them are hinted by doc comments on the single
non-hidden impl.

Signed-off-by: Gary Guo <gary@garyguo.net>
Link: 530c4eb79a
[ Reordered `#[doc]` attributes and safety comments to avoid errors in
  older versions of clippy. - Benno ]
Link: https://patch.msgid.link/20260319093542.3756606-4-lossin@kernel.org
Signed-off-by: Benno Lossin <lossin@kernel.org>
This commit is contained in:
Gary Guo
2026-03-19 10:35:26 +01:00
committed by Benno Lossin
parent 960c37cbcb
commit 44f6fa0dce
1 changed files with 18 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
rust/pin-init/src/lib.rs
View File

@@ -276,6 +276,8 @@
all(feature = "unsafe-pinned", CONFIG_RUSTC_HAS_UNSAFE_PINNED),
feature(unsafe_pinned)
)]
#![cfg_attr(all(USE_RUSTC_FEATURES, doc), allow(internal_features))]
#![cfg_attr(all(USE_RUSTC_FEATURES, doc), feature(rustdoc_internals))]
use core::{
cell::UnsafeCell,
@@ -1638,8 +1640,14 @@ macro_rules! impl_zeroable {
}
macro_rules! impl_tuple_zeroable {
($(,)?) => {};
($first:ident, $(,)?) => {
#[cfg_attr(all(USE_RUSTC_FEATURES, doc), doc(fake_variadic))]
/// Implemented for tuples up to 10 items long.
// SAFETY: All elements are zeroable and padding can be zero.
unsafe impl<$first: Zeroable> Zeroable for ($first,) {}
};
($first:ident, $($t:ident),* $(,)?) => {
#[cfg_attr(doc, doc(hidden))]
// SAFETY: All elements are zeroable and padding can be zero.
unsafe impl<$first: Zeroable, $($t: Zeroable),*> Zeroable for ($first, $($t),*) {}
impl_tuple_zeroable!($($t),* ,);
@@ -1654,7 +1662,16 @@ macro_rules! impl_fn_zeroable_option {
$(impl_fn_zeroable_option!({unsafe extern $abi} $args);)*
};
({$($prefix:tt)*} {$(,)?}) => {};
({$($prefix:tt)*} {$ret:ident, $arg:ident $(,)?}) => {
#[cfg_attr(all(USE_RUSTC_FEATURES, doc), doc(fake_variadic))]
/// Implemented for function pointers with up to 20 arity.
// SAFETY: function pointers are part of the option layout optimization:
// <https://doc.rust-lang.org/stable/std/option/index.html#representation>.
unsafe impl<$ret, $arg> ZeroableOption for $($prefix)* fn($arg) -> $ret {}
impl_fn_zeroable_option!({$($prefix)*} {$arg,});
};
({$($prefix:tt)*} {$ret:ident, $($rest:ident),* $(,)?}) => {
#[cfg_attr(doc, doc(hidden))]
// SAFETY: function pointers are part of the option layout optimization:
// <https://doc.rust-lang.org/stable/std/option/index.html#representation>.
unsafe impl<$ret, $($rest),*> ZeroableOption for $($prefix)* fn($($rest),*) -> $ret {}