linux-kernel - Re: [PATCH v3 6/7] docs/mm: make GFP flags descriptions usable as kernel-doc

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: <20180726160825.0667af9f@lwn.net>
Date:   Thu, 26 Jul 2018 16:08:25 -0600
From:   Jonathan Corbet <corbet@....net>
To:     Mike Rapoport <rppt@...ux.vnet.ibm.com>
Cc:     Andrew Morton <akpm@...ux-foundation.org>,
        Matthew Wilcox <willy@...radead.org>,
        Michal Hocko <mhocko@...nel.org>, linux-doc@...r.kernel.org,
        linux-mm@...ck.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH v3 6/7] docs/mm: make GFP flags descriptions usable as
 kernel-doc

On Thu, 26 Jul 2018 20:32:39 +0300
Mike Rapoport <rppt@...ux.vnet.ibm.com> wrote:

> This patch adds DOC: headings for GFP flag descriptions and adjusts the
> formatting to fit sphinx expectations of paragraphs.

So I think this is a great thing to do.  Adding cross references from
places where GFP flags are expected would be even better.  I do have one
little concern, though...

> - * __GFP_MOVABLE (also a zone modifier) indicates that the page can be
> - *   moved by page migration during memory compaction or can be reclaimed.
> + * %__GFP_MOVABLE (also a zone modifier) indicates that the page can be
> + * moved by page migration during memory compaction or can be reclaimed.

There are Certain Developers who get rather bent out of shape when they
feel that excessive markup is degrading the readability of the plain-text
documentation.  I have a suspicion that all of these % signs might turn
out to be one of those places.  People have been trained to expect them in
function documentation, but that's not quite what we have here.

I won't insist on this, but I would suggest that, in this particular case,
it might be better for that markup to come out.

Then we have the same old question of who applies these.  I'd love to have
an ack from somebody who can speak for mm - or a statement that these will
go through another tree.  Preferably quickly so that this stuff can get
in through the upcoming merge window.

Thanks,

jon