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
