On Sun, May 14, 2023 at 08:58:00AM +0900, Akira Yokosawa wrote: > Hi, > > On Fri, 12 May 2023 19:11:15 -0700, Paul E. McKenney wrote: > [...] > > > > > And here is a rough first cut: > > > > git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu.git tags/fallback-rework-kernel-doc.2023.05.12a > > > > Or via HTML: > > > > https://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu.git/log/?h=fallback-rework-kernel-doc.2023.05.12a > > Running "./scripts/kernel-doc -none include/linux/atomic/atomic-arch-fallback.h" > on the tag emits a lot of warnings. > > Looks like there are kernel-doc comments who don't have a corresponding > function signature next to them. > > /** > * function_name() - Brief description of function. > * @arg1: Describe the first argument. > * @arg2: Describe the second argument. > * One can provide multiple line descriptions > * for arguments. > * > * A longer description, with more discussion of the function function_name() > * that might be useful to those using or modifying it. Begins with an > * empty comment line, and may include additional embedded empty > * comment lines. > */ > int function_name(int arg1, int arg2) <--- > > Note that the kernel-doc script ignores #ifdef -- #else. Me, I was thinking in terms of making this diagnostic ignore include/linux/atomic/atomic-arch-fallback.h. ;-) The actual definitions are off in architecture-specific files, and the kernel-doc headers could be left there. But there are benefits to automatically generating all of them. Another approach might be to put a "it is OK for the definition to be elsewhere" comment following those kernel-doc headers. Any other ways to make this work? For me, the option of making this diagnostic ignore include/linux/atomic/atomic-arch-fallback.h has considerable attraction. > BTW, I couldn't checkout the tag so downloaded the tar ball via > HTML. Tags can be a bit annoying in that way. I will provide a branch next time. Thanx, Paul > Thanks, Akira > > > > > Thoughts? > > > > In the meantime, enjoy the weekend! > > > > Thanx, Paul
