linux-kernel - [PATCH v3 0/1] Compactly make code examples into literal blocks

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: <20200326195156.11858-1-peter@bikeshed.quignogs.org.uk>
Date:   Thu, 26 Mar 2020 19:51:55 +0000
From:   peter@...eshed.quignogs.org.uk
To:     Matthew Wilcox <willy@...radead.org>, linux-kernel@...r.kernel.org
Cc:     Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
        "Rafael J. Wysocki" <rafael@...nel.org>, linux-doc@...r.kernel.org,
        Jonathan Corbet <corbet@....net>,
        Peter Lister <peter@...eshed.quignogs.org.uk>
Subject: [PATCH v3 0/1] Compactly make code examples into literal blocks

From: Peter Lister <peter@...eshed.quignogs.org.uk>

[ A couple of typos corrected. Thanks, Matthew ]

In a previous patch, I fixed a couple of doc build warnings due to a
section heading "Example:" which didn't have the intended effect of
inserting a heading and literal quoting the following code snippet. I
added an explicit double colon to fix warnings and produce nice ReST.

Jon suggested that I could have used a minimal form "Example::".
Unfortunately not - kernel-doc munges the output so that the formatted
output ends up as a stray colon and no literal block.

Looking around in the source tree, it seems that parameter definitions
can be more complex than the original authors of kernel-doc allowed
for. Return values often need lists and examples often should be
literal blocks. Many comments in the source are "ASCII formatted" but
kernel-doc can make a mess of them and generate doc build warnings
along the way.

It seems useful to support some terse idioms which serve as compact
source annotation and also generate well formed ReST.

Here is a first try to let a heading directly introduce a literal
block - the "Example::" form for code snippets and an update to
platform.c to use it, just as Jon suggested.

Peter Lister (1):
  A compact idiom to add code examples in kerneldoc comments.

 drivers/base/platform.c |  4 ++--
 scripts/kernel-doc      | 19 +++++++++++++++----
 2 files changed, 17 insertions(+), 6 deletions(-)

-- 
2.25.1