Re: [net-next PATCH v8 5/8] net: dsa: realtek: rtl8365mb: add VLAN support

[Luiz Angelo Daros de Luca]

> On Mon, 25 May 2026 16:48:01 -0300 Luiz Angelo Daros de Luca wrote:
> > + * rtl8365mb_vlan_port_get_pvid - Retrieve the port PVID
> > + * @priv: realtek switch private structure
> > + * @port: port index
> > + * @pvid: pointer to store the retrieved VLAN ID
> > + *
> > + * Returns the port PVID if defined or 0 if not.
> > + *
> > + * Context: Can sleep. Takes and releases &priv->map_lock.
> > + * Returns 0 on success or a negative error code on failure.
> > + */
> > +int rtl8365mb_vlan_port_get_pvid(struct realtek_priv *priv, int port, u16 *pvid)
>
> Warning: drivers/net/dsa/realtek/rtl8365mb_vlan.c:686 No description found for return value of 'rtl8365mb_vlan_port_get_pvid'
>
> Personal preference but IMHO use of kdoc on international driver
> functions is plenty pain for little gain. Maybe y'all use more advanced
> code editors or such that makes this useful? For me it's just lots of
> unnecessary metadata and kdoc warning risk, where a normal comment would
> do just fine to convey the information 🤷️


> On Mon, 25 May 2026 16:48:01 -0300 Luiz Angelo Daros de Luca wrote:
> > + * rtl8365mb_vlan_port_get_pvid - Retrieve the port PVID
> > + * @priv: realtek switch private structure
> > + * @port: port index
> > + * @pvid: pointer to store the retrieved VLAN ID
> > + *
> > + * Returns the port PVID if defined or 0 if not.
> > + *
> > + * Context: Can sleep. Takes and releases &priv->map_lock.
> > + * Returns 0 on success or a negative error code on failure.
> > + */
> > +int rtl8365mb_vlan_port_get_pvid(struct realtek_priv *priv, int port, u16 *pvid)
>
> Warning: drivers/net/dsa/realtek/rtl8365mb_vlan.c:686 No description found for return value of 'rtl8365mb_vlan_port_get_pvid'
>
> Personal preference but IMHO use of kdoc on international driver
> functions is plenty pain for little gain. Maybe y'all use more advanced
> code editors or such that makes this useful? For me it's just lots of
> unnecessary metadata and kdoc warning risk, where a normal comment would
> do just fine to convey the information 🤷️

Hello Jakub,

You are right. I'll convert them to normal comments. There is no need
for kdocs here.

It would be a nice addition to b4 to run kernel-doc checks on touched
files during b4 prep --check. I will use this b4 config from now on:

.b4-config:
[b4]
prep-perpatch-check-cmd = awk '/^\\+\\+\\+/ { system(\"[ -f \"
substr($0,7) \" ] && ./scripts/kernel-doc -none \" substr($0,7)) }'
prep-perpatch-check-cmd = ./scripts/checkpatch.pl --terse --no-summary
--mailback --showfile --max-line-length=80

It's a bit of an ugly hack since it always tests the HEAD file, but at
least it forces the check.

Regards,

Luiz