Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
Date:   Sat, 28 Jul 2018 00:27:21 +0300
From:   Mike Rapoport <rppt@linux.vnet.ibm.com>
To:     Jonathan Corbet <corbet@lwn.net>
Cc:     Andrew Morton <akpm@linux-foundation.org>,
        Matthew Wilcox <willy@infradead.org>,
        Michal Hocko <mhocko@kernel.org>, linux-doc@vger.kernel.org,
        linux-mm@kvack.org, linux-kernel@vger.kernel.org
Subject: Re: [PATCH v3 6/7] docs/mm: make GFP flags descriptions usable as
 kernel-doc
References: <1532626360-16650-1-git-send-email-rppt@linux.vnet.ibm.com>
 <1532626360-16650-7-git-send-email-rppt@linux.vnet.ibm.com>
 <20180726160825.0667af9f@lwn.net>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20180726160825.0667af9f@lwn.net>
User-Agent: Mutt/1.5.24 (2015-08-30)
Message-Id: <20180727212720.GD17745@rapoport-lnx>
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

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@linux.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.