rust: kernel: clean Rust 1.66.0 rustdoc::broken_intra_doc_links warnings

Since Rust 1.63.0, `rustdoc` complains with `broken_intra_doc_links`
about intra-doc links pointing to exported `macro_rules`, e.g.:

    error: unresolved link to `dev_info`
       --> rust/kernel/device.rs:135:43
        |
    135 |     /// More details are available from [`dev_info`].
        |                                           ^^^^^^^^ no item named `dev_info` in scope
        |
        = note: `macro_rules` named `dev_info` exists in this crate, but it is not in scope at this link's location
        = note: `-D rustdoc::broken-intra-doc-links` implied by `-D warnings`

    error: aborting due to previous error

The text is confusing, because the link still gets generated, and previous versions
(<= 1.62) did not warn and also generated the link. This was reported
upstream at [1], and it turns out that the link still being generated was
a compatibility measure for docs.rs, which may get removed soon. Thus
the intended behavior is that the user specifies the proper path.

Therefore, clean up the `allow()`s introduced earlier to satisfy `rustdoc`
and the new behavior.

Link: rust-lang/rust#106142 [1]
Reviewed-by: Björn Roy Baron <[email protected]>
Reviewed-by: Martin Rodriguez Reboredo <[email protected]>
Tested-by: Martin Rodriguez Reboredo <[email protected]>
Reviewed-by: Gary Guo <[email protected]>
Reviewed-by: Vincenzo Palazzo <[email protected]>
Reviewed-by: Alice Ferrazzi <[email protected]>
Tested-by: Alice Ferrazzi <[email protected]>
Reviewed-by: Neal Gompa <[email protected]>
Tested-by: Neal Gompa <[email protected]>
Signed-off-by: Miguel Ojeda <[email protected]>

Author: ojeda

rust/kernel/build_assert.rs

@@ -68,7 +68,8 @@ macro_rules! build_error {
 ///     assert!(n > 1); // Run-time check
 /// }
 /// ```
-#[allow(rustdoc::broken_intra_doc_links)]
+///
+/// [`static_assert!`]: crate::static_assert!
 #[macro_export]
 macro_rules! build_assert {
     ($cond:expr $(,)?) => {{

rust/kernel/device.rs

@@ -73,7 +73,8 @@ pub unsafe trait RawDevice {
     /// Prints an emergency-level message (level 0) prefixed with device information.
     ///
     /// More details are available from [`dev_emerg`].
-    #[allow(rustdoc::broken_intra_doc_links)]
+    ///
+    /// [`dev_emerg`]: crate::dev_emerg
     fn pr_emerg(&self, args: fmt::Arguments<'_>) {
         // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
         unsafe { self.printk(bindings::KERN_EMERG, args) };
@@ -82,7 +83,8 @@ pub unsafe trait RawDevice {
     /// Prints an alert-level message (level 1) prefixed with device information.
     ///
     /// More details are available from [`dev_alert`].
-    #[allow(rustdoc::broken_intra_doc_links)]
+    ///
+    /// [`dev_alert`]: crate::dev_alert
     fn pr_alert(&self, args: fmt::Arguments<'_>) {
         // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
         unsafe { self.printk(bindings::KERN_ALERT, args) };
@@ -91,7 +93,8 @@ pub unsafe trait RawDevice {
     /// Prints a critical-level message (level 2) prefixed with device information.
     ///
     /// More details are available from [`dev_crit`].
-    #[allow(rustdoc::broken_intra_doc_links)]
+    ///
+    /// [`dev_crit`]: crate::dev_crit
     fn pr_crit(&self, args: fmt::Arguments<'_>) {
         // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
         unsafe { self.printk(bindings::KERN_CRIT, args) };
@@ -100,7 +103,8 @@ pub unsafe trait RawDevice {
     /// Prints an error-level message (level 3) prefixed with device information.
     ///
     /// More details are available from [`dev_err`].
-    #[allow(rustdoc::broken_intra_doc_links)]
+    ///
+    /// [`dev_err`]: crate::dev_err
     fn pr_err(&self, args: fmt::Arguments<'_>) {
         // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
         unsafe { self.printk(bindings::KERN_ERR, args) };
@@ -109,7 +113,8 @@ pub unsafe trait RawDevice {
     /// Prints a warning-level message (level 4) prefixed with device information.
     ///
     /// More details are available from [`dev_warn`].
-    #[allow(rustdoc::broken_intra_doc_links)]
+    ///
+    /// [`dev_warn`]: crate::dev_warn
     fn pr_warn(&self, args: fmt::Arguments<'_>) {
         // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
         unsafe { self.printk(bindings::KERN_WARNING, args) };
@@ -118,7 +123,8 @@ pub unsafe trait RawDevice {
     /// Prints a notice-level message (level 5) prefixed with device information.
     ///
     /// More details are available from [`dev_notice`].
-    #[allow(rustdoc::broken_intra_doc_links)]
+    ///
+    /// [`dev_notice`]: crate::dev_notice
     fn pr_notice(&self, args: fmt::Arguments<'_>) {
         // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
         unsafe { self.printk(bindings::KERN_NOTICE, args) };
@@ -127,7 +133,8 @@ pub unsafe trait RawDevice {
     /// Prints an info-level message (level 6) prefixed with device information.
     ///
     /// More details are available from [`dev_info`].
-    #[allow(rustdoc::broken_intra_doc_links)]
+    ///
+    /// [`dev_info`]: crate::dev_info
     fn pr_info(&self, args: fmt::Arguments<'_>) {
         // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
         unsafe { self.printk(bindings::KERN_INFO, args) };
@@ -136,7 +143,8 @@ pub unsafe trait RawDevice {
     /// Prints a debug-level message (level 7) prefixed with device information.
     ///
     /// More details are available from [`dev_dbg`].
-    #[allow(rustdoc::broken_intra_doc_links)]
+    ///
+    /// [`dev_dbg`]: crate::dev_dbg
     fn pr_dbg(&self, args: fmt::Arguments<'_>) {
         if cfg!(debug_assertions) {
             // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.

rust/kernel/fs/param.rs

@@ -275,7 +275,8 @@ impl<const N: usize, S: 'static> SpecArray<N, S> {
     /// The type of the elements in `handlers` must be compatible with the types in specs. For
     /// example, if `specs` declares that the i-th element is a bool then the i-th handler
     /// should be for a bool.
-    #[allow(rustdoc::broken_intra_doc_links)]
+    ///
+    /// [`define_fs_params`]: crate::define_fs_params
     pub const unsafe fn new(specs: [Spec; N], handlers: [&'static dyn Handler<S>; N]) -> Self {
         let mut array = Self {
             specs: [ZERO_SPEC; N],
@@ -314,7 +315,8 @@ impl<const N: usize, S: 'static> SpecArray<N, S> {
 ///
 /// Users are encouraged to use the [`define_fs_params`] macro to define the
 /// [`super::Context::PARAMS`] constant.
-#[allow(rustdoc::broken_intra_doc_links)]
+///
+/// [`define_fs_params`]: crate::define_fs_params
 pub struct SpecTable<'a, S: 'static> {
     pub(super) first: &'a bindings::fs_parameter_spec,
     pub(super) handlers: &'a [&'static dyn Handler<S>],
@@ -343,7 +345,8 @@ impl<const N: usize> ConstantArray<N> {
     ///
     /// Users are encouraged to use the [`define_fs_params`] macro to define the
     /// [`super::Context::PARAMS`] constant.
-    #[allow(rustdoc::broken_intra_doc_links)]
+    ///
+    /// [`define_fs_params`]: crate::define_fs_params
     pub const fn new(consts: [(&'static CStr, u32); N]) -> Self {
         const ZERO: bindings::constant_table = bindings::constant_table {
             name: core::ptr::null(),

rust/kernel/gpio.rs

@@ -120,7 +120,8 @@ impl<T: Chip> Registration<T> {
     ///
     /// Users are encouraged to use the [`gpio_chip_register`] macro because it automatically
     /// defines the lock classes and calls the registration function.
-    #[allow(rustdoc::broken_intra_doc_links)]
+    ///
+    /// [`gpio_chip_register`]: crate::gpio_chip_register
     pub fn register(
         self: Pin<&mut Self>,
         gpio_count: u16,
@@ -343,7 +344,8 @@ mod irqchip {
         ///
         /// Users are encouraged to use the [`gpio_irq_chip_register`] macro because it
         /// automatically defines the lock classes and calls the registration function.
-        #[allow(rustdoc::broken_intra_doc_links)]
+        ///
+        /// [`gpio_irq_chip_register`]: crate::gpio_irq_chip_register
         pub fn register<U: irq::Chip<Data = T::Data>>(
             mut self: Pin<&mut Self>,
             gpio_count: u16,

rust/kernel/std_vendor.rs

@@ -133,9 +133,9 @@
 /// ```
 ///
 /// [`std::dbg`]: https://doc.rust-lang.org/std/macro.dbg.html
+/// [`pr_info`]: crate::pr_info
 /// [`eprintln`]: https://doc.rust-lang.org/std/macro.eprintln.html
 /// [`printk`]: https://www.kernel.org/doc/html/latest/core-api/printk-basics.html
-#[allow(rustdoc::broken_intra_doc_links)]
 #[macro_export]
 macro_rules! dbg {
     // NOTE: We cannot use `concat!` to make a static string as a format argument