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(-)
The kernel-doc markups on this file are weird: they don't follow what's specified at:
Documentation/doc-guide/kernel-doc.rst
In particular, markups should use this format: identifier - description
and not this: identifier(args)
The way the definitions are inside this file cause the parser to completely miss the identifier name of each function.
This prevents improving the script to do some needed validation tests.
Address this part. Yet, furter changes are needed in order for it to fully follow the specs.
Acked-by: Kees Cook keescook@chromium.org Signed-off-by: Mauro Carvalho Chehab mchehab+huawei@kernel.org --- tools/testing/selftests/kselftest_harness.h | 26 ++++++++++++--------- 1 file changed, 15 insertions(+), 11 deletions(-)
diff --git a/tools/testing/selftests/kselftest_harness.h b/tools/testing/selftests/kselftest_harness.h index edce85420d19..ae0f0f33b2a6 100644 --- a/tools/testing/selftests/kselftest_harness.h +++ b/tools/testing/selftests/kselftest_harness.h @@ -79,7 +79,7 @@ #endif
/** - * TH_LOG(fmt, ...) + * TH_LOG() * * @fmt: format string * @...: optional arguments @@ -113,12 +113,16 @@ __FILE__, __LINE__, _metadata->name, ##__VA_ARGS__)
/** - * SKIP(statement, fmt, ...) + * SKIP() * * @statement: statement to run after reporting SKIP * @fmt: format string * @...: optional arguments * + * .. code-block:: c + * + * SKIP(statement, fmt, ...); + * * This forces a "pass" after reporting why something is being skipped * and runs "statement", which is usually "return" or "goto skip". */ @@ -136,7 +140,7 @@ } while (0)
/** - * TEST(test_name) - Defines the test function and creates the registration + * TEST() - Defines the test function and creates the registration * stub * * @test_name: test name @@ -155,7 +159,7 @@ #define TEST(test_name) __TEST_IMPL(test_name, -1)
/** - * TEST_SIGNAL(test_name, signal) + * TEST_SIGNAL() * * @test_name: test name * @signal: signal number @@ -195,7 +199,7 @@ struct __test_metadata __attribute__((unused)) *_metadata)
/** - * FIXTURE_DATA(datatype_name) - Wraps the struct name so we have one less + * FIXTURE_DATA() - Wraps the struct name so we have one less * argument to pass around * * @datatype_name: datatype name @@ -212,7 +216,7 @@ #define FIXTURE_DATA(datatype_name) struct _test_data_##datatype_name
/** - * FIXTURE(fixture_name) - Called once per fixture to setup the data and + * FIXTURE() - Called once per fixture to setup the data and * register * * @fixture_name: fixture name @@ -239,7 +243,7 @@ FIXTURE_DATA(fixture_name)
/** - * FIXTURE_SETUP(fixture_name) - Prepares the setup function for the fixture. + * FIXTURE_SETUP() - Prepares the setup function for the fixture. * *_metadata* is included so that EXPECT_* and ASSERT_* work correctly. * * @fixture_name: fixture name @@ -265,7 +269,7 @@ __attribute__((unused)) *variant)
/** - * FIXTURE_TEARDOWN(fixture_name) + * FIXTURE_TEARDOWN() * *_metadata* is included so that EXPECT_* and ASSERT_* work correctly. * * @fixture_name: fixture name @@ -286,7 +290,7 @@ FIXTURE_DATA(fixture_name) __attribute__((unused)) *self)
/** - * FIXTURE_VARIANT(fixture_name) - Optionally called once per fixture + * FIXTURE_VARIANT() - Optionally called once per fixture * to declare fixture variant * * @fixture_name: fixture name @@ -305,7 +309,7 @@ #define FIXTURE_VARIANT(fixture_name) struct _fixture_variant_##fixture_name
/** - * FIXTURE_VARIANT_ADD(fixture_name, variant_name) - Called once per fixture + * FIXTURE_VARIANT_ADD() - Called once per fixture * variant to setup and register the data * * @fixture_name: fixture name @@ -339,7 +343,7 @@ _##fixture_name##_##variant_name##_variant =
/** - * TEST_F(fixture_name, test_name) - Emits test registration and helpers for + * TEST_F() - Emits test registration and helpers for * fixture-based test cases * * @fixture_name: fixture name
On Thu, 14 Jan 2021 09:04:36 +0100 Mauro Carvalho Chehab mchehab+huawei@kernel.org wrote:
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
linux-kselftest-mirror@lists.linaro.org
-
Jonathan Corbet -
Mauro Carvalho Chehab