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 for Android: free password hash cracker in your pocket

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

Message-ID: <874lwmmmzd.fsf@intel.com>
Date:   Mon, 15 May 2017 13:29:58 +0300
From:   Jani Nikula <jani.nikula@...ux.intel.com>
To:     Peter Zijlstra <peterz@...radead.org>,
        Mauro Carvalho Chehab <mchehab@...pensource.com>
Cc:     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:
> 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.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center