From: Mauro Carvalho Chehab <mchehab+huawei@kernel•org>
To: Linux Doc Mailing List <linux-doc@vger•kernel.org>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel•org>,
linux-kernel@vger•kernel.org, Jonathan Corbet <corbet@lwn•net>,
"David S. Miller" <davem@davemloft•net>,
"Theodore Ts'o" <tytso@mit•edu>,
Alexander Viro <viro@zeniv•linux.org.uk>,
Alexandre Bounine <alex.bou9@gmail•com>,
Andrew Lunn <andrew@lunn•ch>,
Andrew Morton <akpm@linux-foundation•org>,
Andy Lutomirski <luto@amacapital•net>,
Anna Schumaker <anna.schumaker@netapp•com>,
Anton Vorontsov <anton@enomsg•org>,
Ben Segall <bsegall@google•com>, Colin Cross <ccross@android•com>,
Daniel Bristot de Oliveira <bristot@redhat•com>,
Daniel Vetter <daniel@ffwll•ch>, David Airlie <airlied@linux•ie>,
Dietmar Eggemann <dietmar.eggemann@arm•com>,
Evgeniy Polyakov <zbr@ioremap•net>,
Heiner Kallweit <hkallweit1@gmail•com>,
Ingo Molnar <mingo@redhat•com>, Jakub Kicinski <kuba@kernel•org>,
Jan Kara <jack@suse•com>, Juri Lelli <juri.lelli@redhat•com>,
Kees Cook <keescook@chromium•org>,
Maarten Lankhorst <maarten.lankhorst@linux•intel.com>,
Matt Porter <mporter@kernel•crashing.org>,
Maxime Ripard <mripard@kernel•org>, Mel Gorman <mgorman@suse•de>,
Mike Rapoport <rppt@kernel•org>,
Peter Zijlstra <peterz@infradead•org>,
Richard Gong <richard.gong@linux•intel.com>,
Russell King <linux@armlinux•org.uk>,
Sebastian Reichel <sre@kernel•org>, Shuah Khan <shuah@kernel•org>,
Steven Rostedt <rostedt@goodmis•org>,
Sudip Mukherjee <sudipm.mukherjee@gmail•com>,
Thomas Gleixner <tglx@linutronix•de>,
Thomas Zimmermann <tzimmermann@suse•de>,
Tony Luck <tony.luck@intel•com>,
Trond Myklebust <trond.myklebust@hammerspace•com>,
Vincent Guittot <vincent.guittot@linaro•org>,
Will Drewry <wad@chromium•org>,
dri-devel@lists•freedesktop.org, intel-gfx@lists•freedesktop.org,
linux-ext4@vger•kernel.org, linux-fbdev@vger•kernel.org,
linux-fsdevel@vger•kernel.org, linux-kselftest@vger•kernel.org,
linux-mm@kvack•org, linux-nfs@vger•kernel.org,
linux-rdma@vger•kernel.org, linux-s390@vger•kernel.org,
netdev@vger•kernel.org, target-devel@vger•kernel.org
Subject: [PATCH v4 00/27]Fix several bad kernel-doc markups
Date: Mon, 16 Nov 2020 11:17:56 +0100 [thread overview]
Message-ID: <cover.1605521731.git.mchehab+huawei@kernel.org> (raw)
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.
--
v4:
- Patches got rebased and got some acks.
Mauro Carvalho Chehab (27):
net: phy: fix kernel-doc markups
net: datagram: fix some kernel-doc markups
net: core: fix some kernel-doc markups
s390: fix kernel-doc markups
drm: fix some kernel-doc markups
HSI: fix a kernel-doc markup
IB: fix kernel-doc markups
parport: fix a kernel-doc markup
rapidio: fix kernel-doc a markup
video: fix some kernel-doc markups
fs: fix kernel-doc markups
jbd2: fix kernel-doc markups
pstore/zone: fix a kernel-doc markup
completion: fix kernel-doc markups
firmware: stratix10-svc: fix kernel-doc markups
connector: fix a kernel-doc markup
lib/crc7: fix a kernel-doc markup
hrtimer: fix kernel-doc markups
genirq: fix kernel-doc markups
list: fix a typo at the kernel-doc markup
memblock: fix kernel-doc markups
w1: fix a kernel-doc markup
resource: fix kernel-doc markups
shed: fix kernel-doc markup
mm: fix kernel-doc markups
selftests: kselftest_harness.h: partially fix kernel-doc markups
scripts: kernel-doc: validate kernel-doc markup with the actual names
arch/s390/include/asm/ccwdev.h | 2 +-
arch/s390/include/asm/cio.h | 2 +-
drivers/gpu/drm/drm_atomic_state_helper.c | 2 +-
drivers/gpu/drm/drm_connector.c | 3 +-
drivers/gpu/drm/drm_dp_helper.c | 2 +-
drivers/gpu/drm/drm_framebuffer.c | 2 +-
drivers/gpu/drm/drm_gem.c | 4 +-
drivers/gpu/drm/drm_gem_vram_helper.c | 2 +-
drivers/gpu/drm/drm_mode_object.c | 2 +-
drivers/gpu/drm/drm_modes.c | 4 +-
drivers/gpu/drm/drm_scdc_helper.c | 2 +-
drivers/gpu/drm/i915/display/intel_dpll_mgr.c | 2 +-
drivers/gpu/drm/i915/i915_gem_evict.c | 2 +-
drivers/gpu/drm/i915/i915_perf.c | 8 ++-
drivers/gpu/drm/scheduler/sched_main.c | 2 +-
drivers/gpu/drm/v3d/v3d_sched.c | 2 +-
drivers/gpu/drm/vc4/vc4_bo.c | 2 +-
drivers/hsi/hsi_core.c | 2 +-
drivers/infiniband/core/cm.c | 5 +-
drivers/infiniband/core/cq.c | 4 +-
drivers/infiniband/core/iwpm_util.h | 2 +-
drivers/infiniband/core/sa_query.c | 3 +-
drivers/infiniband/core/verbs.c | 4 +-
drivers/infiniband/sw/rdmavt/ah.c | 2 +-
drivers/infiniband/sw/rdmavt/mcast.c | 12 ++--
drivers/infiniband/sw/rdmavt/qp.c | 8 +--
drivers/infiniband/ulp/iser/iscsi_iser.c | 2 +-
.../infiniband/ulp/opa_vnic/opa_vnic_encap.h | 2 +-
.../ulp/opa_vnic/opa_vnic_vema_iface.c | 2 +-
drivers/infiniband/ulp/srpt/ib_srpt.h | 2 +-
drivers/net/phy/mdio_bus.c | 2 +-
drivers/net/phy/phy-c45.c | 2 +-
drivers/net/phy/phy.c | 2 +-
drivers/net/phy/phy_device.c | 2 +-
drivers/net/phy/phylink.c | 2 +-
drivers/parport/share.c | 2 +-
drivers/rapidio/rio.c | 2 +-
drivers/video/fbdev/core/fbcmap.c | 2 +-
drivers/video/hdmi.c | 3 +-
fs/dcache.c | 72 +++++++++----------
fs/inode.c | 4 +-
fs/jbd2/journal.c | 34 ++++-----
fs/jbd2/transaction.c | 31 ++++----
fs/pstore/zone.c | 2 +-
fs/seq_file.c | 5 +-
fs/super.c | 12 ++--
include/drm/drm_atomic_helper.h | 4 +-
include/drm/drm_connector.h | 2 +-
include/drm/drm_device.h | 2 +-
include/drm/drm_dsc.h | 3 +-
include/drm/drm_gem_vram_helper.h | 8 +--
include/linux/completion.h | 10 ++-
include/linux/connector.h | 2 +-
.../firmware/intel/stratix10-svc-client.h | 10 +--
include/linux/hrtimer.h | 6 +-
include/linux/jbd2.h | 2 +-
include/linux/list.h | 2 +-
include/linux/memblock.h | 4 +-
include/linux/netdevice.h | 11 ++-
include/linux/parport.h | 31 ++++++++
include/linux/w1.h | 2 +-
include/rdma/ib_verbs.h | 11 +++
kernel/irq/chip.c | 2 +-
kernel/irq/generic-chip.c | 2 +-
kernel/resource.c | 24 ++++---
kernel/sched/core.c | 16 ++---
kernel/sched/fair.c | 2 +-
kernel/time/hrtimer.c | 2 +-
lib/crc7.c | 2 +-
mm/gup.c | 24 ++++---
mm/page_alloc.c | 16 ++---
mm/truncate.c | 10 ++-
net/core/datagram.c | 2 +-
net/core/dev.c | 4 +-
net/core/skbuff.c | 2 +-
net/ethernet/eth.c | 6 +-
net/sunrpc/rpc_pipe.c | 3 +-
scripts/kernel-doc | 62 +++++++++++-----
tools/testing/selftests/kselftest_harness.h | 22 +++---
79 files changed, 350 insertions(+), 235 deletions(-)
--
2.28.0
next reply other threads:[~2020-11-16 11:08 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-11-16 10:17 Mauro Carvalho Chehab [this message]
2020-11-16 10:17 ` [PATCH v4 01/27] net: phy: fix kernel-doc markups Mauro Carvalho Chehab
2020-11-16 10:17 ` [PATCH v4 02/27] net: datagram: fix some " Mauro Carvalho Chehab
2020-11-16 10:20 ` Kirill Tkhai
2020-11-16 10:17 ` [PATCH v4 03/27] net: core: " Mauro Carvalho Chehab
2020-11-17 22:19 ` [PATCH v4 00/27]Fix several bad " Jakub Kicinski
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=cover.1605521731.git.mchehab+huawei@kernel.org \
--to=mchehab+huawei@kernel$(echo .)org \
--cc=airlied@linux$(echo .)ie \
--cc=akpm@linux-foundation$(echo .)org \
--cc=alex.bou9@gmail$(echo .)com \
--cc=andrew@lunn$(echo .)ch \
--cc=anna.schumaker@netapp$(echo .)com \
--cc=anton@enomsg$(echo .)org \
--cc=bristot@redhat$(echo .)com \
--cc=bsegall@google$(echo .)com \
--cc=ccross@android$(echo .)com \
--cc=corbet@lwn$(echo .)net \
--cc=daniel@ffwll$(echo .)ch \
--cc=davem@davemloft$(echo .)net \
--cc=dietmar.eggemann@arm$(echo .)com \
--cc=dri-devel@lists$(echo .)freedesktop.org \
--cc=hkallweit1@gmail$(echo .)com \
--cc=intel-gfx@lists$(echo .)freedesktop.org \
--cc=jack@suse$(echo .)com \
--cc=juri.lelli@redhat$(echo .)com \
--cc=keescook@chromium$(echo .)org \
--cc=kuba@kernel$(echo .)org \
--cc=linux-doc@vger$(echo .)kernel.org \
--cc=linux-ext4@vger$(echo .)kernel.org \
--cc=linux-fbdev@vger$(echo .)kernel.org \
--cc=linux-fsdevel@vger$(echo .)kernel.org \
--cc=linux-kernel@vger$(echo .)kernel.org \
--cc=linux-kselftest@vger$(echo .)kernel.org \
--cc=linux-mm@kvack$(echo .)org \
--cc=linux-nfs@vger$(echo .)kernel.org \
--cc=linux-rdma@vger$(echo .)kernel.org \
--cc=linux-s390@vger$(echo .)kernel.org \
--cc=linux@armlinux$(echo .)org.uk \
--cc=luto@amacapital$(echo .)net \
--cc=maarten.lankhorst@linux$(echo .)intel.com \
--cc=mgorman@suse$(echo .)de \
--cc=mingo@redhat$(echo .)com \
--cc=mporter@kernel$(echo .)crashing.org \
--cc=mripard@kernel$(echo .)org \
--cc=netdev@vger$(echo .)kernel.org \
--cc=peterz@infradead$(echo .)org \
--cc=richard.gong@linux$(echo .)intel.com \
--cc=rostedt@goodmis$(echo .)org \
--cc=rppt@kernel$(echo .)org \
--cc=shuah@kernel$(echo .)org \
--cc=sre@kernel$(echo .)org \
--cc=sudipm.mukherjee@gmail$(echo .)com \
--cc=target-devel@vger$(echo .)kernel.org \
--cc=tglx@linutronix$(echo .)de \
--cc=tony.luck@intel$(echo .)com \
--cc=trond.myklebust@hammerspace$(echo .)com \
--cc=tytso@mit$(echo .)edu \
--cc=tzimmermann@suse$(echo .)de \
--cc=vincent.guittot@linaro$(echo .)org \
--cc=viro@zeniv$(echo .)linux.org.uk \
--cc=wad@chromium$(echo .)org \
--cc=zbr@ioremap$(echo .)net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox