[lkml]   [2020]   [Mar]   [11]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
Messages in this thread
SubjectRe: [PATCH 1/1] Reformat return value descriptions as ReST lists.
Hello Russell,

> Is this really necessary? This seems to be rather OTT, and makes the
> comment way too big IMHO.

The existing form definitely gets the formatted output wrong (I'll send
you a screen grab if you like) and causes doc build warnings. So, yes,
it needs fixing.

ReST makes free with blank lines round blocks and list entries, and I
agree this makes for inelegant source annotation. I tried to retain the
wording unchanged and present the description as just "whitespace"
changes to make a list in the formatted output - as close as I could to
what the author appears to intend.

If you're OK with a mild rewrite of the return value description, e.g.
as two sentences (On success: p; q. On failure: x; y; z.), then we can
fix the doc build and have terser source comments and a happier kerneldoc.

All the best,

Peter Lister

 \ /
  Last update: 2020-03-11 23:22    [W:0.066 / U:3.436 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site