linux-kernel - Re: [PATCH] [PATCH 1/1] staging: erofs: Add function comment for erofs/super.c

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: Windows password security audit tool. GUI, reports in PDF.

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

Date:   Sun, 17 Mar 2019 12:11:12 +0100
From:   Greg KH <gregkh@...uxfoundation.org>
To:     Arshad Hussain <arshad.super@...il.com>
Cc:     linux-erofs@...ts.ozlabs.org, gaoxiang25@...wei.com,
        devel@...verdev.osuosl.org, linux-kernel@...r.kernel.org,
        yuchao0@...wei.com
Subject: Re: [PATCH] [PATCH 1/1] staging: erofs: Add function comment for
 erofs/super.c

On Wed, Mar 13, 2019 at 02:36:40AM +0530, Arshad Hussain wrote:
> This patch adds functions comment for file erofs/super.c in
> sphinx format.
> 
> Signed-off-by: Arshad Hussain <arshad.super@...il.com>
> ---
>  drivers/staging/erofs/super.c | 135 ++++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 131 insertions(+), 4 deletions(-)
> 
> diff --git a/drivers/staging/erofs/super.c b/drivers/staging/erofs/super.c
> index 15c784fba879..60bfc3e8db7a 100644
> --- a/drivers/staging/erofs/super.c
> +++ b/drivers/staging/erofs/super.c
> @@ -30,6 +30,11 @@ static void init_once(void *ptr)
>  	inode_init_once(&vi->vfs_inode);
>  }
>  
> +/**
> + * erofs_init_inode_cache(): Create & initialize inode cache
> + *
> + * Returns: 0 on Success. Errno Otherwise.
> + */
>  static int __init erofs_init_inode_cache(void)

Why do you need kernel doc comments for local functions?  That should
not be needed.  No tool is going through this file to create
documentation, right?  And documentation is only needed for functions
that are called outside of the file at most, and usually only needed for
functions that other drivers/subsystems can call.

And for a function name like this, it is pretty obvious what it does, no
comment should be needed at all.

Same for the other changes here, I do not think it is needed at all.

thanks,

greg k-h