[2/5] thunderbolt: eeprom: Fix kernel-doc descriptions of non-static functions

Fix kernel-doc descriptions of the two non-static functions. This also
gets rid of the rest of the warnings on W=1 build.

Reported-by: Lee Jones <lee.jones@linaro.org>
Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
---
 drivers/thunderbolt/eeprom.c | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

On Thu, Jan 28, 2021 at 01:11:11PM +0000, Lee Jones wrote:
> On Thu, 28 Jan 2021, Mika Westerberg wrote:
> 
> > Fix kernel-doc descriptions of the two non-static functions. This also
> > gets rid of the rest of the warnings on W=1 build.
> > 
> > Reported-by: Lee Jones <lee.jones@linaro.org>
> > Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
> > ---
> >  drivers/thunderbolt/eeprom.c | 13 +++++++++++--
> >  1 file changed, 11 insertions(+), 2 deletions(-)
> > 
> > diff --git a/drivers/thunderbolt/eeprom.c b/drivers/thunderbolt/eeprom.c
> > index 63c64f503faa..dd03d3096653 100644
> > --- a/drivers/thunderbolt/eeprom.c
> > +++ b/drivers/thunderbolt/eeprom.c
> > @@ -279,7 +279,9 @@ struct tb_drom_entry_port {
> >  
> >  
> >  /**
> > - * tb_drom_read_uid_only - read uid directly from drom
> > + * tb_drom_read_uid_only() - Read UID directly from DROM
> 
> Just an FYI: the '()' aren't required per say.

Right. I have been using them in this driver so I thought it is good
idea to add them here too while at it.

> > + * @sw: Router whose UID to read
> > + * @uid: UID is placed here
> >   *
> >   * Does not use the cached copy in sw->drom. Used during resume to check switch
> >   * identity.
> > @@ -520,7 +522,14 @@ static int tb_drom_read_n(struct tb_switch *sw, u16 offset, u8 *val,
> >  }
> >  
> >  /**
> > - * tb_drom_read - copy drom to sw->drom and parse it
> > + * tb_drom_read() - Copy DROM to sw->drom and parse it
> > + * @sw: Router whose DROM to read and parse
> > + *
> > + * This function reads router DROM and if successful parses the entries and
> > + * populates the fields in @sw accordingly. Can be called for any router
> > + * generation.
> > + *
> > + * Returns %0 in case of success and negative errno otherwise.
> 
> What's %0?

It is 0 but marked as "constant" in the output.

> 
> >   */
> >  int tb_drom_read(struct tb_switch *sw)
> >  {
> 
> -- 
> Lee Jones [李琼斯]
> Senior Technical Lead - Developer Services
> Linaro.org │ Open source software for Arm SoCs
> Follow Linaro: Facebook | Twitter | Blog

On Thu, Jan 28, 2021 at 03:29:31PM +0300, Mika Westerberg wrote:
>  /**
> - * tb_drom_read - copy drom to sw->drom and parse it
> + * tb_drom_read() - Copy DROM to sw->drom and parse it
> + * @sw: Router whose DROM to read and parse
> + *
> + * This function reads router DROM and if successful parses the entries and
> + * populates the fields in @sw accordingly. Can be called for any router
> + * generation.
> + *
> + * Returns %0 in case of success and negative errno otherwise.
>   */
>  int tb_drom_read(struct tb_switch *sw)
>  {

I'm confused by the terminology change of "router" vs. "switch".
Is this change mandated by USB4?

The parameter is a tb_switch, so calling it a router looks a little odd.

Thanks,

Lukas

Hi,

On Thu, Jan 28, 2021 at 09:57:19PM +0100, Lukas Wunner wrote:
> On Thu, Jan 28, 2021 at 03:29:31PM +0300, Mika Westerberg wrote:

> >  /**

> > - * tb_drom_read - copy drom to sw->drom and parse it

> > + * tb_drom_read() - Copy DROM to sw->drom and parse it

> > + * @sw: Router whose DROM to read and parse

> > + *

> > + * This function reads router DROM and if successful parses the entries and

> > + * populates the fields in @sw accordingly. Can be called for any router

> > + * generation.

> > + *

> > + * Returns %0 in case of success and negative errno otherwise.

> >   */

> >  int tb_drom_read(struct tb_switch *sw)

> >  {

> 

> I'm confused by the terminology change of "router" vs. "switch".

> Is this change mandated by USB4?


Not mandated.

> The parameter is a tb_switch, so calling it a router looks a little odd.


Right. I'm trying to use the "new" terminology in the comments so that
people reading those might be able to match it better with the spec.
Even though in code we still have tb_switch, tb_port etc. Perhaps we can
mention in kernel-docs of struct tb_switch and others the corresponding
USB4 spec term?