Re: [PATCH] ptp: ptp_clockmatrix: repair non-kernel-doc comment

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(-)

--- linux-next-20211110.orig/drivers/ptp/ptp_clockmatrix.c
+++ linux-next-20211110/drivers/ptp/ptp_clockmatrix.c

@@ -1699,7 +1699,7 @@ static int initialize_dco_operating_mode
  
  /* PTP Hardware Clock interface */
  
-/**
+/*
   * 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.

-- 
~Randy