linux-kernel - Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <87tw4me34y.fsf@intel.com>
Date:   Mon, 15 May 2017 15:05:49 +0300
From:   Jani Nikula <jani.nikula@...ux.intel.com>
To:     Peter Zijlstra <peterz@...radead.org>
Cc:     Mauro Carvalho Chehab <mchehab@...pensource.com>,
        Darren Hart <dvhart@...radead.org>,
        linux-kernel@...r.kernel.org,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Mauro Carvalho Chehab <mchehab@...radead.org>,
        Ingo Molnar <mingo@...hat.com>,
        Thomas Gleixner <tglx@...utronix.de>
Subject: Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST

On Mon, 15 May 2017, Peter Zijlstra <peterz@...radead.org> wrote:
> On Mon, May 15, 2017 at 01:29:58PM +0300, Jani Nikula wrote:
>> On Mon, 15 May 2017, Peter Zijlstra <peterz@...radead.org> 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