2021-05-21 06:46:08

by Aditya Srivastava

Subject: [PATCH] Phonet: fix kernel-doc syntax in file headers

The opening comment mark '/**' is used for highlighting the beginning of
kernel-doc comments.
The header for include/*/linux/phonet.h files follows this syntax, but
the content inside does not comply with kernel-doc.

This line was probably not meant for kernel-doc parsing, but is parsed
due to the presence of kernel-doc like comment syntax(i.e, '/**'), which
causes unexpected warning from kernel-doc.
For e.g., running scripts/kernel-doc -none include/linux/phonet.h emits:
warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
* file phonet.h

Provide a simple fix by replacing this occurrence with general comment
format, i.e. '/*', to prevent kernel-doc from parsing it.

Signed-off-by: Aditya Srivastava <[email protected]>
---
include/linux/phonet.h | 2 +-
include/uapi/linux/phonet.h | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/include/linux/phonet.h b/include/linux/phonet.h
index bc7d1e529efc..09ecb1f94c5e 100644
--- a/include/linux/phonet.h
+++ b/include/linux/phonet.h
@@ -1,5 +1,5 @@
/* SPDX-License-Identifier: GPL-2.0-only */
-/**
+/*
* file phonet.h
*
* Phonet sockets kernel interface
diff --git a/include/uapi/linux/phonet.h b/include/uapi/linux/phonet.h
index a2f6b37a5937..6b873c460994 100644
--- a/include/uapi/linux/phonet.h
+++ b/include/uapi/linux/phonet.h
@@ -1,5 +1,5 @@
/* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
-/**
+/*
* file phonet.h
*
* Phonet sockets kernel interface
--
2.17.1

2021-05-21 06:50:48

by Randy Dunlap

Subject: Re: [PATCH] Phonet: fix kernel-doc syntax in file headers

On 5/20/21 11:21 AM, Aditya Srivastava wrote:
> The opening comment mark '/**' is used for highlighting the beginning of
> kernel-doc comments.
> The header for include/*/linux/phonet.h files follows this syntax, but
> the content inside does not comply with kernel-doc.
>
> This line was probably not meant for kernel-doc parsing, but is parsed
> due to the presence of kernel-doc like comment syntax(i.e, '/**'), which
> causes unexpected warning from kernel-doc.
> For e.g., running scripts/kernel-doc -none include/linux/phonet.h emits:
> warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> * file phonet.h
>
> Provide a simple fix by replacing this occurrence with general comment
> format, i.e. '/*', to prevent kernel-doc from parsing it.
>
> Signed-off-by: Aditya Srivastava <[email protected]>

Hi,
This all looks good, but it would be even better to remove
the file names. We tend to prefer not to have filenames in their files
because they get moved or renamed -- and because it's redundant info.

Anyway,
Acked-by: Randy Dunlap <[email protected]>

Thanks.

> ---
> include/linux/phonet.h | 2 +-
> include/uapi/linux/phonet.h | 2 +-
> 2 files changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/include/linux/phonet.h b/include/linux/phonet.h
> index bc7d1e529efc..09ecb1f94c5e 100644
> --- a/include/linux/phonet.h
> +++ b/include/linux/phonet.h
> @@ -1,5 +1,5 @@
> /* SPDX-License-Identifier: GPL-2.0-only */
> -/**
> +/*
> * file phonet.h
> *
> * Phonet sockets kernel interface
> diff --git a/include/uapi/linux/phonet.h b/include/uapi/linux/phonet.h
> index a2f6b37a5937..6b873c460994 100644
> --- a/include/uapi/linux/phonet.h
> +++ b/include/uapi/linux/phonet.h
> @@ -1,5 +1,5 @@
> /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
> -/**
> +/*
> * file phonet.h
> *
> * Phonet sockets kernel interface
>


--
~Randy

2021-05-22 09:36:42

by Rémi Denis-Courmont

Subject: Re: [PATCH] Phonet: fix kernel-doc syntax in file headers

Le jeudi 20 mai 2021, 21:21:59 EEST Aditya Srivastava a ?crit :
> The opening comment mark '/**' is used for highlighting the beginning of
> kernel-doc comments.
> The header for include/*/linux/phonet.h files follows this syntax, but
> the content inside does not comply with kernel-doc.
>
> This line was probably not meant for kernel-doc parsing, but is parsed
> due to the presence of kernel-doc like comment syntax(i.e, '/**'), which
> causes unexpected warning from kernel-doc.
> For e.g., running scripts/kernel-doc -none include/linux/phonet.h emits:
> warning: This comment starts with '/**', but isn't a kernel-doc comment.
> Refer Documentation/doc-guide/kernel-doc.rst * file phonet.h
>
> Provide a simple fix by replacing this occurrence with general comment
> format, i.e. '/*', to prevent kernel-doc from parsing it.
>
> Signed-off-by: Aditya Srivastava <[email protected]>

You could just as well remove the stray "file XX" lines but OK.

Acked-by: R?mi Denis-Courmont <[email protected].>

--
R?mi Denis-Courmont

2021-05-22 11:28:14

by Aditya Srivastava

Subject: Re: [PATCH] Phonet: fix kernel-doc syntax in file headers

On 22/5/21 2:57 pm, Rémi Denis-Courmont wrote:
> Le jeudi 20 mai 2021, 21:21:59 EEST Aditya Srivastava a écrit :
>> The opening comment mark '/**' is used for highlighting the beginning of
>> kernel-doc comments.
>> The header for include/*/linux/phonet.h files follows this syntax, but
>> the content inside does not comply with kernel-doc.
>>
>> This line was probably not meant for kernel-doc parsing, but is parsed
>> due to the presence of kernel-doc like comment syntax(i.e, '/**'), which
>> causes unexpected warning from kernel-doc.
>> For e.g., running scripts/kernel-doc -none include/linux/phonet.h emits:
>> warning: This comment starts with '/**', but isn't a kernel-doc comment.
>> Refer Documentation/doc-guide/kernel-doc.rst * file phonet.h
>>
>> Provide a simple fix by replacing this occurrence with general comment
>> format, i.e. '/*', to prevent kernel-doc from parsing it.
>>
>> Signed-off-by: Aditya Srivastava <[email protected]>
>
> You could just as well remove the stray "file XX" lines but OK.
>
> Acked-by: Rémi Denis-Courmont <[email protected].>
>


Hi Remi and Randy
Thanks for reviewing :)
I'll be sending a v2 with removed filenames

Thanks
Aditya

2021-05-22 11:37:37

by Aditya Srivastava

Subject: [PATCH v2] Phonet: fix kernel-doc syntax in file headers and remove file names

The opening comment mark '/**' is used for highlighting the beginning of
kernel-doc comments.
For e.g., the header for include/linux/phonet.h follows this syntax, but
the content inside does not comply with kernel-doc.

This line was probably not meant for kernel-doc parsing, but is parsed
due to the presence of kernel-doc like comment syntax(i.e, '/**'), which
causes unexpected warning from kernel-doc:
warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
* file phonet.h

Provide a simple fix by replacing this occurrence with general comment
format, i.e. '/*', to prevent kernel-doc from parsing it.

Also remove the redundant file name from the comment headers.

Signed-off-by: Aditya Srivastava <[email protected]>
---
Changes in v2:
- Remove file name information from comment headers as well, as suggested by Randy and Remi

include/linux/phonet.h | 4 +---
include/uapi/linux/phonet.h | 4 +---
2 files changed, 2 insertions(+), 6 deletions(-)

diff --git a/include/linux/phonet.h b/include/linux/phonet.h
index bc7d1e529efc..6117a0e462d3 100644
--- a/include/linux/phonet.h
+++ b/include/linux/phonet.h
@@ -1,7 +1,5 @@
/* SPDX-License-Identifier: GPL-2.0-only */
-/**
- * file phonet.h
- *
+/*
* Phonet sockets kernel interface
*
* Copyright (C) 2008 Nokia Corporation. All rights reserved.
diff --git a/include/uapi/linux/phonet.h b/include/uapi/linux/phonet.h
index a2f6b37a5937..e7e14b5e59c6 100644
--- a/include/uapi/linux/phonet.h
+++ b/include/uapi/linux/phonet.h
@@ -1,7 +1,5 @@
/* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
-/**
- * file phonet.h
- *
+/*
* Phonet sockets kernel interface
*
* Copyright (C) 2008 Nokia Corporation. All rights reserved.
--
2.17.1

2021-05-22 15:17:34

by Randy Dunlap

Subject: Re: [PATCH v2] Phonet: fix kernel-doc syntax in file headers and remove file names

On 5/22/21 4:34 AM, Aditya Srivastava wrote:
> The opening comment mark '/**' is used for highlighting the beginning of
> kernel-doc comments.
> For e.g., the header for include/linux/phonet.h follows this syntax, but
> the content inside does not comply with kernel-doc.
>
> This line was probably not meant for kernel-doc parsing, but is parsed
> due to the presence of kernel-doc like comment syntax(i.e, '/**'), which
> causes unexpected warning from kernel-doc:
> warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> * file phonet.h
>
> Provide a simple fix by replacing this occurrence with general comment
> format, i.e. '/*', to prevent kernel-doc from parsing it.
>
> Also remove the redundant file name from the comment headers.
>
> Signed-off-by: Aditya Srivastava <[email protected]>

Acked-by: Randy Dunlap <[email protected]>

Thanks.

> ---
> Changes in v2:
> - Remove file name information from comment headers as well, as suggested by Randy and Remi
>
> include/linux/phonet.h | 4 +---
> include/uapi/linux/phonet.h | 4 +---
> 2 files changed, 2 insertions(+), 6 deletions(-)
>
> diff --git a/include/linux/phonet.h b/include/linux/phonet.h
> index bc7d1e529efc..6117a0e462d3 100644
> --- a/include/linux/phonet.h
> +++ b/include/linux/phonet.h
> @@ -1,7 +1,5 @@
> /* SPDX-License-Identifier: GPL-2.0-only */
> -/**
> - * file phonet.h
> - *
> +/*
> * Phonet sockets kernel interface
> *
> * Copyright (C) 2008 Nokia Corporation. All rights reserved.
> diff --git a/include/uapi/linux/phonet.h b/include/uapi/linux/phonet.h
> index a2f6b37a5937..e7e14b5e59c6 100644
> --- a/include/uapi/linux/phonet.h
> +++ b/include/uapi/linux/phonet.h
> @@ -1,7 +1,5 @@
> /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
> -/**
> - * file phonet.h
> - *
> +/*
> * Phonet sockets kernel interface
> *
> * Copyright (C) 2008 Nokia Corporation. All rights reserved.
>


--
~Randy

2021-05-23 08:13:29

by Rémi Denis-Courmont

Subject: Re: [PATCH v2] Phonet: fix kernel-doc syntax in file headers and remove file names

Le samedi 22 mai 2021, 14:34:08 EEST Aditya Srivastava a ?crit :
> The opening comment mark '/**' is used for highlighting the beginning of
> kernel-doc comments.
> For e.g., the header for include/linux/phonet.h follows this syntax, but
> the content inside does not comply with kernel-doc.
>
> This line was probably not meant for kernel-doc parsing, but is parsed
> due to the presence of kernel-doc like comment syntax(i.e, '/**'), which
> causes unexpected warning from kernel-doc:
> warning: This comment starts with '/**', but isn't a kernel-doc comment.
> Refer Documentation/doc-guide/kernel-doc.rst * file phonet.h
>
> Provide a simple fix by replacing this occurrence with general comment
> format, i.e. '/*', to prevent kernel-doc from parsing it.
>
> Also remove the redundant file name from the comment headers.
>
> Signed-off-by: Aditya Srivastava <[email protected]>

Acked-by: R?mi Denis-Courmont <[email protected]>

> ---
> Changes in v2:
> - Remove file name information from comment headers as well, as suggested by
> Randy and Remi
>
> include/linux/phonet.h | 4 +---
> include/uapi/linux/phonet.h | 4 +---
> 2 files changed, 2 insertions(+), 6 deletions(-)
>
> diff --git a/include/linux/phonet.h b/include/linux/phonet.h
> index bc7d1e529efc..6117a0e462d3 100644
> --- a/include/linux/phonet.h
> +++ b/include/linux/phonet.h
> @@ -1,7 +1,5 @@
> /* SPDX-License-Identifier: GPL-2.0-only */
> -/**
> - * file phonet.h
> - *
> +/*
> * Phonet sockets kernel interface
> *
> * Copyright (C) 2008 Nokia Corporation. All rights reserved.
> diff --git a/include/uapi/linux/phonet.h b/include/uapi/linux/phonet.h
> index a2f6b37a5937..e7e14b5e59c6 100644
> --- a/include/uapi/linux/phonet.h
> +++ b/include/uapi/linux/phonet.h
> @@ -1,7 +1,5 @@
> /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
> -/**
> - * file phonet.h
> - *
> +/*
> * Phonet sockets kernel interface
> *
> * Copyright (C) 2008 Nokia Corporation. All rights reserved.


--
R?mi Denis-Courmont