Re: [PATCH] pci: pci-stub fix kernel-doc warnings

["Ilpo Järvinen" <ilpo.jarvinen@linux.intel.com>]

On Mon, 22 Dec 2025, Roman Shlyakhov wrote:

> Fix kernel-doc warnings reported by kernel test robot:
> 
> Warning: drivers/pci/pci-stub.c:55 This comment starts with '/**',
> 	but isn't a kernel-doc comment.
> Warning: drivers/pci/pci-stub.c:122 This comment starts with '/**',
> 	but isn't a kernel-doc comment.
> Warning: drivers/pci/pci-stub.c:148 This comment starts with '/**',
> 	but isn't a kernel-doc comment.
> Warning: drivers/pci/pci-stub.c:207 This comment starts with '/**',
> 	but isn't a kernel-doc comment.
> Warning: drivers/pci/pci-stub.c:222 This comment starts with '/**',
> 	but isn't a kernel-doc comment.
> 
> Convert incorrect /** comments to proper kernel-doc format or
> regular /* comments as required by Documentation/doc-guide/kernel-doc.rst.
> 
> Reported-by: kernel test robot <lkp@intel.com>
> Closes: https://lore.kernel.org/oe-kbuild-all/202512202126.F1IQYL9V-lkp@intel.com/
> Signed-off-by: Roman Shlyakhov <roman.shlyakhov.rs@gmail.com>
> ---
>  drivers/pci/pci-stub.c | 58 ++++++++++++++++++++++++++++++++++--------
>  1 file changed, 48 insertions(+), 10 deletions(-)
> 
> diff --git a/drivers/pci/pci-stub.c b/drivers/pci/pci-stub.c
> index 3ca5e11c3939..fdeed328080e 100644
> --- a/drivers/pci/pci-stub.c
> +++ b/drivers/pci/pci-stub.c
> @@ -27,6 +27,14 @@
>  
>  static char ids[1024] __initdata;
>  
> +/**
> + * struct pci_stub_busid - represents a PCI BUSID for stub driver binding
> + * @domain: PCI domain (if domain_specified is true)
> + * @bus: PCI bus number
> + * @device: PCI device/slot number
> + * @function: PCI function number
> + * @domain_specified: true if domain was explicitly specified in BUSID
> + */
>  struct pci_stub_busid {
>  	unsigned int domain;
>  	unsigned int bus;
> @@ -52,8 +60,11 @@ MODULE_PARM_DESC(ids, "Initial PCI IDs to add to the stub driver, format is "
>  		"\"vendor:device[:subvendor[:subdevice[:class[:class_mask]]]]\""
>  		" and multiple comma separated entries can be specified");
>  
> -/**
> - * Checking if the PCI device matches the BUSID list.
> +/*

Didn't you just make this kerneldoc compatible so why only /* ?

> + * pci_stub_find_busid - Check if the PCI device matches the BUSID list
> + * @dev: PCI device to check
> + *
> + * Return: pointer to matching pci_stub_busid if found, NULL otherwise

Add . (+same comment to return entries below)

>   */
>  static struct pci_stub_busid *pci_stub_find_busid(struct pci_dev *dev)
>  {
> @@ -81,6 +92,13 @@ static struct pci_stub_busid *pci_stub_find_busid(struct pci_dev *dev)
>  	return NULL;
>  }
>  
> +/**
> + * pci_stub_probe - Probe function for pci-stub driver
> + * @dev: PCI device being probed
> + * @id: matching PCI device ID if any
> + *
> + * Return: 0 on successful claim, -ENODEV otherwise
> + */
>  static int pci_stub_probe(struct pci_dev *dev, const struct pci_device_id *id)
>  {
>  	struct pci_stub_busid *busid = pci_stub_find_busid(dev);
> @@ -120,7 +138,15 @@ static struct pci_driver stub_driver = {
>  };
>  
>  /**
> - * Parsing a single BUSID.
> + * pci_stub_parse_one_busid - Parse a single BUSID string
> + * @str: BUSID string to parse
> + * @busid: pointer to pci_stub_busid structure to fill
> + *
> + * Formats accepted:
> + * - with domain: "DDDD:BB:DD.F"
> + * - without domain: "BB:DD.F"
> + *
> + * Return: 0 on success, -EINVAL on parse error
>   */
>  static int pci_stub_parse_one_busid(const char *str, struct pci_stub_busid *busid)
>  {
> @@ -145,8 +171,10 @@ static int pci_stub_parse_one_busid(const char *str, struct pci_stub_busid *busi
>  	return 0;
>  }
>  
> -/**
> - * Parsing the "busid" kernel parameter.
> +/*

Here too, isn't this not kernel doc compatible?

(Did you perhaps start this patch with one approach and then made the 
comments kerneldoc compatible later and forgot to add the second * back?)

There are two more similar case below.

> + * pci_stub_parse_busid_param - Parse the "busid" kernel parameter
> + *
> + * Parses comma-separated list of BUSIDs and registers them for binding.
>   */
>  static void __init pci_stub_parse_busid_param(void)
>  {
> @@ -205,7 +233,11 @@ static void __init pci_stub_parse_busid_param(void)
>  }
>  
>  /**
> - * early_param "pci_stub_busid" handler for the built-in module.
> + * pci_stub_early_param - early_param handler for "pci_stub_busid"
> + * @str: BUSID list parameter value
> + *
> + * This function is called during early boot to parse BUSID list.
> + * Return: 0 on success
>   */
>  static int __init pci_stub_early_param(char *str)
>  {
> @@ -219,8 +251,11 @@ static int __init pci_stub_early_param(char *str)
>  
>  early_param("pci_stub_busid", pci_stub_early_param);
>  
> -/**
> - * Binding devices by BUSID via dynamic IDs.
> +/*
> + * pci_stub_bind_free_devices - Bind devices by BUSID via dynamic IDs
> + *
> + * Attempts to bind all PCI devices matching registered BUSIDs to pci-stub
> + * driver using dynamic IDs.
>   */
>  static void __init pci_stub_bind_free_devices(void)
>  {
> @@ -285,8 +320,11 @@ static void __init pci_stub_bind_free_devices(void)
>  	pr_info("pci-stub: bound %d device(s), skipped %d\n", bound, skipped);
>  }
>  
> -/**
> - * Checking the final binding state.
> +/*
> + * pci_stub_verify_bindings - Check the final binding state
> + *
> + * Verifies which devices from BUSID list are bound to pci-stub,
> + * bound to other drivers, or not bound at all.
>   */
>  static void __init pci_stub_verify_bindings(void)
>  {
> 

-- 
 i.