lkml.org 
[lkml]   [2020]   [Mar]   [11]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [PATCH 1/1] Reformat return value descriptions as ReST lists.
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

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