[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

[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

[kernel test robot]

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

-- 
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests/wiki

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

[Randy Dunlap]

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

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]

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.

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

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]

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

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

[Randy Dunlap]

On 11/30/25 6:00 PM, Philip Li wrote:
> 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}")
> 

Ah, I see. Thanks for the info.

>>
>>> all of which seem to be valid warning reports when I have a quick
>>> look at them.


-- 
~Randy