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]

Date:   Sat, 28 Jul 2018 00:27:21 +0300
From:   Mike Rapoport <rppt@...ux.vnet.ibm.com>
To:     Jonathan Corbet <corbet@....net>
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, Jul 26, 2018 at 04:08:25PM -0600, Jonathan Corbet wrote:
> 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.

No problem with removing % signs, but the whitespace changes are necessary,
otherwise the generated html gets weird.
 
> 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
> 

-- 
Sincerely yours,
Mike.