| 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
| ||
|
Date: Thu, 14 Jan 2021 09:04:36 +0100
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Linux Doc Mailing List <linux-doc@...r.kernel.org>,
Jonathan Corbet <corbet@....net>
Cc: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
linux-kernel@...r.kernel.org,
"David S. Miller" <davem@...emloft.net>,
Alexander Viro <viro@...iv.linux.org.uk>,
Alexandre Bounine <alex.bou9@...il.com>,
Andy Lutomirski <luto@...capital.net>,
Anton Vorontsov <anton@...msg.org>,
Colin Cross <ccross@...roid.com>,
Daniel Vetter <daniel@...ll.ch>,
David Airlie <airlied@...ux.ie>,
Evgeniy Polyakov <zbr@...emap.net>,
Hans de Goede <hdegoede@...hat.com>,
Jakub Kicinski <kuba@...nel.org>,
Johannes Berg <johannes@...solutions.net>,
Jon Maloy <jmaloy@...hat.com>,
Kees Cook <keescook@...omium.org>,
Maarten Lankhorst <maarten.lankhorst@...ux.intel.com>,
Mark Gross <mgross@...ux.intel.com>,
Matt Porter <mporter@...nel.crashing.org>,
Maxime Ripard <mripard@...nel.org>,
Maximilian Luz <luzmaximilian@...il.com>,
Mike Rapoport <rppt@...nel.org>,
Philipp Zabel <p.zabel@...gutronix.de>,
Richard Gong <richard.gong@...ux.intel.com>,
Shuah Khan <shuah@...nel.org>,
Sudip Mukherjee <sudipm.mukherjee@...il.com>,
Thomas Zimmermann <tzimmermann@...e.de>,
Tony Luck <tony.luck@...el.com>,
Will Drewry <wad@...omium.org>,
Ying Xue <ying.xue@...driver.com>,
dri-devel@...ts.freedesktop.org, linux-fsdevel@...r.kernel.org,
linux-kselftest@...r.kernel.org, linux-mm@...ck.org,
linux-wireless@...r.kernel.org, netdev@...r.kernel.org,
platform-driver-x86@...r.kernel.org,
tipc-discussion@...ts.sourceforge.net
Subject: [PATCH v6 00/16] Fix several bad kernel-doc markups
Hi Jon,
This series have three parts:
1) 10 remaining fixup patches from the series I sent back on Dec, 1st:
parport: fix a kernel-doc markup
rapidio: fix kernel-doc a markup
fs: fix kernel-doc markups
pstore/zone: fix a kernel-doc markup
firmware: stratix10-svc: fix kernel-doc markups
connector: fix a kernel-doc markup
lib/crc7: fix a kernel-doc markup
memblock: fix kernel-doc markups
w1: fix a kernel-doc markup
selftests: kselftest_harness.h: partially fix kernel-doc markups
2) The patch adding the new check to ensure that the kernel-doc
markup will be used for the right declaration;
3) 5 additional patches, produced against next-20210114 with new
problems detected after the original series:
net: tip: fix a couple kernel-doc markups
net: cfg80211: fix a kerneldoc markup
reset: core: fix a kernel-doc markup
drm: drm_crc: fix a kernel-doc markup
platform/surface: aggregator: fix a kernel-doc markup
It probably makes sense to merge at least the first 11 patches
via the doc tree, as they should apply cleanly there, and
having the last 5 patches merged via each maintainer's tree.
-
Kernel-doc has always be limited to a probably bad documented
rule:
The kernel-doc markups should appear *imediatelly before* the
function or data structure that it documents.
On other words, if a C file would contain something like this:
/**
* foo - function foo
* @args: foo args
*/
static inline void bar(int args);
/**
* bar - function bar
* @args: foo args
*/
static inline void foo(void *args);
The output (in ReST format) will be:
.. c:function:: void bar (int args)
function foo
**Parameters**
``int args``
foo args
.. c:function:: void foo (void *args)
function bar
**Parameters**
``void *args``
foo args
Which is clearly a wrong result. Before this changeset,
not even a warning is produced on such cases.
As placing such markups just before the documented
data is a common practice, on most cases this is fine.
However, as patches touch things, identifiers may be
renamed, and people may forget to update the kernel-doc
markups to follow such changes.
This has been happening for quite a while, as there are
lots of files with kernel-doc problems.
This series address those issues and add a file at the
end that will enforce that the identifier will match the
kernel-doc markup, avoiding this problem from
keep happening as time goes by.
This series is based on current upstream tree.
@maintainers: feel free to pick the patches and
apply them directly on your trees, as all patches on
this series are independent from the other ones.
--
v6:
- rebased on the top of next-20210114 and added a few extra fixes
v5:
- The completion.h patch was replaced by another one which drops
an obsolete macro;
- Some typos got fixed and review tags got added;
- Dropped patches that were already merged at linux-next.
v4:
- Patches got rebased and got some acks.
Mauro Carvalho Chehab (16):
parport: fix a kernel-doc markup
rapidio: fix kernel-doc a markup
fs: fix kernel-doc markups
pstore/zone: fix a kernel-doc markup
firmware: stratix10-svc: fix kernel-doc markups
connector: fix a kernel-doc markup
lib/crc7: fix a kernel-doc markup
memblock: fix kernel-doc markups
w1: fix a kernel-doc markup
selftests: kselftest_harness.h: partially fix kernel-doc markups
scripts: kernel-doc: validate kernel-doc markup with the actual names
net: tip: fix a couple kernel-doc markups
net: cfg80211: fix a kerneldoc markup
reset: core: fix a kernel-doc markup
drm: drm_crc: fix a kernel-doc markup
platform/surface: aggregator: fix a kernel-doc markup
drivers/parport/share.c | 2 +-
.../surface/aggregator/ssh_request_layer.c | 2 +-
drivers/rapidio/rio.c | 2 +-
drivers/reset/core.c | 4 +-
fs/dcache.c | 73 ++++++++++---------
fs/inode.c | 4 +-
fs/pstore/zone.c | 2 +-
fs/seq_file.c | 5 +-
fs/super.c | 12 +--
include/drm/drm_crtc.h | 2 +-
include/linux/connector.h | 2 +-
.../firmware/intel/stratix10-svc-client.h | 10 +--
include/linux/memblock.h | 4 +-
include/linux/parport.h | 31 ++++++++
include/linux/w1.h | 2 +-
include/net/cfg80211.h | 2 +-
lib/crc7.c | 2 +-
net/tipc/link.c | 2 +-
net/tipc/node.c | 2 +-
scripts/kernel-doc | 62 ++++++++++++----
tools/testing/selftests/kselftest_harness.h | 26 ++++---
21 files changed, 160 insertions(+), 93 deletions(-)
--
2.29.2
Powered by blists - more mailing lists