From: Jakub Kicinski <kuba@kernel.org>
To: Oleksij Rempel <o.rempel@pengutronix.de>
Cc: "Russell King (Oracle)" <linux@armlinux.org.uk>,
Paolo Abeni <pabeni@redhat.com>,
"David S. Miller" <davem@davemloft.net>,
Eric Dumazet <edumazet@google.com>,
Andrew Lunn <andrew+netdev@lunn.ch>,
Heiner Kallweit <hkallweit1@gmail.com>,
Jonathan Corbet <corbet@lwn.net>,
kernel@pengutronix.de, linux-kernel@vger.kernel.org,
netdev@vger.kernel.org, Simon Horman <horms@kernel.org>,
Maxime Chevallier <maxime.chevallier@bootlin.com>,
linux-doc@vger.kernel.org
Subject: Re: [PATCH net-next v1 1/1] net: phy: Move callback comments from struct to kernel-doc section
Date: Tue, 17 Dec 2024 07:03:11 -0800 [thread overview]
Message-ID: <20241217070311.1c867d32@kernel.org> (raw)
In-Reply-To: <Z2EO45xuUkzlw-Uy@pengutronix.de>
On Tue, 17 Dec 2024 06:40:51 +0100 Oleksij Rempel wrote:
> > > Please rephrase, I do not understand.
> > >
> > > Should I resend this patch with corrected "Return:" description, or
> > > continue with inlined comments withing the struct and drop this patch?
> >
> > I'm not talking about Returns, I'm talking about the core idea of
> > the patch. The duplicate definitions seem odd, can we teach kernel-doc
> > to understand function args instead? Most obvious format which comes
> > to mind:
> >
> > * ...
> > * @config_init - Initialize the PHY, including after a reset.
> > * @config_init.phydev: The PHY device to initialize.
> > *
> > * Returns: 0 on success or a negative error code on failure.
> > * ...
>
> It will be too many side quests to me for now. I can streamline comments
> if there is agreement how it should look like. But fixing kdoc - I would leave
> it to the experts.
>
> What do you prefer, proceed with stats patch without fixing comments or
> fix comment without fixing kdoc?
The former. And you're using the word "fix" very loosely here, IMHO.
next prev parent reply other threads:[~2024-12-17 15:03 UTC|newest]
Thread overview: 14+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-12-06 11:39 [PATCH net-next v1 1/1] net: phy: Move callback comments from struct to kernel-doc section Oleksij Rempel
2024-12-06 12:14 ` Russell King (Oracle)
2024-12-07 20:38 ` Andrew Lunn
2024-12-10 11:56 ` Paolo Abeni
2024-12-10 14:02 ` Russell King (Oracle)
2024-12-10 14:37 ` Jakub Kicinski
2024-12-16 12:20 ` Oleksij Rempel
2024-12-17 1:53 ` Jakub Kicinski
2024-12-17 5:40 ` Oleksij Rempel
2024-12-17 15:03 ` Jakub Kicinski [this message]
2025-01-02 16:56 ` Russell King (Oracle)
2025-01-02 18:01 ` Jonathan Corbet
2025-01-02 18:28 ` Russell King (Oracle)
2024-12-10 12:03 ` Mateusz Polchlopek
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20241217070311.1c867d32@kernel.org \
--to=kuba@kernel.org \
--cc=andrew+netdev@lunn.ch \
--cc=corbet@lwn.net \
--cc=davem@davemloft.net \
--cc=edumazet@google.com \
--cc=hkallweit1@gmail.com \
--cc=horms@kernel.org \
--cc=kernel@pengutronix.de \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux@armlinux.org.uk \
--cc=maxime.chevallier@bootlin.com \
--cc=netdev@vger.kernel.org \
--cc=o.rempel@pengutronix.de \
--cc=pabeni@redhat.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.