On Tue, Mar 9, 2021 at 10:24 PM Aditya <yashsri421@xxxxxxxxx> wrote: > > On 9/3/21 7:00 pm, Markus Heiser wrote: > > > > Am 09.03.21 um 13:53 schrieb Aditya Srivastava: > >> Starting commented lines in a file mostly contains comments describing > >> license, copyright or general information about the file. > >> > >> E.g., in sound/pci/ctxfi/ctresource.c, initial comment lines describe > >> its copyright and other related file informations. > > > > 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. > Aditya, can you provide a diff of the warnings over the whole kernel tree? At the moment, your patch just implements ignoring the initial comment, which probably is good for experimentation. Alternatively, we could simply have a dedicated warning and then ignore it or even warn and then parse it as-if. In the "long run", we would probably want to fix all current files in the repository by just replacing '/**' by '/*' and have kernel-doc warn about this suspicious pattern, when new files appear (maybe even configurable, but that is another feature to enable or disable certain kernel-doc checks and warnings). I would certainly assist and contribute to such a clean-up task. I think the first step is to look at the diff, and see how many cases really appear in the tree... then check how many patches throughout the whole tree are required and if they are generally accepted. Lukas
