On 2/27/26 2:20 AM, Ilya Maximets wrote:
> On 2/27/26 6:42 AM, Randy Dunlap wrote:
>>
>>
>> On 2/26/26 2:57 PM, Ilya Maximets wrote:
>>> On 2/26/26 11:10 PM, Randy Dunlap wrote:
>>>> Fix some kernel-doc warnings in openvswitch.h:
>>>>
>>>> Mark enum placeholders that are not used as "private" so that kernel-doc
>>>> comments are not needed for them.
>>>>
>>>> Correct names for 2 enum values:
>>>> Warning: include/uapi/linux/openvswitch.h:300 Excess enum value
>>>> '@OVS_VPORT_UPCALL_SUCCESS' description in 'ovs_vport_upcall_attr'
>>>> Warning: include/uapi/linux/openvswitch.h:300 Excess enum value
>>>> '@OVS_VPORT_UPCALL_FAIL' description in 'ovs_vport_upcall_attr'
>>>>
>>>> Warning: include/uapi/linux/openvswitch.h:638 This comment starts with
>>>> '/**', but isn't a kernel-doc comment.
>>>> * Omit attributes for notifications.
>>>>
>>>> Signed-off-by: Randy Dunlap <[email protected]>
>>>> ---
>>>
>>> Hi, Randy. Thanks for the fixes!
>>>
>>> If the private/public is the style to follow, it sounds good to me,
>>> though there seem to be an inconsistency in how the kernel-only
>>> attributes are marked. I see the OVS_SAMPLE_ATTR_ARG is in the
>>> private section, but OVS_CHECK_PKT_LEN_ATTR_ARG and the
>>> OVS_ACTION_ATTR_SET_TO_MASKED are public. They should either all
>>> be public or all private, as they are used for very similar purposes,
>>> which is storing extra information about the action to make it easier
>>> for the kernel to work with them. These attributes should never be
>>> used in the communication with userspace. So, maybe private?
>>
>> I documented them and made them all public:.
>
> OK.
>
>>
>>>
>>> __OVS_CHECK_PKT_LEN_ATTR_MAX is also public for some reason. I guess,
>>> it is because while it has kernel-doc-style comment, it doesn't start
>>> with /**, so it's not treated like one. Maybe we should fix that here
>>> just to be consistent?
>>
>> I didn't follow the "it doesn't start with /**", but I made it private:.
>
> The point was that the comment for the 'enum ovs_check_pkt_len_attr'
> starts with the regular '/*' and not the kernel-doc standard '/**'.
> So I assumed that's the reason why it was missed.
I had already converted that enum to kernel-doc.
> Looking more closely, the same applies also to the
> 'struct ovs_action_push_eth', that documents a filed it doesn't have...
>
and now I have also converted that one.
>>
>>> note: Some enums and structures do not have kernel-doc comments, so
>>> I guess that's the reason to not mark them. I suppose it's fine,
>>> since adding extra docs is not the purpose of this patch.
>>
>> I ended up adding comments for several enums, but you might want to correct
>> a few of them.
>
> Sure.
thanks.
--
~Randy
_______________________________________________
dev mailing list
[email protected]
https://mail.openvswitch.org/mailman/listinfo/ovs-dev
