On Mon, 15 May 2017, Peter Zijlstra <peterz@xxxxxxxxxxxxx> wrote: > On Mon, May 15, 2017 at 01:29:58PM +0300, Jani Nikula wrote: >> On Mon, 15 May 2017, Peter Zijlstra <peterz@xxxxxxxxxxxxx> wrote: >> > The intention is to aid readability. Making comments worse so that some >> > retarded script can generate better html or whatnot is just that, >> > retarded. >> > >> > Code matters, generated documentation not so much. I'll take a comment >> > that reads well over one that generates pretty html any day. >> >> The deal is that if you start your comments with "/**" they'll be >> processed with the retarded script to produce pretty html. >> >> For the most part the comments that generate pretty html also read well, >> and we don't expect or want anyone to go overboard with markup. I don't >> think it's unreasonable to make small concessions to improve generated >> documentation for people who care about it even if you don't. > > No. Such a concession has pure negative value. It opens the door to more > patches converting this or that comment to be prettier or whatnot. And > before you know it there's a Markus like idiot spamming you with dozens > of crap patches to prettify the generated crud. > > Not to mention that this would mean having to learn this rest crud in > order to write these comments. > > All things I'm not prepared to do. > > I'm all for useful comments, but I see no value _at_all_ in this > generated nonsense. The only reason I sometimes use the docbook comment > style is because its fairly uniform and the build bot gets you a warning > when your function signature no longer matches with the comment. But > if you make this painful I'll simply stop using them. I see plenty of value in the generated documentation, but I see zero return on investment in spending any time trying to convince you about any of it. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
