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(-)