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

[Lee Jones <lee.jones@linaro.org>]

On Thu, 28 Jan 2021, Mika Westerberg wrote:

> 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.

Interesting.  I wonder what it actually does.

Not sure if it's just my eyes playing me up, but is the font slightly
different for items marked as const:

 mm/memblock.c: https://www.kernel.org/doc/html/latest/core-api/boot-time-mm.html

Anyway, either way:

Reviewed-by: Lee Jones <lee.jones@linaro.org>

-- 
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog