* [PATCH] Phonet: fix kernel-doc syntax in file headers @ 2021-05-20 18:21 ` Aditya Srivastava 0 siblings, 0 replies; 14+ messages in thread From: Aditya Srivastava @ 2021-05-20 18:21 UTC (permalink / raw) To: courmisch Cc: yashsri421, lukas.bulwahn, rdunlap, linux-kernel-mentees, linux-doc, linux-kernel 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 <yashsri421@gmail.com> --- 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 ^ permalink raw reply related [flat|nested] 14+ messages in thread
* [PATCH] Phonet: fix kernel-doc syntax in file headers @ 2021-05-20 18:21 ` Aditya Srivastava 0 siblings, 0 replies; 14+ messages in thread From: Aditya Srivastava @ 2021-05-20 18:21 UTC (permalink / raw) To: courmisch Cc: linux-doc, rdunlap, linux-kernel, yashsri421, linux-kernel-mentees 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 <yashsri421@gmail.com> --- 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 _______________________________________________ Linux-kernel-mentees mailing list Linux-kernel-mentees@lists.linuxfoundation.org https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees ^ permalink raw reply related [flat|nested] 14+ messages in thread
* Re: [PATCH] Phonet: fix kernel-doc syntax in file headers 2021-05-20 18:21 ` Aditya Srivastava @ 2021-05-20 18:30 ` Randy Dunlap -1 siblings, 0 replies; 14+ messages in thread From: Randy Dunlap @ 2021-05-20 18:30 UTC (permalink / raw) To: Aditya Srivastava, courmisch Cc: lukas.bulwahn, linux-kernel-mentees, linux-doc, linux-kernel 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 <yashsri421@gmail.com> 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 <rdunlap@infradead.org> 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 ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH] Phonet: fix kernel-doc syntax in file headers @ 2021-05-20 18:30 ` Randy Dunlap 0 siblings, 0 replies; 14+ messages in thread From: Randy Dunlap @ 2021-05-20 18:30 UTC (permalink / raw) To: Aditya Srivastava, courmisch Cc: linux-kernel-mentees, linux-kernel, linux-doc 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 <yashsri421@gmail.com> 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 <rdunlap@infradead.org> 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 _______________________________________________ Linux-kernel-mentees mailing list Linux-kernel-mentees@lists.linuxfoundation.org https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH] Phonet: fix kernel-doc syntax in file headers 2021-05-20 18:21 ` Aditya Srivastava @ 2021-05-22 9:27 ` Rémi Denis-Courmont -1 siblings, 0 replies; 14+ messages in thread From: Rémi Denis-Courmont @ 2021-05-22 9:27 UTC (permalink / raw) To: Aditya Srivastava Cc: courmisch, lukas.bulwahn, rdunlap, linux-kernel-mentees, linux-doc, linux-kernel 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 <yashsri421@gmail.com> You could just as well remove the stray "file XX" lines but OK. Acked-by: Rémi Denis-Courmont <courmisch@gmail.com.> -- Rémi Denis-Courmont ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH] Phonet: fix kernel-doc syntax in file headers @ 2021-05-22 9:27 ` Rémi Denis-Courmont 0 siblings, 0 replies; 14+ messages in thread From: Rémi Denis-Courmont @ 2021-05-22 9:27 UTC (permalink / raw) To: Aditya Srivastava Cc: linux-doc, rdunlap, linux-kernel, courmisch, linux-kernel-mentees 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 <yashsri421@gmail.com> You could just as well remove the stray "file XX" lines but OK. Acked-by: Rémi Denis-Courmont <courmisch@gmail.com.> -- Rémi Denis-Courmont _______________________________________________ Linux-kernel-mentees mailing list Linux-kernel-mentees@lists.linuxfoundation.org https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH] Phonet: fix kernel-doc syntax in file headers 2021-05-22 9:27 ` Rémi Denis-Courmont @ 2021-05-22 11:26 ` Aditya Srivastava -1 siblings, 0 replies; 14+ messages in thread From: Aditya Srivastava @ 2021-05-22 11:26 UTC (permalink / raw) To: Rémi Denis-Courmont Cc: courmisch, lukas.bulwahn, rdunlap, linux-kernel-mentees, linux-doc, linux-kernel 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 <yashsri421@gmail.com> > > You could just as well remove the stray "file XX" lines but OK. > > Acked-by: Rémi Denis-Courmont <courmisch@gmail.com.> > Hi Remi and Randy Thanks for reviewing :) I'll be sending a v2 with removed filenames Thanks Aditya ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH] Phonet: fix kernel-doc syntax in file headers @ 2021-05-22 11:26 ` Aditya Srivastava 0 siblings, 0 replies; 14+ messages in thread From: Aditya Srivastava @ 2021-05-22 11:26 UTC (permalink / raw) To: Rémi Denis-Courmont Cc: linux-doc, rdunlap, linux-kernel, courmisch, linux-kernel-mentees 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 <yashsri421@gmail.com> > > You could just as well remove the stray "file XX" lines but OK. > > Acked-by: Rémi Denis-Courmont <courmisch@gmail.com.> > Hi Remi and Randy Thanks for reviewing :) I'll be sending a v2 with removed filenames Thanks Aditya _______________________________________________ Linux-kernel-mentees mailing list Linux-kernel-mentees@lists.linuxfoundation.org https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees ^ permalink raw reply [flat|nested] 14+ messages in thread
* [PATCH v2] Phonet: fix kernel-doc syntax in file headers and remove file names 2021-05-22 9:27 ` Rémi Denis-Courmont @ 2021-05-22 11:34 ` Aditya Srivastava -1 siblings, 0 replies; 14+ messages in thread From: Aditya Srivastava @ 2021-05-22 11:34 UTC (permalink / raw) To: courmisch Cc: yashsri421, lukas.bulwahn, rdunlap, linux-kernel-mentees, linux-doc, linux-kernel 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 <yashsri421@gmail.com> --- 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 ^ permalink raw reply related [flat|nested] 14+ messages in thread
* [PATCH v2] Phonet: fix kernel-doc syntax in file headers and remove file names @ 2021-05-22 11:34 ` Aditya Srivastava 0 siblings, 0 replies; 14+ messages in thread From: Aditya Srivastava @ 2021-05-22 11:34 UTC (permalink / raw) To: courmisch Cc: linux-doc, rdunlap, linux-kernel, yashsri421, linux-kernel-mentees 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 <yashsri421@gmail.com> --- 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 _______________________________________________ Linux-kernel-mentees mailing list Linux-kernel-mentees@lists.linuxfoundation.org https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees ^ permalink raw reply related [flat|nested] 14+ messages in thread
* Re: [PATCH v2] Phonet: fix kernel-doc syntax in file headers and remove file names 2021-05-22 11:34 ` Aditya Srivastava @ 2021-05-22 15:16 ` Randy Dunlap -1 siblings, 0 replies; 14+ messages in thread From: Randy Dunlap @ 2021-05-22 15:16 UTC (permalink / raw) To: Aditya Srivastava, courmisch Cc: lukas.bulwahn, linux-kernel-mentees, linux-doc, linux-kernel 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 <yashsri421@gmail.com> Acked-by: Randy Dunlap <rdunlap@infradead.org> 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 ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH v2] Phonet: fix kernel-doc syntax in file headers and remove file names @ 2021-05-22 15:16 ` Randy Dunlap 0 siblings, 0 replies; 14+ messages in thread From: Randy Dunlap @ 2021-05-22 15:16 UTC (permalink / raw) To: Aditya Srivastava, courmisch Cc: linux-kernel-mentees, linux-kernel, linux-doc 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 <yashsri421@gmail.com> Acked-by: Randy Dunlap <rdunlap@infradead.org> 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 _______________________________________________ Linux-kernel-mentees mailing list Linux-kernel-mentees@lists.linuxfoundation.org https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH v2] Phonet: fix kernel-doc syntax in file headers and remove file names 2021-05-22 11:34 ` Aditya Srivastava @ 2021-05-23 8:11 ` Rémi Denis-Courmont -1 siblings, 0 replies; 14+ messages in thread From: Rémi Denis-Courmont @ 2021-05-23 8:11 UTC (permalink / raw) To: Aditya Srivastava Cc: courmisch, lukas.bulwahn, rdunlap, linux-kernel-mentees, linux-doc, linux-kernel 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 <yashsri421@gmail.com> Acked-by: Rémi Denis-Courmont <courmisch@gmail.com> > --- > 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 ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH v2] Phonet: fix kernel-doc syntax in file headers and remove file names @ 2021-05-23 8:11 ` Rémi Denis-Courmont 0 siblings, 0 replies; 14+ messages in thread From: Rémi Denis-Courmont @ 2021-05-23 8:11 UTC (permalink / raw) To: Aditya Srivastava Cc: linux-doc, rdunlap, linux-kernel, courmisch, linux-kernel-mentees 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 <yashsri421@gmail.com> Acked-by: Rémi Denis-Courmont <courmisch@gmail.com> > --- > 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 _______________________________________________ Linux-kernel-mentees mailing list Linux-kernel-mentees@lists.linuxfoundation.org https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees ^ permalink raw reply [flat|nested] 14+ messages in thread
end of thread, other threads:[~2021-05-23 8:11 UTC | newest] Thread overview: 14+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2021-05-20 18:21 [PATCH] Phonet: fix kernel-doc syntax in file headers Aditya Srivastava 2021-05-20 18:21 ` Aditya Srivastava 2021-05-20 18:30 ` Randy Dunlap 2021-05-20 18:30 ` Randy Dunlap 2021-05-22 9:27 ` Rémi Denis-Courmont 2021-05-22 9:27 ` Rémi Denis-Courmont 2021-05-22 11:26 ` Aditya Srivastava 2021-05-22 11:26 ` Aditya Srivastava 2021-05-22 11:34 ` [PATCH v2] Phonet: fix kernel-doc syntax in file headers and remove file names Aditya Srivastava 2021-05-22 11:34 ` Aditya Srivastava 2021-05-22 15:16 ` Randy Dunlap 2021-05-22 15:16 ` Randy Dunlap 2021-05-23 8:11 ` Rémi Denis-Courmont 2021-05-23 8:11 ` Rémi Denis-Courmont
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.