Re: [PATCH] docs: kdoc: fix duplicate section warning message

[Jonathan Corbet <corbet@lwn.net>]

Jacob Keller <jacob.e.keller@intel.com> writes:

> The python version of the kernel-doc parser emits some strange warnings
> with just a line number in certain cases:
>
> $ ./scripts/kernel-doc -Wall -none 'include/linux/virtio_config.h'
> Warning: 174
> Warning: 184
> Warning: 190
> Warning: include/linux/virtio_config.h:226 No description found for return value of '__virtio_test_bit'
> Warning: include/linux/virtio_config.h:259 No description found for return value of 'virtio_has_feature'
> Warning: include/linux/virtio_config.h:283 No description found for return value of 'virtio_has_dma_quirk'
> Warning: include/linux/virtio_config.h:392 No description found for return value of 'virtqueue_set_affinity'
>
> I eventually tracked this down to the lone call of emit_msg() in the
> KernelEntry class, which looks like:
>
>   self.emit_msg(self.new_start_line, f"duplicate section name '{name}'\n")
>
> This looks like all the other emit_msg calls. Unfortunately, the definition
> within the KernelEntry class takes only a message parameter and not a line
> number. The intended message is passed as the warning!
>
> Pass the filename to the KernelEntry class, and use this to build the log
> message in the same way as the KernelDoc class does.

So I would like to thrash the logging more thoroughly in a number of
ways.  Having separate log() and warn() functions would be a good start.

Failing that, though, this looks to me like a reasonable fix.

However: it doesn't apply to docs-next.  I can try to make a version
that does in the next day or three, but if you could respin it against
the current docs, that would be great...?

Thanks,

jon