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

[Philipp Stanner <pstanner@redhat.com>]

On Tue, 2024-12-03 at 15:37 -0600, Bjorn Helgaas wrote:
> 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@redhat.com>
> > ---
> >  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.
> 

Yup, sound like a good idea to me.

(nit: though I would say "name of the driver". But I'm also not a
native English speaker, so..)


P.