The opening comment mark '/**' is used for highlighting the beginning of
kernel-doc comments.
There are files in drivers/net/wireless/rsi which follow this syntax in
their file headers, i.e. start with '/**' like comments, which causes
unexpected warnings from kernel-doc.
E.g., running scripts/kernel-doc -none on drivers/net/wireless/rsi/rsi_coex.h
causes this warning:
"warning: wrong kernel-doc identifier on line:
* Copyright (c) 2018 Redpine Signals Inc."
Similarly for other files too.
Provide a simple fix by replacing the kernel-doc like comment syntax with
general format, i.e. "/*", to prevent kernel-doc from parsing it.
* The patch series applies perfectly on next-20210312
Aditya Srivastava (10):
rsi: rsi_boot_params: fix file header comment syntax
rsi: rsi_coex: fix file header comment syntax
rsi: rsi_ps: fix file header comment syntax
rsi: rsi_common: fix file header comment syntax
rsi: rsi_mgmt: fix file header comment syntax
rsi: rsi_main: fix file header comment syntax
rsi: rsi_hal: fix file header comment syntax
rsi: rsi_debugfs: fix file header comment syntax
rsi: rsi_sdio: fix file header comment syntax
rsi: rsi_usb: fix file header comment syntax
drivers/net/wireless/rsi/rsi_boot_params.h | 2 +-
drivers/net/wireless/rsi/rsi_coex.h | 2 +-
drivers/net/wireless/rsi/rsi_common.h | 2 +-
drivers/net/wireless/rsi/rsi_debugfs.h | 2 +-
drivers/net/wireless/rsi/rsi_hal.h | 2 +-
drivers/net/wireless/rsi/rsi_main.h | 2 +-
drivers/net/wireless/rsi/rsi_mgmt.h | 2 +-
drivers/net/wireless/rsi/rsi_ps.h | 2 +-
drivers/net/wireless/rsi/rsi_sdio.h | 2 +-
drivers/net/wireless/rsi/rsi_usb.h | 2 +-
10 files changed, 10 insertions(+), 10 deletions(-)
--
2.17.1
The opening comment mark '/**' is used for highlighting the beginning of
kernel-doc comments.
The header comment used in drivers/net/wireless/rsi/rsi_boot_params.h
follows kernel-doc syntax, i.e. starts with '/**'. But the content
inside the comment does not comply with kernel-doc specifications (i.e.,
function, struct, etc).
This causes unwelcomed warning from kernel-doc:
"warning: wrong kernel-doc identifier on line:
* Copyright (c) 2014 Redpine Signals Inc."
Replace this comment syntax with general comment format, i.e. '/*' to
prevent kernel-doc from parsing these
Signed-off-by: Aditya Srivastava <[email protected]>
---
drivers/net/wireless/rsi/rsi_boot_params.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/drivers/net/wireless/rsi/rsi_boot_params.h b/drivers/net/wireless/rsi/rsi_boot_params.h
index c1cf19d1e376..30e03aa6a529 100644
--- a/drivers/net/wireless/rsi/rsi_boot_params.h
+++ b/drivers/net/wireless/rsi/rsi_boot_params.h
@@ -1,4 +1,4 @@
-/**
+/*
* Copyright (c) 2014 Redpine Signals Inc.
*
* Permission to use, copy, modify, and/or distribute this software for any
--
2.17.1
The opening comment mark '/**' is used for highlighting the beginning of
kernel-doc comments.
The header comment used in drivers/net/wireless/rsi/rsi_coex.h
follows kernel-doc syntax, i.e. starts with '/**'. But the content
inside the comment does not comply with kernel-doc specifications (i.e.,
function, struct, etc).
This causes unwelcomed warning from kernel-doc:
"warning: wrong kernel-doc identifier on line:
* Copyright (c) 2018 Redpine Signals Inc."
Replace this comment syntax with general comment format, i.e. '/*' to
prevent kernel-doc from parsing it.
Signed-off-by: Aditya Srivastava <[email protected]>
---
drivers/net/wireless/rsi/rsi_coex.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/drivers/net/wireless/rsi/rsi_coex.h b/drivers/net/wireless/rsi/rsi_coex.h
index 0fdc67f37a56..2c14e4c651b9 100644
--- a/drivers/net/wireless/rsi/rsi_coex.h
+++ b/drivers/net/wireless/rsi/rsi_coex.h
@@ -1,4 +1,4 @@
-/**
+/*
* Copyright (c) 2018 Redpine Signals Inc.
*
* Permission to use, copy, modify, and/or distribute this software for any
--
2.17.1
The opening comment mark '/**' is used for highlighting the beginning of
kernel-doc comments.
The header comment used in drivers/net/wireless/rsi/rsi_common.h
follows kernel-doc syntax, i.e. starts with '/**'. But the content
inside the comment does not comply with kernel-doc specifications (i.e.,
function, struct, etc).
This causes unwelcomed warning from kernel-doc:
"warning: wrong kernel-doc identifier on line:
* Copyright (c) 2014 Redpine Signals Inc."
Replace this comment syntax with general comment format, i.e. '/*' to
prevent kernel-doc from parsing it.
Signed-off-by: Aditya Srivastava <[email protected]>
---
drivers/net/wireless/rsi/rsi_common.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/drivers/net/wireless/rsi/rsi_common.h b/drivers/net/wireless/rsi/rsi_common.h
index 60f1f286b030..7aa5124575cf 100644
--- a/drivers/net/wireless/rsi/rsi_common.h
+++ b/drivers/net/wireless/rsi/rsi_common.h
@@ -1,4 +1,4 @@
-/**
+/*
* Copyright (c) 2014 Redpine Signals Inc.
*
* Permission to use, copy, modify, and/or distribute this software for any
--
2.17.1
The opening comment mark '/**' is used for highlighting the beginning of
kernel-doc comments.
The header comment used in drivers/net/wireless/rsi/rsi_mgmt.h
follows kernel-doc syntax, i.e. starts with '/**'. But the content
inside the comment does not comply with kernel-doc specifications (i.e.,
function, struct, etc).
This causes unwelcomed warning from kernel-doc:
"warning: wrong kernel-doc identifier on line:
* Copyright (c) 2014 Redpine Signals Inc."
Replace this comment syntax with general comment format, i.e. '/*' to
prevent kernel-doc from parsing it.
Signed-off-by: Aditya Srivastava <[email protected]>
---
drivers/net/wireless/rsi/rsi_mgmt.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/drivers/net/wireless/rsi/rsi_mgmt.h b/drivers/net/wireless/rsi/rsi_mgmt.h
index 2ce2dcf57441..236b21482f38 100644
--- a/drivers/net/wireless/rsi/rsi_mgmt.h
+++ b/drivers/net/wireless/rsi/rsi_mgmt.h
@@ -1,4 +1,4 @@
-/**
+/*
* Copyright (c) 2014 Redpine Signals Inc.
*
* Permission to use, copy, modify, and/or distribute this software for any
--
2.17.1
The opening comment mark '/**' is used for highlighting the beginning of
kernel-doc comments.
The header comment used in drivers/net/wireless/rsi/rsi_main.h
follows kernel-doc syntax, i.e. starts with '/**'. But the content
inside the comment does not comply with kernel-doc specifications (i.e.,
function, struct, etc).
This causes unwelcomed warning from kernel-doc:
"warning: wrong kernel-doc identifier on line:
* Copyright (c) 2014 Redpine Signals Inc."
Replace this comment syntax with general comment format, i.e. '/*' to
prevent kernel-doc from parsing it.
Signed-off-by: Aditya Srivastava <[email protected]>
---
drivers/net/wireless/rsi/rsi_main.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/drivers/net/wireless/rsi/rsi_main.h b/drivers/net/wireless/rsi/rsi_main.h
index 73a19e43106b..a1065e5a92b4 100644
--- a/drivers/net/wireless/rsi/rsi_main.h
+++ b/drivers/net/wireless/rsi/rsi_main.h
@@ -1,4 +1,4 @@
-/**
+/*
* Copyright (c) 2014 Redpine Signals Inc.
*
* Permission to use, copy, modify, and/or distribute this software for any
--
2.17.1
The opening comment mark '/**' is used for highlighting the beginning of
kernel-doc comments.
The header comment used in drivers/net/wireless/rsi/rsi_debugfs.h
follows kernel-doc syntax, i.e. starts with '/**'. But the content
inside the comment does not comply with kernel-doc specifications (i.e.,
function, struct, etc).
This causes unwelcomed warning from kernel-doc:
"warning: wrong kernel-doc identifier on line:
* Copyright (c) 2014 Redpine Signals Inc."
Replace this comment syntax with general comment format, i.e. '/*' to
prevent kernel-doc from parsing it.
Signed-off-by: Aditya Srivastava <[email protected]>
---
drivers/net/wireless/rsi/rsi_debugfs.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/drivers/net/wireless/rsi/rsi_debugfs.h b/drivers/net/wireless/rsi/rsi_debugfs.h
index 580ad3b3f710..a6a28640ad40 100644
--- a/drivers/net/wireless/rsi/rsi_debugfs.h
+++ b/drivers/net/wireless/rsi/rsi_debugfs.h
@@ -1,4 +1,4 @@
-/**
+/*
* Copyright (c) 2014 Redpine Signals Inc.
*
* Permission to use, copy, modify, and/or distribute this software for any
--
2.17.1
The opening comment mark '/**' is used for highlighting the beginning of
kernel-doc comments.
The header comment used in drivers/net/wireless/rsi/rsi_sdio.h
follows kernel-doc syntax, i.e. starts with '/**'. But the content
inside the comment does not comply with kernel-doc specifications (i.e.,
function, struct, etc).
This causes unwelcomed warning from kernel-doc:
"warning: Cannot understand * @section LICENSE
on line 2 - I thought it was a doc line"
Replace this comment syntax with general comment format, i.e. '/*' to
prevent kernel-doc from parsing it.
Signed-off-by: Aditya Srivastava <[email protected]>
---
drivers/net/wireless/rsi/rsi_sdio.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/drivers/net/wireless/rsi/rsi_sdio.h b/drivers/net/wireless/rsi/rsi_sdio.h
index 1c756263cf15..7c91b126b350 100644
--- a/drivers/net/wireless/rsi/rsi_sdio.h
+++ b/drivers/net/wireless/rsi/rsi_sdio.h
@@ -1,4 +1,4 @@
-/**
+/*
* @section LICENSE
* Copyright (c) 2014 Redpine Signals Inc.
*
--
2.17.1
The opening comment mark '/**' is used for highlighting the beginning of
kernel-doc comments.
The header comment used in drivers/net/wireless/rsi/rsi_hal.h
follows kernel-doc syntax, i.e. starts with '/**'. But the content
inside the comment does not comply with kernel-doc specifications (i.e.,
function, struct, etc).
This causes unwelcomed warning from kernel-doc:
"warning: wrong kernel-doc identifier on line:
* Copyright (c) 2017 Redpine Signals Inc."
Replace this comment syntax with general comment format, i.e. '/*' to
prevent kernel-doc from parsing it.
Signed-off-by: Aditya Srivastava <[email protected]>
---
drivers/net/wireless/rsi/rsi_hal.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/drivers/net/wireless/rsi/rsi_hal.h b/drivers/net/wireless/rsi/rsi_hal.h
index 46e36df9e8e3..d044a440fa08 100644
--- a/drivers/net/wireless/rsi/rsi_hal.h
+++ b/drivers/net/wireless/rsi/rsi_hal.h
@@ -1,4 +1,4 @@
-/**
+/*
* Copyright (c) 2017 Redpine Signals Inc.
*
* Permission to use, copy, modify, and/or distribute this software for any
--
2.17.1
The opening comment mark '/**' is used for highlighting the beginning of
kernel-doc comments.
The header comment used in drivers/net/wireless/rsi/rsi_usb.h
follows kernel-doc syntax, i.e. starts with '/**'. But the content
inside the comment does not comply with kernel-doc specifications (i.e.,
function, struct, etc).
This causes unwelcomed warning from kernel-doc:
"warning: Cannot understand * @section LICENSE
on line 2 - I thought it was a doc line"
Replace this comment syntax with general comment format, i.e. '/*' to
prevent kernel-doc from parsing it.
Signed-off-by: Aditya Srivastava <[email protected]>
---
drivers/net/wireless/rsi/rsi_usb.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/drivers/net/wireless/rsi/rsi_usb.h b/drivers/net/wireless/rsi/rsi_usb.h
index 8702f434b569..254d19b66412 100644
--- a/drivers/net/wireless/rsi/rsi_usb.h
+++ b/drivers/net/wireless/rsi/rsi_usb.h
@@ -1,4 +1,4 @@
-/**
+/*
* @section LICENSE
* Copyright (c) 2014 Redpine Signals Inc.
*
--
2.17.1
On Sun, Mar 14, 2021 at 9:18 PM Aditya Srivastava <[email protected]> wrote:
>
> The opening comment mark '/**' is used for highlighting the beginning of
> kernel-doc comments.
> There are files in drivers/net/wireless/rsi which follow this syntax in
> their file headers, i.e. start with '/**' like comments, which causes
> unexpected warnings from kernel-doc.
>
> E.g., running scripts/kernel-doc -none on drivers/net/wireless/rsi/rsi_coex.h
> causes this warning:
> "warning: wrong kernel-doc identifier on line:
> * Copyright (c) 2018 Redpine Signals Inc."
>
> Similarly for other files too.
>
> Provide a simple fix by replacing the kernel-doc like comment syntax with
> general format, i.e. "/*", to prevent kernel-doc from parsing it.
>
Aditya, thanks for starting to clean up the repository following your
investigation on kernel-doc warnings.
The changes to all those files look sound.
However I think these ten patches are really just _one change_, and
hence, all can be put into a single commit.
Hints that suggest it is one change:
- The commit message is pretty much the same (same motivation, same
explanation, same design decisions)
- The change is basically the same (same resulting change in different files)
- All patches are sent to the same responsible people, all of the
patches would be reviewed and accepted by the same people.
- All ten patches can be reviewed at once.
How about merging all ten patches into one patch and sending out a v2.
Lukas
Lukas Bulwahn <[email protected]> writes:
> On Sun, Mar 14, 2021 at 9:18 PM Aditya Srivastava <[email protected]> wrote:
>>
>> The opening comment mark '/**' is used for highlighting the beginning of
>> kernel-doc comments.
>> There are files in drivers/net/wireless/rsi which follow this syntax in
>> their file headers, i.e. start with '/**' like comments, which causes
>> unexpected warnings from kernel-doc.
>>
>> E.g., running scripts/kernel-doc -none on drivers/net/wireless/rsi/rsi_coex.h
>> causes this warning:
>> "warning: wrong kernel-doc identifier on line:
>> * Copyright (c) 2018 Redpine Signals Inc."
>>
>> Similarly for other files too.
>>
>> Provide a simple fix by replacing the kernel-doc like comment syntax with
>> general format, i.e. "/*", to prevent kernel-doc from parsing it.
>>
>
> Aditya, thanks for starting to clean up the repository following your
> investigation on kernel-doc warnings.
>
> The changes to all those files look sound.
>
> However I think these ten patches are really just _one change_, and
> hence, all can be put into a single commit.
I agree, this is one logical change to a single driver so one patch will
suffice. I think for cleanup changes like this one patch per driver is a
good approach.
--
https://patchwork.kernel.org/project/linux-wireless/list/
https://wireless.wiki.kernel.org/en/developers/documentation/submittingpatches
On 15/3/21 2:11 pm, Kalle Valo wrote:
> Lukas Bulwahn <[email protected]> writes:
>
>> On Sun, Mar 14, 2021 at 9:18 PM Aditya Srivastava <[email protected]> wrote:
>>>
>>> The opening comment mark '/**' is used for highlighting the beginning of
>>> kernel-doc comments.
>>> There are files in drivers/net/wireless/rsi which follow this syntax in
>>> their file headers, i.e. start with '/**' like comments, which causes
>>> unexpected warnings from kernel-doc.
>>>
>>> E.g., running scripts/kernel-doc -none on drivers/net/wireless/rsi/rsi_coex.h
>>> causes this warning:
>>> "warning: wrong kernel-doc identifier on line:
>>> * Copyright (c) 2018 Redpine Signals Inc."
>>>
>>> Similarly for other files too.
>>>
>>> Provide a simple fix by replacing the kernel-doc like comment syntax with
>>> general format, i.e. "/*", to prevent kernel-doc from parsing it.
>>>
>>
>> Aditya, thanks for starting to clean up the repository following your
>> investigation on kernel-doc warnings.
>>
>> The changes to all those files look sound.
>>
>> However I think these ten patches are really just _one change_, and
>> hence, all can be put into a single commit.
>
> I agree, this is one logical change to a single driver so one patch will
> suffice. I think for cleanup changes like this one patch per driver is a
> good approach.
>
Thanks for the feedback Lukas and Kalle. I will be sending the
modified v2.
Thanks
Aditya