On Wed, Mar 11, 2020 at 10:21:41PM +0000, Peter Lister wrote: > 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. I think it's more important that the documentation interferes to a minimal degree with the code in the file, so please rewrite if it improves it. (btw, I'm the author.) Thanks. -- RMK's Patch system: https://www.armlinux.org.uk/developer/patches/ FTTC broadband for 0.8mile line in suburbia: sync at 10.2Mbps down 587kbps up
