From: Kees Cook <keescook@chromium.org>
To: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Cc: Linux Doc Mailing List <linux-doc@vger.kernel.org>,
Jonathan Corbet <corbet@lwn.net>,
Andy Lutomirski <luto@amacapital.net>,
Shuah Khan <shuah@kernel.org>, Will Drewry <wad@chromium.org>,
linux-kernel@vger.kernel.org, linux-kselftest@vger.kernel.org
Subject: Re: [PATCH v3 55/56] selftests: kselftest_harness.h: partially fix kernel-doc markups
Date: Fri, 23 Oct 2020 10:39:02 -0700 [thread overview]
Message-ID: <202010231036.B41FB56D@keescook> (raw)
In-Reply-To: <8d816b5a5f31600176fd9ad5e58c0a74bf79f8dd.1603469755.git.mchehab+huawei@kernel.org>
On Fri, Oct 23, 2020 at 06:33:42PM +0200, Mauro Carvalho Chehab wrote:
> 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.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
> tools/testing/selftests/kselftest_harness.h | 66 ++++++++++-----------
> 1 file changed, 33 insertions(+), 33 deletions(-)
>
> diff --git a/tools/testing/selftests/kselftest_harness.h b/tools/testing/selftests/kselftest_harness.h
> index f19804df244c..665d04f3b802 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
Hmmm. Yeah, this does need fixing, but I don't want to lose the
"examples". Some have stuff like this before the description:
* .. code-block:: c
*
* TH_LOG(format, ...)
which retains it, but many don't. Can you add the code-block:: c
sections where they're missing so this doesn't lose the syntax hints
when just looking at the header file alone.
-Kees
> @@ -113,7 +113,7 @@
> __FILE__, __LINE__, _metadata->name, ##__VA_ARGS__)
>
> /**
> - * SKIP(statement, fmt, ...)
> + * SKIP()
> *
> * @statement: statement to run after reporting SKIP
> * @fmt: format string
> @@ -136,7 +136,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 +155,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 +195,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 +212,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 +239,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 +265,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 +286,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 +305,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 +339,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
> @@ -432,7 +432,7 @@
> */
>
> /**
> - * ASSERT_EQ(expected, seen)
> + * ASSERT_EQ()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -443,7 +443,7 @@
> __EXPECT(expected, #expected, seen, #seen, ==, 1)
>
> /**
> - * ASSERT_NE(expected, seen)
> + * ASSERT_NE()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -454,7 +454,7 @@
> __EXPECT(expected, #expected, seen, #seen, !=, 1)
>
> /**
> - * ASSERT_LT(expected, seen)
> + * ASSERT_LT()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -465,7 +465,7 @@
> __EXPECT(expected, #expected, seen, #seen, <, 1)
>
> /**
> - * ASSERT_LE(expected, seen)
> + * ASSERT_LE()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -476,7 +476,7 @@
> __EXPECT(expected, #expected, seen, #seen, <=, 1)
>
> /**
> - * ASSERT_GT(expected, seen)
> + * ASSERT_GT()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -487,7 +487,7 @@
> __EXPECT(expected, #expected, seen, #seen, >, 1)
>
> /**
> - * ASSERT_GE(expected, seen)
> + * ASSERT_GE()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -498,7 +498,7 @@
> __EXPECT(expected, #expected, seen, #seen, >=, 1)
>
> /**
> - * ASSERT_NULL(seen)
> + * ASSERT_NULL()
> *
> * @seen: measured value
> *
> @@ -508,7 +508,7 @@
> __EXPECT(NULL, "NULL", seen, #seen, ==, 1)
>
> /**
> - * ASSERT_TRUE(seen)
> + * ASSERT_TRUE()
> *
> * @seen: measured value
> *
> @@ -518,7 +518,7 @@
> __EXPECT(0, "0", seen, #seen, !=, 1)
>
> /**
> - * ASSERT_FALSE(seen)
> + * ASSERT_FALSE()
> *
> * @seen: measured value
> *
> @@ -528,7 +528,7 @@
> __EXPECT(0, "0", seen, #seen, ==, 1)
>
> /**
> - * ASSERT_STREQ(expected, seen)
> + * ASSERT_STREQ()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -539,7 +539,7 @@
> __EXPECT_STR(expected, seen, ==, 1)
>
> /**
> - * ASSERT_STRNE(expected, seen)
> + * ASSERT_STRNE()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -550,7 +550,7 @@
> __EXPECT_STR(expected, seen, !=, 1)
>
> /**
> - * EXPECT_EQ(expected, seen)
> + * EXPECT_EQ()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -561,7 +561,7 @@
> __EXPECT(expected, #expected, seen, #seen, ==, 0)
>
> /**
> - * EXPECT_NE(expected, seen)
> + * EXPECT_NE()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -572,7 +572,7 @@
> __EXPECT(expected, #expected, seen, #seen, !=, 0)
>
> /**
> - * EXPECT_LT(expected, seen)
> + * EXPECT_LT()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -583,7 +583,7 @@
> __EXPECT(expected, #expected, seen, #seen, <, 0)
>
> /**
> - * EXPECT_LE(expected, seen)
> + * EXPECT_LE()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -594,7 +594,7 @@
> __EXPECT(expected, #expected, seen, #seen, <=, 0)
>
> /**
> - * EXPECT_GT(expected, seen)
> + * EXPECT_GT()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -605,7 +605,7 @@
> __EXPECT(expected, #expected, seen, #seen, >, 0)
>
> /**
> - * EXPECT_GE(expected, seen)
> + * EXPECT_GE()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -616,7 +616,7 @@
> __EXPECT(expected, #expected, seen, #seen, >=, 0)
>
> /**
> - * EXPECT_NULL(seen)
> + * EXPECT_NULL()
> *
> * @seen: measured value
> *
> @@ -626,7 +626,7 @@
> __EXPECT(NULL, "NULL", seen, #seen, ==, 0)
>
> /**
> - * EXPECT_TRUE(seen)
> + * EXPECT_TRUE()
> *
> * @seen: measured value
> *
> @@ -636,7 +636,7 @@
> __EXPECT(0, "0", seen, #seen, !=, 0)
>
> /**
> - * EXPECT_FALSE(seen)
> + * EXPECT_FALSE()
> *
> * @seen: measured value
> *
> @@ -646,7 +646,7 @@
> __EXPECT(0, "0", seen, #seen, ==, 0)
>
> /**
> - * EXPECT_STREQ(expected, seen)
> + * EXPECT_STREQ()
> *
> * @expected: expected value
> * @seen: measured value
> @@ -657,7 +657,7 @@
> __EXPECT_STR(expected, seen, ==, 0)
>
> /**
> - * EXPECT_STRNE(expected, seen)
> + * EXPECT_STRNE()
> *
> * @expected: expected value
> * @seen: measured value
> --
> 2.26.2
>
--
Kees Cook
next prev parent reply other threads:[~2020-10-23 17:39 UTC|newest]
Thread overview: 122+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-10-23 16:32 [PATCH v3 00/56] Fix several bad kernel-doc markups Mauro Carvalho Chehab
2020-10-23 16:32 ` [PATCH v3 01/56] scripts: kernel-doc: fix typedef parsing Mauro Carvalho Chehab
2020-10-23 17:22 ` Jonathan Corbet
2020-10-23 18:01 ` Joe Perches
2020-10-26 7:03 ` Mauro Carvalho Chehab
2020-10-27 3:55 ` Joe Perches
2020-10-27 8:37 ` Mauro Carvalho Chehab
2020-10-24 6:43 ` Mauro Carvalho Chehab
2020-10-26 5:55 ` Mauro Carvalho Chehab
2020-10-23 16:32 ` [PATCH v3 02/56] drm: amdgpu_dm: fix a typo Mauro Carvalho Chehab
2020-10-23 19:02 ` Alex Deucher
2020-10-23 16:32 ` [PATCH v3 03/56] amdgpu: fix a few kernel-doc markup issues Mauro Carvalho Chehab
2020-10-23 16:38 ` Christian König
2020-10-23 18:58 ` Alex Deucher
2020-10-23 16:32 ` [PATCH v3 04/56] drm: drm_print.h: fix kernel-doc markups Mauro Carvalho Chehab
2020-10-23 16:32 ` [PATCH v3 05/56] s390: " Mauro Carvalho Chehab
2020-10-23 16:32 ` [PATCH v3 06/56] x86: mtrr: fix a kernel-doc markup Mauro Carvalho Chehab
2020-10-23 16:32 ` [PATCH v3 07/56] block: blk-mq: " Mauro Carvalho Chehab
2020-10-23 18:20 ` Jens Axboe
2020-10-23 16:32 ` [PATCH v3 08/56] ata: fix some kernel-doc markups Mauro Carvalho Chehab
2020-10-23 18:21 ` Jens Axboe
2020-10-23 16:32 ` [PATCH v3 09/56] drivers: base: " Mauro Carvalho Chehab
2020-10-23 16:32 ` [PATCH v3 10/56] EDAC: " Mauro Carvalho Chehab
2020-11-02 19:37 ` Borislav Petkov
2020-10-23 16:32 ` [PATCH v3 11/56] drm/amdgpu: " Mauro Carvalho Chehab
2020-10-23 16:50 ` Christian König
2020-10-23 18:59 ` Alex Deucher
2020-10-23 16:32 ` [PATCH v3 12/56] drm: " Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 13/56] HSI: fix a kernel-doc markup Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 14/56] IB: fix kernel-doc markups Mauro Carvalho Chehab
2020-10-24 21:50 ` Max Gurtovoy
2020-10-23 16:33 ` [PATCH v3 15/56] media: " Mauro Carvalho Chehab
2020-10-23 17:27 ` Sakari Ailus
2020-10-23 16:33 ` [PATCH v3 16/56] mei: bus: fix a kernel-doc markup Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 17/56] mtd: rawnand: " Mauro Carvalho Chehab
2020-10-30 17:27 ` Miquel Raynal
2020-10-23 16:33 ` [PATCH v3 18/56] net: phy: fix kernel-doc markups Mauro Carvalho Chehab
2020-10-23 21:04 ` Andrew Lunn
2020-10-23 16:33 ` [PATCH v3 19/56] net: datagram: fix some " Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 20/56] net: core: " Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 21/56] mac80211: fix " Mauro Carvalho Chehab
2020-10-27 7:26 ` Johannes Berg
2020-10-27 8:00 ` Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 22/56] parport: fix a kernel-doc markup Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 23/56] PCI: fix kernel-doc markups Mauro Carvalho Chehab
2020-10-23 17:43 ` Bjorn Helgaas
2020-10-24 7:30 ` Mauro Carvalho Chehab
2020-11-05 14:44 ` Bjorn Helgaas
2020-10-23 16:33 ` [PATCH v3 24/56] PNP: " Mauro Carvalho Chehab
2020-10-27 18:24 ` Rafael J. Wysocki
2020-10-23 16:33 ` [PATCH v3 25/56] rapidio: fix kernel-doc a markup Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 26/56] regulator: fix a kernel-doc markup Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 27/56] scsi: fix some kernel-doc markups Mauro Carvalho Chehab
2020-10-27 1:54 ` Martin K. Petersen
2020-10-23 16:33 ` [PATCH v3 28/56] slimbus: fix a kernel-doc markup Mauro Carvalho Chehab
2020-10-26 14:52 ` Srinivas Kandagatla
2020-10-23 16:33 ` [PATCH v3 29/56] spi: fix a typo inside " Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 30/56] uio: fix some kernel-doc markups Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 31/56] usb: dwc3: fix " Mauro Carvalho Chehab
2020-10-27 6:58 ` Felipe Balbi
2020-10-28 9:08 ` Greg Kroah-Hartman
2020-10-28 9:13 ` Felipe Balbi
2020-10-23 16:33 ` [PATCH v3 32/56] video: fix some " Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 33/56] vme: fix two " Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 34/56] fs: fix " Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 35/56] jbd2: " Mauro Carvalho Chehab
2020-10-23 16:57 ` Jan Kara
2020-10-23 16:33 ` [PATCH v3 36/56] locks: fix a typo at a kernel-doc markup Mauro Carvalho Chehab
2020-10-26 12:01 ` Jeff Layton
2020-10-23 16:33 ` [PATCH v3 37/56] pstore/zone: fix " Mauro Carvalho Chehab
2020-10-23 17:40 ` Kees Cook
2020-10-23 16:33 ` [PATCH v3 38/56] clk: " Mauro Carvalho Chehab
2020-11-05 2:01 ` Stephen Boyd
2020-10-23 16:33 ` [PATCH v3 39/56] completion: fix kernel-doc markups Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 40/56] firmware: stratix10-svc: " Mauro Carvalho Chehab
2020-10-27 17:31 ` Richard Gong
2020-10-23 16:33 ` [PATCH v3 41/56] connector: fix a kernel-doc markup Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 42/56] lib/crc7: " Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 43/56] hrtimer: fix kernel-doc markups Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 44/56] genirq: " Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 45/56] iio: fix a kernel-doc markup Mauro Carvalho Chehab
2020-10-29 15:43 ` Jonathan Cameron
2020-10-23 16:33 ` [PATCH v3 46/56] list: fix a typo at the " Mauro Carvalho Chehab
2020-10-23 17:55 ` Andy Shevchenko
2020-10-23 20:50 ` Paul E. McKenney
2020-10-23 16:33 ` [PATCH v3 47/56] memblock: fix kernel-doc markups Mauro Carvalho Chehab
2020-10-25 6:34 ` Mike Rapoport
2020-10-23 16:33 ` [PATCH v3 48/56] sound: " Mauro Carvalho Chehab
2020-10-23 18:26 ` Mark Brown
2020-10-26 13:46 ` Takashi Iwai
2020-10-26 14:14 ` Mauro Carvalho Chehab
2020-10-26 14:25 ` Takashi Iwai
2020-10-23 16:33 ` [PATCH v3 49/56] refcount.h: fix a kernel-doc markup Mauro Carvalho Chehab
2020-10-23 17:40 ` Kees Cook
2020-10-23 19:39 ` Peter Zijlstra
2020-10-23 19:47 ` Jonathan Corbet
2020-10-24 6:28 ` Mauro Carvalho Chehab
2020-10-26 8:10 ` Peter Zijlstra
2020-10-26 9:16 ` Mauro Carvalho Chehab
2020-10-26 9:38 ` Peter Zijlstra
2020-10-23 16:33 ` [PATCH v3 50/56] w1: " Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 51/56] audit: " Mauro Carvalho Chehab
2020-10-25 22:10 ` Paul Moore
2020-10-25 22:38 ` Mauro Carvalho Chehab
2020-10-28 0:59 ` Paul Moore
2020-10-23 16:33 ` [PATCH v3 52/56] resource: fix kernel-doc markups Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 53/56] shed: fix kernel-doc markup Mauro Carvalho Chehab
2020-10-23 17:53 ` Steven Rostedt
2020-10-26 10:07 ` Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 54/56] mm: fix kernel-doc markups Mauro Carvalho Chehab
2020-10-23 17:46 ` Matthew Wilcox
2020-10-23 16:33 ` [PATCH v3 55/56] selftests: kselftest_harness.h: partially " Mauro Carvalho Chehab
2020-10-23 17:39 ` Kees Cook [this message]
2020-10-23 16:33 ` [PATCH v3 56/56] scrpits: kernel-doc: validate kernel-doc markup with the actual names Mauro Carvalho Chehab
2020-10-23 20:02 ` kernel test robot
2020-10-23 20:34 ` kernel test robot
2020-11-05 15:00 ` Matthew Wilcox
2020-11-05 15:15 ` Jonathan Corbet
2020-11-05 15:30 ` Matthew Wilcox
2020-11-05 15:20 ` Mauro Carvalho Chehab
2020-10-23 18:12 ` [PATCH v3 00/56] Fix several bad kernel-doc markups Jakub Kicinski
2020-10-23 18:22 ` Mark Brown
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=202010231036.B41FB56D@keescook \
--to=keescook@chromium.org \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-kselftest@vger.kernel.org \
--cc=luto@amacapital.net \
--cc=mchehab+huawei@kernel.org \
--cc=shuah@kernel.org \
--cc=wad@chromium.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).