[-CC lkml] On Wed, 23 Feb 2022 15:04:03 +0100, Tomasz Warniełło wrote: > On Wed, 23 Feb 2022 22:16:30 +0900 > Akira Yokosawa <akiyks@xxxxxxxxx> wrote: > >> When I do "man perl", I want to see a detailed explanation, and >> somewhat hard-to-parse synopsis is ok. >> >> I'm saying that I don't like to see such a thing when I type >> "./scripts/kerneldoc -h". I expect a hint to recall which option I >> should use. I don't want to scroll back the terminal. >> >> It would be nice if the verbose man page can be shown by >> "./scripts/kerneldoc -v -h" or "perldoc -F ./scripts/kerneldoc". > > This is an option. But it makes things more complex. I'd rather reduce > the easy in favour of the difficult. I'd say _not_ introducing POD is the simplest, but I guess you have another thought. > >>>>> I don't see much point for such a non-user-facing script having nice-looking >>>>> well-structured documentation in the first place. >>> >>> You're touching the very essence of kernel-doc here. What and who is it for? >>> Not just the script - all of it. >> >> Sorry, I have no idea what I am being asked. >> Could you rephrase above for a non-native speaker of English, please? > > Who is the "user"? Most of Linux users never even browse the source code. Apparently, users of ./scripts/kernel-doc are who run "make htmldocs" or "make pdfdocs", a relatively small portion of Linux kernel development community, I guess. Note that they don't have direct interactions with ./scripts/kernel-doc in most (>95% ??) cases. Normal Linux end-users don't bother with kernel-doc, I guess. If you are interested in how the kernel dev community works, I'd recommend starting from "Working with the kernel development community" at https://www.kernel.org/doc/html/latest/process/index.html, that is if you have not done so. Thanks, Akira > > Tomasz
