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. > Thanks, > > jon > -- Sincerely yours, Mike. -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
