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

[Randy Dunlap]

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@xxxxxxxxxxxxx>
>> Reported-by: kernel test robot <lkp@xxxxxxxxx>
>> Closes: lore.kernel.org/r/202309252330.saRU491h-lkp@xxxxxxxxx
>> Cc: Liming Sun <lsun@xxxxxxxxxxxx>
>> Cc: Hans de Goede <hdegoede@xxxxxxxxxx>
>> Cc: Ilpo Järvinen <ilpo.jarvinen@xxxxxxxxxxxxxxx>
>> Cc: Mark Gross <markgross@xxxxxxxxxx>
>> Cc: Vadim Pasternak <vadimp@xxxxxxxxxx>
>> Cc: platform-driver-x86@xxxxxxxxxxxxxxx
>> ---
>>  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