In particular:

  - Add missing Markdown code spans.

  - Improve title for `DeviceId`, adding a link to the struct in the
    C side, rather than referring to `bindings::`.

  - Convert `TODO` from documentation to a normal comment, and put code
    in block.

This was found using the Clippy `doc_markdown` lint, which we may want
to enable.

Fixes: 1bd8b6b2c5d3 ("rust: pci: add basic PCI device / driver abstractions")
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
---
 rust/kernel/pci.rs | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/rust/kernel/pci.rs b/rust/kernel/pci.rs
index f7b2743828ae..99413607c2b6 100644
--- a/rust/kernel/pci.rs
+++ b/rust/kernel/pci.rs
@@ -115,7 +115,9 @@ macro_rules! module_pci_driver {
 };
 }

-/// Abstraction for bindings::pci_device_id.
+/// Abstraction for the PCI device ID structure ([`pci_device_id`]).
+///
+/// [`pci_device_id`]: https://docs.kernel.org/PCI/pci.html#c.pci_device_id
 #[repr(transparent)]
 #[derive(Clone, Copy)]
 pub struct DeviceId(bindings::pci_device_id);
@@ -170,7 +172,7 @@ fn index(&self) -> usize {
     }
 }

-/// IdTable type for PCI
+/// `IdTable` type for PCI.
 pub type IdTable<T> = &'static dyn kernel::device_id::IdTable<DeviceId, T>;

 /// Create a PCI `IdTable` with its alias for modpost.
@@ -221,10 +223,11 @@ macro_rules! pci_device_table {
 /// `Adapter` documentation for an example.
 pub trait Driver {
     /// The type holding information about each device id supported by the driver.
-    ///
-    /// TODO: Use associated_type_defaults once stabilized:
-    ///
-    /// type IdInfo: 'static = ();
+    // TODO: Use `associated_type_defaults` once stabilized:
+    //
+    // ```
+    // type IdInfo: 'static = ();
+    // ```
     type IdInfo: 'static;

     /// The table of device ids supported by the driver.
--
2.49.0

On Mon Mar 24, 2025 at 10:03 PM CET, Miguel Ojeda wrote:
> diff --git a/rust/kernel/pci.rs b/rust/kernel/pci.rs
> index f7b2743828ae..99413607c2b6 100644
> --- a/rust/kernel/pci.rs
> +++ b/rust/kernel/pci.rs
> @@ -115,7 +115,9 @@ macro_rules! module_pci_driver {
>  };
>  }
>
> -/// Abstraction for bindings::pci_device_id.
> +/// Abstraction for the PCI device ID structure ([`pci_device_id`]).

Wouldn't "([`struct pci_device_id`])" make more sense?

---
Cheers,
Benno

> +///
> +/// [`pci_device_id`]: https://docs.kernel.org/PCI/pci.html#c.pci_device_id
>  #[repr(transparent)]
>  #[derive(Clone, Copy)]
>  pub struct DeviceId(bindings::pci_device_id);

On Mon, Mar 24, 2025 at 11:54 PM Benno Lossin <benno.lossin@proton.me> wrote:
>
> Wouldn't "([`struct pci_device_id`])" make more sense?

Yeah, definitely, it should have the `struct` to be consistent with
our usual style.

Cheers,
Miguel