[PATCH v3 00/56] Fix several bad kernel-doc markups

From: Mauro Carvalho Chehab
Date: Fri Oct 23 2020 - 12:35:13 EST

Next message: Mauro Carvalho Chehab: "[PATCH v3 56/56] scrpits: kernel-doc: validate kernel-doc markup with the actual names"
Previous message: Mauro Carvalho Chehab: "[PATCH v3 48/56] sound: fix kernel-doc markups"
Next in thread: Mauro Carvalho Chehab: "[PATCH v3 07/56] block: blk-mq: fix a kernel-doc markup"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

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.

Jon,

The first patch contains a trivial bug fix that I got
at kernel-doc script while writing this series. Feel
free to pick it anytime.

The last one should likely be applied only after we
have everything else in place, as otherwise it will
produce hundreds of warnings, and the broken
markups will be ignored.

Mauro Carvalho Chehab (56):
scripts: kernel-doc: fix typedef parsing
drm: amdgpu_dm: fix a typo
amdgpu: fix a few kernel-doc markup issues
drm: drm_print.h: fix kernel-doc markups
s390: fix kernel-doc markups
x86: mtrr: fix a kernel-doc markup
block: blk-mq: fix a kernel-doc markup
ata: fix some kernel-doc markups
drivers: base: fix some kernel-doc markups
EDAC: fix some kernel-doc markups
drm/amdgpu: fix some kernel-doc markups
drm: fix some kernel-doc markups
HSI: fix a kernel-doc markup
IB: fix kernel-doc markups
media: fix kernel-doc markups
mei: bus: fix a kernel-doc markup
mtd: rawnand: fix a kernel-doc markup
net: phy: fix kernel-doc markups
net: datagram: fix some kernel-doc markups
net: core: fix some kernel-doc markups
mac80211: fix kernel-doc markups
parport: fix a kernel-doc markup
PCI: fix kernel-doc markups
PNP: fix kernel-doc markups
rapidio: fix kernel-doc a markup
regulator: fix a kernel-doc markup
scsi: fix some kernel-doc markups
slimbus: fix a kernel-doc markup
spi: fix a typo inside a kernel-doc markup
uio: fix some kernel-doc markups
usb: dwc3: fix kernel-doc markups
video: fix some kernel-doc markups
vme: fix two kernel-doc markups
fs: fix kernel-doc markups
jbd2: fix kernel-doc markups
locks: fix a typo at a kernel-doc markup
pstore/zone: fix a kernel-doc markup
clk: 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
iio: fix a kernel-doc markup
list: fix a typo at the kernel-doc markup
memblock: fix kernel-doc markups
sound: fix kernel-doc markups
refcount.h: fix a kernel-doc markup
w1: fix a kernel-doc markup
audit: 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
scrpits: kernel-doc: validate kernel-doc markup with the actual names

arch/s390/include/asm/ccwdev.h | 2 +-
arch/s390/include/asm/cio.h | 2 +-
arch/x86/kernel/cpu/mtrr/mtrr.c | 3 +-
block/blk-mq.c | 2 +-
drivers/ata/libata-core.c | 2 +-
drivers/ata/libata-eh.c | 2 +-
drivers/ata/libata-scsi.c | 2 +-
drivers/base/class.c | 2 +-
drivers/base/devres.c | 2 +-
drivers/base/firmware_loader/fallback.c | 2 +-
drivers/edac/edac_device.h | 11 ++-
drivers/gpu/drm/amd/amdgpu/amdgpu_device.c | 8 ++-
drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c | 2 +-
drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c | 2 +-
.../gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c | 2 +-
.../gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h | 6 +-
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/media/dvb-frontends/ascot2e.h | 2 +-
drivers/media/dvb-frontends/cxd2820r.h | 2 +-
drivers/media/dvb-frontends/drxk.h | 2 +-
drivers/media/dvb-frontends/dvb-pll.h | 2 +-
drivers/media/dvb-frontends/helene.h | 4 +-
drivers/media/dvb-frontends/horus3a.h | 2 +-
drivers/media/dvb-frontends/ix2505v.h | 4 +-
drivers/media/dvb-frontends/m88ds3103.h | 2 +-
drivers/media/dvb-frontends/mb86a20s.h | 2 +-
drivers/media/dvb-frontends/stb6000.h | 2 +-
drivers/media/dvb-frontends/tda826x.h | 2 +-
drivers/media/dvb-frontends/zl10036.h | 4 +-
drivers/misc/mei/bus.c | 2 +-
drivers/mtd/nand/raw/nand_bbt.c | 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/pci/p2pdma.c | 10 +--
drivers/pci/pci-driver.c | 4 +-
drivers/pci/pci.c | 2 +-
drivers/pci/probe.c | 4 +-
drivers/pci/slot.c | 5 +-
drivers/pnp/core.c | 4 +-
drivers/rapidio/rio.c | 2 +-
drivers/regulator/core.c | 2 +-
drivers/scsi/iscsi_tcp.c | 4 +-
drivers/scsi/libiscsi.c | 2 +-
drivers/scsi/scsi_devinfo.c | 3 +-
drivers/scsi/scsi_lib.c | 6 +-
drivers/scsi/scsi_transport_fc.c | 2 +-
drivers/slimbus/slimbus.h | 2 +-
drivers/spi/spi.c | 6 +-
.../staging/media/ipu3/include/intel-ipu3.h | 8 +--
drivers/uio/uio.c | 4 +-
drivers/usb/dwc3/core.c | 2 +-
drivers/usb/dwc3/core.h | 2 +-
drivers/usb/gadget/composite.c | 2 +-
drivers/usb/typec/mux.c | 2 +-
drivers/video/fbdev/core/fbcmap.c | 2 +-
drivers/video/hdmi.c | 3 +-
drivers/vme/vme.c | 4 +-
fs/dcache.c | 72 +++++++++----------
fs/inode.c | 4 +-
fs/jbd2/journal.c | 34 ++++-----
fs/jbd2/transaction.c | 31 ++++----
fs/locks.c | 2 +-
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/drm/drm_print.h | 20 +++++-
include/linux/clk.h | 2 +-
include/linux/completion.h | 10 ++-
include/linux/connector.h | 2 +-
include/linux/device/class.h | 14 ++++
include/linux/edac.h | 4 +-
.../firmware/intel/stratix10-svc-client.h | 10 +--
include/linux/hrtimer.h | 6 +-
include/linux/iio/trigger.h | 2 +-
include/linux/jbd2.h | 2 +-
include/linux/list.h | 2 +-
include/linux/memblock.h | 4 +-
include/linux/mtd/rawnand.h | 3 +-
include/linux/netdevice.h | 11 ++-
include/linux/parport.h | 31 ++++++++
include/linux/refcount.h | 2 +-
include/linux/uio_driver.h | 16 +++++
include/linux/usb/composite.h | 2 +-
include/linux/w1.h | 2 +-
include/media/dvbdev.h | 2 +-
include/media/v4l2-ctrls.h | 2 +-
include/media/v4l2-dev.h | 4 +-
include/media/v4l2-device.h | 2 +-
include/media/v4l2-dv-timings.h | 2 +-
include/media/v4l2-fwnode.h | 2 +-
include/media/v4l2-mediabus.h | 6 +-
include/media/v4l2-subdev.h | 2 +-
include/media/videobuf2-core.h | 2 +-
include/net/cfg80211.h | 9 +--
include/net/mac80211.h | 7 +-
include/rdma/ib_verbs.h | 11 +++
include/sound/core.h | 3 +-
include/sound/pcm.h | 4 +-
include/uapi/drm/amdgpu_drm.h | 2 +-
include/uapi/sound/compress_offload.h | 2 +-
kernel/audit.c | 2 +-
kernel/irq/chip.c | 2 +-
kernel/irq/generic-chip.c | 2 +-
kernel/resource.c | 24 ++++---
kernel/sched/core.c | 16 ++---
kernel/sched/fair.c | 3 +-
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/mac80211/sta_info.h | 9 ++-
net/sunrpc/rpc_pipe.c | 3 +-
scripts/kernel-doc | 64 ++++++++++++-----
sound/core/control.c | 4 +-
sound/core/pcm_dmaengine.c | 3 +-
sound/core/pcm_lib.c | 2 +-
sound/core/pcm_native.c | 4 +-
sound/soc/soc-core.c | 2 +-
sound/soc/soc-dapm.c | 2 +-
tools/testing/selftests/kselftest_harness.h | 66 ++++++++---------
161 files changed, 558 insertions(+), 382 deletions(-)

--
2.26.2

Next message: Mauro Carvalho Chehab: "[PATCH v3 56/56] scrpits: kernel-doc: validate kernel-doc markup with the actual names"
Previous message: Mauro Carvalho Chehab: "[PATCH v3 48/56] sound: fix kernel-doc markups"
Next in thread: Mauro Carvalho Chehab: "[PATCH v3 07/56] block: blk-mq: fix a kernel-doc markup"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]