| Message ID | cover.1610610937.git.mchehab+huawei@kernel.org (mailing list archive) |
|---|---|
| Headers | show |
| Series | Fix several bad kernel-doc markups | expand |
On Thu, 14 Jan 2021 09:04:36 +0100 Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote: > 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 A week later none of these have shown up in linux-next, so I went ahead and applied the set. Thanks, jon
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(-)