On Thu, Mar 11, 2021 at 10:04 PM Aditya <yashsri421@xxxxxxxxx> wrote: > > On 10/3/21 11:49 am, Lukas Bulwahn wrote: > > 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. > > > > Hi Lukas! > This is the diff of the warnings over kernel tree before and after > applying these changes. > There are 2 sections in this report: > 1) for the warnings present before, but not after, and; > 2) after but not before > > The part (2) contains, for some cases, where the warning for "warning: > Incorrect use of kernel-doc format:" type has changed to "warning: > wrong kernel-doc identifier on line:" type. > > The diff file can be found at: > https://github.com/AdityaSrivast/kernel-tasks/blob/master/random/kernel-doc/avoid_init_line_diff.txt > Thanks, let us check if we can use this diff to create a patch set that cleans up those header comments for those files. Lukas
