linux-kernel - Re: [PATCH] platform/mellanox: tmfifo: fix kernel-doc warnings

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Sat, 30 Sep 2023 18:07:55 -0700
From:   Randy Dunlap <rdunlap@...radead.org>
To:     Ilpo Järvinen <ilpo.jarvinen@...ux.intel.com>
Cc:     LKML <linux-kernel@...r.kernel.org>,
        kernel test robot <lkp@...el.com>,
        Liming Sun <lsun@...lanox.com>,
        Hans de Goede <hdegoede@...hat.com>,
        Mark Gross <markgross@...nel.org>,
        Vadim Pasternak <vadimp@...dia.com>,
        platform-driver-x86@...r.kernel.org,
        Mauro Carvalho Chehab <mchehab@...nel.org>
Subject: Re: [PATCH] platform/mellanox: tmfifo: fix kernel-doc warnings

Hi,

On 9/26/23 09:18, Ilpo Järvinen wrote:
> On Mon, 25 Sep 2023, Randy Dunlap wrote:
> 
>> Fix kernel-doc notation for structs and struct members to prevent
>> these warnings:
>>
>> mlxbf-tmfifo.c:73: warning: cannot understand function prototype: 'struct mlxbf_tmfifo_vring '
>> mlxbf-tmfifo.c:128: warning: cannot understand function prototype: 'struct mlxbf_tmfifo_vdev '
>> mlxbf-tmfifo.c:146: warning: cannot understand function prototype: 'struct mlxbf_tmfifo_irq_info '
>> mlxbf-tmfifo.c:158: warning: cannot understand function prototype: 'struct mlxbf_tmfifo_io '
>> mlxbf-tmfifo.c:182: warning: cannot understand function prototype: 'struct mlxbf_tmfifo '
>> mlxbf-tmfifo.c:208: warning: cannot understand function prototype: 'struct mlxbf_tmfifo_msg_hdr '
>> mlxbf-tmfifo.c:138: warning: Function parameter or member 'config' not described in 'mlxbf_tmfifo_vdev'
>> mlxbf-tmfifo.c:212: warning: Function parameter or member 'unused' not described in 'mlxbf_tmfifo_msg_hdr'
>>
>> Fixes: 1357dfd7261f ("platform/mellanox: Add TmFifo driver for Mellanox BlueField Soc")
>> Fixes: bc05ea63b394 ("platform/mellanox: Add BlueField-3 support in the tmfifo driver")
>> Signed-off-by: Randy Dunlap <rdunlap@...radead.org>
>> Reported-by: kernel test robot <lkp@...el.com>
>> Closes: lore.kernel.org/r/202309252330.saRU491h-lkp@...el.com
>> Cc: Liming Sun <lsun@...lanox.com>
>> Cc: Hans de Goede <hdegoede@...hat.com>
>> Cc: Ilpo Järvinen <ilpo.jarvinen@...ux.intel.com>
>> Cc: Mark Gross <markgross@...nel.org>
>> Cc: Vadim Pasternak <vadimp@...dia.com>
>> Cc: platform-driver-x86@...r.kernel.org
>> ---
>>  drivers/platform/mellanox/mlxbf-tmfifo.c |   14 ++++++++------
>>  1 file changed, 8 insertions(+), 6 deletions(-)
>>
>> diff -- a/drivers/platform/mellanox/mlxbf-tmfifo.c b/drivers/platform/mellanox/mlxbf-tmfifo.c
>> --- a/drivers/platform/mellanox/mlxbf-tmfifo.c
>> +++ b/drivers/platform/mellanox/mlxbf-tmfifo.c
>> @@ -53,7 +53,7 @@
>>  struct mlxbf_tmfifo;
>>  
>>  /**
>> - * mlxbf_tmfifo_vring - Structure of the TmFifo virtual ring
>> + * struct mlxbf_tmfifo_vring - Structure of the TmFifo virtual ring
>>   * @va: virtual address of the ring
>>   * @dma: dma address of the ring
>>   * @vq: pointer to the virtio virtqueue
>> @@ -113,12 +113,13 @@ enum {
>>  };
>>  
>>  /**
>> - * mlxbf_tmfifo_vdev - Structure of the TmFifo virtual device
>> + * struct mlxbf_tmfifo_vdev - Structure of the TmFifo virtual device
>>   * @vdev: virtio device, in which the vdev.id.device field has the
>>   *        VIRTIO_ID_xxx id to distinguish the virtual device.
>>   * @status: status of the device
>>   * @features: supported features of the device
>>   * @vrings: array of tmfifo vrings of this device
>> + * @config: non-anonymous union for cons and net
> 
> I wonder what information this adds? It's not documenting anything else 
> than C syntax, IMO.
> 
> Would it be possible to make kerneldoc not give warning from a named union 
> which is already fully documented?

I don't know. Maybe.
I have no idea if anyone has ever looked into doing that.

I'm adding Mauro since he did the nested struct/union kernel-doc code.

~Randy