On Mon, Mar 15, 2021 at 8:25 PM Jonathan Corbet <corbet@xxxxxxx> wrote: > > Aditya <yashsri421@xxxxxxxxx> writes: > > >> The opening comment mark /** is used for kernel-doc comments [1] > >> > >> [1] > >> https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#how-to-format-kernel-doc-comments > >> > > > > Hi Markus! > > That's true. But the content inside the comment does not follow > > kernel-doc format. > > For e.g., try running kernel-doc -none/man/rst on the above file in > > the example("sound/pci/ctxfi/ctresource.c"). > > The starting 2-3 lines in files generally do not contain any > > struct/enum/function, etc. declaration. > > The problem is that it's marked as a kerneldoc comment without actually > being one; it looks like somebody's internal corporate formatting. The > fix is not to put a hack into kernel-doc - we have more than enough of > those in the file already! The right thing to do is to remove the extra > "*" so that the comment doesn't look like a kerneldoc comment anymore. > Jonathan, I agree that that is the right thing to do. Aditya is already following through and is cleaning up the repository. So, let us be optimistic that we will have cleaned up all of those occurrences within a few weeks. But how to continue? Someone is going to come with new files and introduce this pattern again in the repository; and as of now, we do not have a script to identify that pattern and react... Running kernel-doc on the whole tree continuously and just observing the new warnings is probably not going to work as of now: there are 20,000 kernel-doc warnings and at least, I cannot see a really good way to filter out this one specific type of issue among all the warnings that will might appear in the future (without specifically applying Aditya's patch and looking at the diff before and after). I wonder if we could extend kernel-doc (not your preferred option as it seems) for a new dedicated warning message or maintain a separate kernel-doc sanity checking script to emit a dedicated warning based on some heuristics that suggests when a "header comment" is probably unintentionally declared as a "kernel-doc comment" when it really should not be. Jonathan, would you then prefer to have a separate kernel-doc sanity checking script that then allows us to maintain checking for patterns we already cleaned up? Eventually, we might have cleaned up enough to just use kernel-doc and keep it kind of warning-free (as with make htmldocs now) and then, we can simply follow up with kernel-doc and some basic monitoring scripts, but with 20,000 warnings in the whole repository to start with, it is still a long way to that point, IMHO. Lukas
