Subject: Re: [patch net-next 05/15] devlink: move port_split/unsplit() ops into devlink_port_ops

From: Jiri Pirko <[email-masked]>
Date: Thu, 25 May 2023 08:05:22 +0200

Thu, May 25, 2023 at 06:53:01AM CEST, [email-masked] wrote:
>On Wed, 24 May 2023 14:18:26 +0200 Jiri Pirko wrote:
>>  /**
>>   * struct devlink_port_ops - Port operations
>> + * @port_split: Callback used to split the port into multiple ones.
>> + * @port_unsplit: Callback used to unsplit the port group back into
>> + *		  a single port.
>>   */
>>  struct devlink_port_ops {
>> +	int (*port_split)(struct devlink *devlink, struct devlink_port *port,
>> +			  unsigned int count, struct netlink_ext_ack *extack);
>> +	int (*port_unsplit)(struct devlink *devlink, struct devlink_port *port,
>> +			    struct netlink_ext_ack *extack);
>>  };
>
>Two random take it or leave it comments: (1) since these are port ops
>now do they need the port_* prefix? (2) I've become partial to adding

Yeah, I'd like to leave them, for grepability purposes.

>the kdoc inline in op structs:
>
>/**
> * struct x - it is the X struct
> */
>struct x {
>	/** @an_op: its an op */
>	int (*an_op)(int arg);
>};
>
>I think it's because every time I look at struct net_device_ops 
>a little part of me gives up.

Does this work? I checked the existing layout of devlink_ops and the
internal comments are ignored by kdoc. Actually the whole devlink_ops
struct is omitted in kdoc. See:
$ scripts/kernel-doc include/net/devlink.h

I followed the format we have for the other ops structures in devlink.h
which works with kernel-doc script.