Re: [PATCH] virt: acrn: fix kernel-doc in <uapi/linux/acrn.h>

[Randy Dunlap <rdunlap@infradead.org>]

Hi,

On 10/23/25 11:22 PM, Li, Fei1 wrote:
>>
>> Hi,
>>
>> On 10/23/25 11:00 PM, Li, Fei1 wrote:
>>>> From: Randy Dunlap <rdunlap@infradead.org>
>>>> Sent: Friday, October 24, 2025 12:42 PM
>>>> To: linux-kernel@vger.kernel.org
>>>> Cc: Randy Dunlap <rdunlap@infradead.org>; Li, Fei1
>>>> <fei1.li@intel.com>; acrn-dev@lists.projectacrn.org; Greg
>>>> Kroah-Hartman <gregkh@linuxfoundation.org>
>>>> Subject: [PATCH] virt: acrn: fix kernel-doc in <uapi/linux/acrn.h>
>>>>
>>>> Fix the kernel-doc comments for struct acrn_mmiodev so that all
>>>> struct members are rendered correctly.
>>>> Correct io_base to io_addr in struct acrn_vdev.
>>>>
>>>> acrn.h:441: warning: Function parameter or struct member 'res'
>>>>  not described in 'acrn_mmiodev'
>>>> acrn.h:479: warning: Function parameter or struct member 'io_addr'
>>>>  not described in 'acrn_vdev'
>>>> acrn.h:479: warning: Excess struct member 'io_base' description  in
>>>> 'acrn_vdev'
>>>>
>>>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>>>> ---
>>>> Cc: Fei Li <fei1.li@intel.com>
>>>> Cc: acrn-dev@lists.projectacrn.org
>>>> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
>>>> ---
>>>>  include/uapi/linux/acrn.h |   11 ++++++-----
>>>>  1 file changed, 6 insertions(+), 5 deletions(-)
>>>>
>>>> --- linux-next-20251022.orig/include/uapi/linux/acrn.h
>>>> +++ linux-next-20251022/include/uapi/linux/acrn.h
>>>> @@ -420,12 +420,13 @@ struct acrn_pcidev {
>>>>  /**
>>>>   * struct acrn_mmiodev - Info for assigning or de-assigning a MMIO device
>>>>   * @name:			Name of the MMIO device.
>>>> - * @res[].user_vm_pa:		Physical address of User VM of the
>> MMIO
>>>> region
>>>> + * @res:			MMIO resource descriptor info.
>>>
>>> Hi Randy
>>>
>>> Thanks for cooking this patch to help fix these warning.
>>> Could you just add the comment for `res` and keep the other comments for
>> the fields of ` struct acrn_mmiodev ` ?
>>>
>>
>> Do you mean leave the [] square brackets in the field name?
> yes
>> If that's what you mean, that's not valid kernel-doc notation.
> Would you please post the quote how kernel-doc prefer to add this comments ? I didn't see
> an example in the kernel-doc.rst

There is not anything in kernel-doc that indicates arrays
so I can't post a quote that shows that.
The patch shows the preferred kernel-doc here.

>>>> + * @res.user_vm_pa:		Physical address of User VM of the
>> MMIO
>>>> region
>>>>   *				for the MMIO device.
>>>> - * @res[].service_vm_pa:	Physical address of Service VM of the MMIO
>>>> + * @res.service_vm_pa:		Physical address of Service VM of the
>>>> MMIO
>>>>   *				region for the MMIO device.
>>>> - * @res[].size:			Size of the MMIO region for the
>> MMIO
>>>> device.
>>>> - * @res[].mem_type:		Memory type of the MMIO region for
>> the
>>>> MMIO
>>>> + * @res.size:			Size of the MMIO region for the
>> MMIO
>>>> device.
>>>> + * @res.mem_type:		Memory type of the MMIO region for
>> the
>>>> MMIO
>>>>   *				device.
>>>>   *
>>>>   * This structure will be passed to hypervisor directly.
>>>> @@ -449,7 +450,7 @@ struct acrn_mmiodev {
>>>>   * @id.fields.legacy_id:	ID of the virtual device if not a PCI device
>>>>   * @slot:			Virtual Bus/Device/Function of the virtual
>>>>   *				device
>>>> - * @io_base:			IO resource base address of the
>> virtual device
>>>> + * @io_addr:			IO resource base address of the
>> virtual device
>>>>   * @io_size:			IO resource size of the virtual device
>>>>   * @args:			Arguments for the virtual device creation
>>>>   *
>>
>> --
>> ~Randy
> 

-- 
~Randy