Re: [PATCH v3 6/7] docs/mm: make GFP flags descriptions usable as kernel-doc
From: Mike Rapoport
Date: Fri Jul 27 2018 - 17:27:32 EST
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@xxxxxxxxxxxxxxxxxx> 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.