Re: [PATCH] PCI: Improve parameter docu for request APIs

[Bjorn Helgaas]

On Tue, Dec 03, 2024 at 11:00:24AM +0100, Philipp Stanner wrote:
> PCI region request functions have a @name parameter (sometimes called
> "res_name"). It is used in a log message to inform drivers about request
> collisions, i.e., when another driver has requested that region already.
> 
> This message is only useful when it contains the actual owner of the
> region, i.e., which driver requested it. So far, a great many drivers
> misuse the @name parameter and just pass pci_name(), which doesn't
> result in useful debug information.
> 
> Rename "res_name" to "name".
> 
> Detail @name's purpose in the docstrings.
> 
> Improve formatting a bit.
> 
> Signed-off-by: Philipp Stanner <pstanner@xxxxxxxxxx>
> ---
>  drivers/pci/devres.c | 12 ++++----
>  drivers/pci/pci.c    | 69 +++++++++++++++++++++-----------------------
>  2 files changed, 39 insertions(+), 42 deletions(-)
> 
> diff --git a/drivers/pci/devres.c b/drivers/pci/devres.c
> index 3b59a86a764b..ffaffa880b88 100644
> --- a/drivers/pci/devres.c
> +++ b/drivers/pci/devres.c
> @@ -101,7 +101,7 @@ static inline void pcim_addr_devres_clear(struct pcim_addr_devres *res)
>   * @bar: BAR the range is within
>   * @offset: offset from the BAR's start address
>   * @maxlen: length in bytes, beginning at @offset
> - * @name: name associated with the request
> + * @name: name of the resource requestor

What if we say plainly:

  @name: name of driver requesting the resource

I can tweak this locally if you agree.