From: Randy Dunlap <hidden> Date: 2021-11-10 22:53:14
Do not use "/**" to begin a comment that is not in kernel-doc format.
Prevents this docs build warning:
drivers/ptp/ptp_clockmatrix.c:1679: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
* Maximum absolute value for write phase offset in picoseconds
Fixes: 794c3dffacc16 ("ptp: ptp_clockmatrix: Add support for FW 5.2 (8A34005)")
Signed-off-by: Randy Dunlap <redacted>
Reported-by: kernel test robot <redacted>
Cc: Min Li <redacted>
Cc: Richard Cochran <richardcochran@gmail.com>
Cc: "David S. Miller" <davem@davemloft.net>
Cc: Jakub Kicinski <kuba@kernel.org>
---
drivers/ptp/ptp_clockmatrix.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
From: Jakub Kicinski <kuba@kernel.org> Date: 2021-11-11 01:49:59
On Wed, 10 Nov 2021 14:53:06 -0800 Randy Dunlap wrote:
quoted hunk
Do not use "/**" to begin a comment that is not in kernel-doc format.
Prevents this docs build warning:
drivers/ptp/ptp_clockmatrix.c:1679: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
* Maximum absolute value for write phase offset in picoseconds
Fixes: 794c3dffacc16 ("ptp: ptp_clockmatrix: Add support for FW 5.2 (8A34005)")
Signed-off-by: Randy Dunlap <redacted>
Reported-by: kernel test robot <redacted>
Cc: Min Li <redacted>
Cc: Richard Cochran <richardcochran@gmail.com>
Cc: "David S. Miller" <davem@davemloft.net>
Cc: Jakub Kicinski <kuba@kernel.org>
---
drivers/ptp/ptp_clockmatrix.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
Looks like it documents parameters to the function, should we either
fix it to make it valid kdoc or remove the params (which TBH aren't
really adding much value)?
From: Randy Dunlap <hidden> Date: 2021-11-11 02:10:35
On 11/10/21 5:49 PM, Jakub Kicinski wrote:
On Wed, 10 Nov 2021 14:53:06 -0800 Randy Dunlap wrote:
quoted
Do not use "/**" to begin a comment that is not in kernel-doc format.
Prevents this docs build warning:
drivers/ptp/ptp_clockmatrix.c:1679: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
* Maximum absolute value for write phase offset in picoseconds
Fixes: 794c3dffacc16 ("ptp: ptp_clockmatrix: Add support for FW 5.2 (8A34005)")
Signed-off-by: Randy Dunlap <redacted>
Reported-by: kernel test robot <redacted>
Cc: Min Li <redacted>
Cc: Richard Cochran <richardcochran@gmail.com>
Cc: "David S. Miller" <davem@davemloft.net>
Cc: Jakub Kicinski <kuba@kernel.org>
---
drivers/ptp/ptp_clockmatrix.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
Looks like it documents parameters to the function, should we either
fix it to make it valid kdoc or remove the params (which TBH aren't
really adding much value)?
a. It would be the only kernel-doc in that source file and
b. we usually want to document exported or at least non-static
functions and don't try very hard to document static ones.
I don't care much about whether we remove the other comments
that are there...
If you want them removed, I can do that.
--
~Randy
From: Jakub Kicinski <kuba@kernel.org> Date: 2021-11-11 13:58:06
On Wed, 10 Nov 2021 18:09:20 -0800 Randy Dunlap wrote:
On 11/10/21 5:49 PM, Jakub Kicinski wrote:
quoted
On Wed, 10 Nov 2021 14:53:06 -0800 Randy Dunlap wrote:
quoted
-/**
+/*
* Maximum absolute value for write phase offset in picoseconds
*
* @channel: channel
Looks like it documents parameters to the function, should we either
fix it to make it valid kdoc or remove the params (which TBH aren't
really adding much value)?
a. It would be the only kernel-doc in that source file and
b. we usually want to document exported or at least non-static
functions and don't try very hard to document static ones.
I don't care much about whether we remove the other comments
that are there...
If you want them removed, I can do that.
Yeah, lest remove the "@channel: channel" etc. while at it.
Thanks, Randy!