From: Peter Lister <peter@bikeshed.quignogs.org.uk>
To: Russell King - ARM Linux admin <linux@armlinux.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.
Date: Wed, 11 Mar 2020 22:21:41 +0000 [thread overview]
Message-ID: <db5f6d8f-beb0-b9bd-e47d-2a8e3dd513a2@bikeshed.quignogs.org.uk> (raw)
In-Reply-To: <20200311203817.GT25745@shell.armlinux.org.uk>
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
next prev parent reply other threads:[~2020-03-11 22:21 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-03-11 19:28 [PATCH 0/1] Convert text to ReST list and remove doc build warnings peter
2020-03-11 19:28 ` [PATCH 1/1] Reformat return value descriptions as ReST lists peter
2020-03-11 20:38 ` Russell King - ARM Linux admin
2020-03-11 22:21 ` Peter Lister [this message]
2020-03-11 22:25 ` Russell King - ARM Linux admin
2020-03-12 0:49 ` Matthew Wilcox
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=db5f6d8f-beb0-b9bd-e47d-2a8e3dd513a2@bikeshed.quignogs.org.uk \
--to=peter@bikeshed.quignogs.org.uk \
--cc=andrew@lunn.ch \
--cc=corbet@lwn.net \
--cc=f.fainelli@gmail.com \
--cc=hkallweit1@gmail.com \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux@armlinux.org.uk \
--cc=netdev@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.