Re: [lwn:docs-next 64/66] Warning: sound/usb/usx2y/us144mkii_controls.c:8 This comment starts with '/**', but isn't a kernel-doc comment. Refer to Documentation/doc-guide/kernel-doc.rst

[Philip Li <philip.li@intel.com>]

On Mon, Dec 01, 2025 at 08:43:33AM +0800, Philip Li wrote:
> On Sun, Nov 30, 2025 at 04:20:59PM -0800, Randy Dunlap wrote:
> > Hi,
> > Is the robot an AI?
> > Maybe that could help explain why a commit that fixes spelling,
> > grammar, punctuation, etc., causes all of these kernel-doc warnings--
> 
> Sorry about this, the bisection is buggy and identified the wrong commit
> in this case. I will further investigate and ix the issue asap.

Hi Randy, it is found the commit slightly change the warning output from "Refer Documentation"
to "Refer to Documentation", which leads to wrong judgement that considers this
commit as the first bad one.

I will think of how to avoid this kind of false positive. Sorry again for the
confusion.

@@ -1179,7 +1179,7 @@ class KernelDoc:
             #
             else:
                 self.emit_msg(ln,
-                              f"This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n{line}")
+                              f"This comment starts with '/**', but isn't a kernel-doc comment. Refer to Documentation/doc-guide/kernel-doc.rst\n{line}")

> 
> > all of which seem to be valid warning reports when I have a quick
> > look at them.
> > 
> > 
> > On 11/30/25 3:12 PM, kernel test robot wrote:
> > > tree:   git://git.lwn.net/linux.git docs-next
> > > head:   464257baf99200d1be1c053f15aa617056361e81
> > > commit: 5f88f44d8427a97347afda3a6114aed0df472a0b [64/66] docs: kdoc: various fixes for grammar, spelling, punctuation
> > > config: loongarch-allmodconfig (https://download.01.org/0day-ci/archive/20251201/202512010746.EPe9Xcp5-lkp@intel.com/config)
> > > compiler: clang version 19.1.7 (https://github.com/llvm/llvm-project cd708029e0b2869e80abe31ddb175f7c35361f90)
> > > reproduce (this is a W=1 build): (https://download.01.org/0day-ci/archive/20251201/202512010746.EPe9Xcp5-lkp@intel.com/reproduce)
> > > 
> > > If you fix the issue in a separate patch/commit (i.e. not just a new version of
> > > the same patch/commit), kindly add following tags
> > > | Reported-by: kernel test robot <lkp@intel.com>
> > > | Closes: https://lore.kernel.org/oe-kbuild-all/202512010746.EPe9Xcp5-lkp@intel.com/
> > > 
> > > All warnings (new ones prefixed by >>):
> > > 
> > >    Warning: sound/usb/usx2y/us144mkii_controls.c:6 Cannot find identifier on line:
> > >     * @brief Text descriptions for playback output source options.
> > >    Warning: sound/usb/usx2y/us144mkii_controls.c:7 Cannot find identifier on line:
> > >     *
> > >>> Warning: sound/usb/usx2y/us144mkii_controls.c:8 This comment starts with '/**', but isn't a kernel-doc comment. Refer to Documentation/doc-guide/kernel-doc.rst
> > >     * Used by ALSA kcontrol elements to provide user-friendly names for
> > >    Warning: sound/usb/usx2y/us144mkii_controls.c:15 Cannot find identifier on line:
> > >     * @brief Text descriptions for capture input source options.
> > >    Warning: sound/usb/usx2y/us144mkii_controls.c:16 Cannot find identifier on line:
> > >     *
> > >    Warning: sound/usb/usx2y/us144mkii_controls.c:17 This comment starts with '/**', but isn't a kernel-doc comment. Refer to Documentation/doc-guide/kernel-doc.rst
> > >     * Used by ALSA kcontrol elements to provide user-friendly names for
> > >    Warning: sound/usb/usx2y/us144mkii_controls.c:100 cannot understand function prototype: 'const struct snd_kcontrol_new tascam_line_out_control ='
> > >    Warning: sound/usb/usx2y/us144mkii_controls.c:171 cannot understand function prototype: 'const struct snd_kcontrol_new tascam_digital_out_control ='
> > >    Warning: sound/usb/usx2y/us144mkii_controls.c:259 cannot understand function prototype: 'const struct snd_kcontrol_new tascam_capture_12_control ='
> > >    Warning: sound/usb/usx2y/us144mkii_controls.c:330 cannot understand function prototype: 'const struct snd_kcontrol_new tascam_capture_34_control ='
> > >    Warning: sound/usb/usx2y/us144mkii_controls.c:408 cannot understand function prototype: 'const struct snd_kcontrol_new tascam_samplerate_control ='
> > > --
> > >    Warning: sound/usb/usx2y/us144mkii.c:13 Cannot find identifier on line:
> > >     * @brief Module parameters for ALSA card instantiation.
> > >    Warning: sound/usb/usx2y/us144mkii.c:14 Cannot find identifier on line:
> > >     *
> > >>> Warning: sound/usb/usx2y/us144mkii.c:15 This comment starts with '/**', but isn't a kernel-doc comment. Refer to Documentation/doc-guide/kernel-doc.rst
> > >     * These parameters allow users to configure how the ALSA sound card
> > > --
> > >>> Warning: drivers/infiniband/hw/mlx5/umr.c:986 This comment starts with '/**', but isn't a kernel-doc comment. Refer to Documentation/doc-guide/kernel-doc.rst
> > >     * This function makes an mkey non-present by zapping the translation entries of
> > > 
> > 
> > -- 
> > ~Randy
> > 
> >