Messages in this thread | | | Subject | Re: [PATCH 1/1] Reformat return value descriptions as ReST lists. | From | Peter Lister <> | Date | Wed, 11 Mar 2020 22:21:41 +0000 |
| |
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
| |