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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite for Android: free password hash cracker in your pocket

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Thu, 20 May 2021 11:30:31 -0700
From:   Randy Dunlap <rdunlap@...radead.org>
To:     Aditya Srivastava <yashsri421@...il.com>, courmisch@...il.com
Cc:     lukas.bulwahn@...il.com,
        linux-kernel-mentees@...ts.linuxfoundation.org,
        linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org
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 <yashsri421@...il.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@...radead.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