Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
Date:   Wed, 11 Mar 2020 22:25:12 +0000
From:   Russell King - ARM Linux admin <linux@armlinux.org.uk>
To:     Peter Lister <peter@bikeshed.quignogs.org.uk>
Cc:     linux-doc@vger.kernel.org, netdev@vger.kernel.org,
        Andrew Lunn <andrew@lunn.ch>,
        Florian Fainelli <f.fainelli@gmail.com>,
        Heiner Kallweit <hkallweit1@gmail.com>,
        Jonathan Corbet <corbet@lwn.net>, linux-kernel@vger.kernel.org
Subject: Re: [PATCH 1/1] Reformat return value descriptions as ReST lists.
Message-ID: <20200311222512.GV25745@shell.armlinux.org.uk>
References: <20200311192823.16213-1-peter@bikeshed.quignogs.org.uk>
 <20200311192823.16213-2-peter@bikeshed.quignogs.org.uk>
 <20200311203817.GT25745@shell.armlinux.org.uk>
 <db5f6d8f-beb0-b9bd-e47d-2a8e3dd513a2@bikeshed.quignogs.org.uk>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <db5f6d8f-beb0-b9bd-e47d-2a8e3dd513a2@bikeshed.quignogs.org.uk>
User-Agent: Mutt/1.10.1 (2018-07-13)
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

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