linux-kernel - Re: [PATCH 1/1] Reformat return value descriptions as ReST lists.

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <db5f6d8f-beb0-b9bd-e47d-2a8e3dd513a2@bikeshed.quignogs.org.uk>
Date:   Wed, 11 Mar 2020 22:21:41 +0000
From:   Peter Lister <peter@...eshed.quignogs.org.uk>
To:     Russell King - ARM Linux admin <linux@...linux.org.uk>
Cc:     linux-doc@...r.kernel.org, netdev@...r.kernel.org,
        Andrew Lunn <andrew@...n.ch>,
        Florian Fainelli <f.fainelli@...il.com>,
        Heiner Kallweit <hkallweit1@...il.com>,
        Jonathan Corbet <corbet@....net>, linux-kernel@...r.kernel.org
Subject: Re: [PATCH 1/1] Reformat return value descriptions as ReST lists.

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