| Message ID | 20211110225306.13483-1-rdunlap@infradead.org (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | ptp: ptp_clockmatrix: repair non-kernel-doc comment | expand |
| Context | Check | Description |
|---|---|---|
| netdev/tree_selection | success | Guessing tree name failed - patch did not apply |
On Wed, 10 Nov 2021 14:53:06 -0800 Randy Dunlap wrote: > 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 <rdunlap@infradead.org> > Reported-by: kernel test robot <lkp@intel.com> > Cc: Min Li <min.li.xe@renesas.com> > 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)?
On 11/10/21 5:49 PM, Jakub Kicinski wrote: > On Wed, 10 Nov 2021 14:53:06 -0800 Randy Dunlap wrote: >> 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 <rdunlap@infradead.org> >> Reported-by: kernel test robot <lkp@intel.com> >> Cc: Min Li <min.li.xe@renesas.com> >> 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.
On Wed, 10 Nov 2021 18:09:20 -0800 Randy Dunlap wrote: > On 11/10/21 5:49 PM, Jakub Kicinski wrote: > > On Wed, 10 Nov 2021 14:53:06 -0800 Randy Dunlap wrote: > >> -/** > >> +/* > >> * 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!
--- 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
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 <rdunlap@infradead.org> Reported-by: kernel test robot <lkp@intel.com> Cc: Min Li <min.li.xe@renesas.com> 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(-)