lkml.org 
[lkml]   [2020]   [Dec]   [1]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
From
Subject[PATCH v5 00/16]Fix several bad kernel-doc markups
Date
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.

--

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):
HSI: fix a kernel-doc markup
IB: fix kernel-doc markups
parport: fix a kernel-doc markup
rapidio: fix kernel-doc a markup
fs: fix kernel-doc markups
pstore/zone: fix a kernel-doc markup
completion: drop init_completion define
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
sched: fix kernel-doc markup
selftests: kselftest_harness.h: partially fix kernel-doc markups
refcount.h: fix a kernel-doc markup
scripts: kernel-doc: validate kernel-doc markup with the actual names

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/parport/share.c | 2 +-
drivers/rapidio/rio.c | 2 +-
fs/dcache.c | 72 +++++++++----------
fs/inode.c | 4 +-
fs/pstore/zone.c | 2 +-
fs/seq_file.c | 5 +-
fs/super.c | 12 ++--
include/linux/completion.h | 5 +-
include/linux/connector.h | 2 +-
.../firmware/intel/stratix10-svc-client.h | 10 +--
include/linux/memblock.h | 4 +-
include/linux/parport.h | 31 ++++++++
include/linux/refcount.h | 2 +-
include/linux/w1.h | 2 +-
include/rdma/ib_verbs.h | 11 +++
kernel/sched/core.c | 16 ++---
kernel/sched/fair.c | 2 +-
lib/crc7.c | 2 +-
scripts/kernel-doc | 62 +++++++++++-----
tools/testing/selftests/kselftest_harness.h | 22 +++---
33 files changed, 197 insertions(+), 123 deletions(-)

--
2.28.0


\
 
 \ /
  Last update: 2020-12-01 13:13    [W:0.201 / U:0.140 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site