Re: [PATCH v2 15/24] scsi: myrs: Demote obvious misuse of kerneldoc to standard comment blocks

From: Lee Jones <lee.jones@linaro.org>
To: Hannes Reinecke <hare@suse.de>
Cc: jejb@linux.ibm.com, martin.petersen@oracle.com,
	linux-kernel@vger.kernel.org, linux-scsi@vger.kernel.org,
	Hannes Reinecke <hare@kernel.org>, Linux GmbH <hare@suse.com>,
	"Leonard N. Zubkoff" <lnz@dandelion.com>
Subject: Re: [PATCH v2 15/24] scsi: myrs: Demote obvious misuse of kerneldoc to standard comment blocks
Date: Tue, 14 Jul 2020 09:49:04 +0100	[thread overview]
Message-ID: <20200714084904.GK3500@dell> (raw)
In-Reply-To: <270f544a-19ef-cf71-220c-54e349dc6bfc@suse.de>

On Tue, 14 Jul 2020, Hannes Reinecke wrote:

> On 7/13/20 9:59 AM, Lee Jones wrote:
> > No attempt has been made to document any of the demoted functions here.
> > 
> > Fixes the following W=1 kernel build warning(s):
> > 
> >  drivers/scsi/myrs.c:94: warning: Function parameter or member 'cmd_blk' not described in 'myrs_reset_cmd'
> >  drivers/scsi/myrs.c:105: warning: Function parameter or member 'cs' not described in 'myrs_qcmd'
> >  drivers/scsi/myrs.c:105: warning: Function parameter or member 'cmd_blk' not described in 'myrs_qcmd'
> >  drivers/scsi/myrs.c:130: warning: Function parameter or member 'cs' not described in 'myrs_exec_cmd'
> >  drivers/scsi/myrs.c:130: warning: Function parameter or member 'cmd_blk' not described in 'myrs_exec_cmd'
> >  drivers/scsi/myrs.c:149: warning: Function parameter or member 'cs' not described in 'myrs_report_progress'
> >  drivers/scsi/myrs.c:149: warning: Function parameter or member 'ldev_num' not described in 'myrs_report_progress'
> >  drivers/scsi/myrs.c:149: warning: Function parameter or member 'msg' not described in 'myrs_report_progress'
> >  drivers/scsi/myrs.c:149: warning: Function parameter or member 'blocks' not described in 'myrs_report_progress'
> >  drivers/scsi/myrs.c:149: warning: Function parameter or member 'size' not described in 'myrs_report_progress'
> >  drivers/scsi/myrs.c:160: warning: Function parameter or member 'cs' not described in 'myrs_get_ctlr_info'
> >  drivers/scsi/myrs.c:222: warning: Function parameter or member 'cs' not described in 'myrs_get_ldev_info'
> >  drivers/scsi/myrs.c:222: warning: Function parameter or member 'ldev_num' not described in 'myrs_get_ldev_info'
> >  drivers/scsi/myrs.c:222: warning: Function parameter or member 'ldev_info' not described in 'myrs_get_ldev_info'
> >  drivers/scsi/myrs.c:310: warning: Function parameter or member 'cs' not described in 'myrs_get_pdev_info'
> >  drivers/scsi/myrs.c:310: warning: Function parameter or member 'channel' not described in 'myrs_get_pdev_info'
> >  drivers/scsi/myrs.c:310: warning: Function parameter or member 'target' not described in 'myrs_get_pdev_info'
> >  drivers/scsi/myrs.c:310: warning: Function parameter or member 'lun' not described in 'myrs_get_pdev_info'
> >  drivers/scsi/myrs.c:310: warning: Function parameter or member 'pdev_info' not described in 'myrs_get_pdev_info'
> >  drivers/scsi/myrs.c:353: warning: Function parameter or member 'cs' not described in 'myrs_dev_op'
> >  drivers/scsi/myrs.c:353: warning: Function parameter or member 'opcode' not described in 'myrs_dev_op'
> >  drivers/scsi/myrs.c:353: warning: Function parameter or member 'opdev' not described in 'myrs_dev_op'
> >  drivers/scsi/myrs.c:379: warning: Function parameter or member 'cs' not described in 'myrs_translate_pdev'
> >  drivers/scsi/myrs.c:379: warning: Function parameter or member 'channel' not described in 'myrs_translate_pdev'
> >  drivers/scsi/myrs.c:379: warning: Function parameter or member 'target' not described in 'myrs_translate_pdev'
> >  drivers/scsi/myrs.c:379: warning: Function parameter or member 'lun' not described in 'myrs_translate_pdev'
> >  drivers/scsi/myrs.c:379: warning: Function parameter or member 'devmap' not described in 'myrs_translate_pdev'
> >  drivers/scsi/myrs.c:422: warning: Function parameter or member 'cs' not described in 'myrs_get_event'
> >  drivers/scsi/myrs.c:422: warning: Function parameter or member 'event_num' not described in 'myrs_get_event'
> >  drivers/scsi/myrs.c:422: warning: Function parameter or member 'event_buf' not described in 'myrs_get_event'
> >  drivers/scsi/myrs.c:484: warning: Function parameter or member 'cs' not described in 'myrs_enable_mmio_mbox'
> >  drivers/scsi/myrs.c:484: warning: Function parameter or member 'enable_mbox_fn' not described in 'myrs_enable_mmio_mbox'
> >  drivers/scsi/myrs.c:584: warning: Function parameter or member 'cs' not described in 'myrs_get_config'
> >  drivers/scsi/myrs.c:688: warning: cannot understand function prototype: 'struct '
> >  drivers/scsi/myrs.c:1967: warning: Function parameter or member 'dev' not described in 'myrs_is_raid'
> >  drivers/scsi/myrs.c:1980: warning: Function parameter or member 'dev' not described in 'myrs_get_resync'
> >  drivers/scsi/myrs.c:2005: warning: Function parameter or member 'dev' not described in 'myrs_get_state'
> >  drivers/scsi/myrs.c:2343: warning: bad line:   the Error Status Register when the driver performs the BIOS handshaking.
> >  drivers/scsi/myrs.c:2344: warning: bad line:   It returns true for fatal errors and false otherwise.
> >  drivers/scsi/myrs.c:2349: warning: Function parameter or member 'cs' not described in 'myrs_err_status'
> >  drivers/scsi/myrs.c:2349: warning: Function parameter or member 'status' not described in 'myrs_err_status'
> >  drivers/scsi/myrs.c:2349: warning: Function parameter or member 'parm0' not described in 'myrs_err_status'
> >  drivers/scsi/myrs.c:2349: warning: Function parameter or member 'parm1' not described in 'myrs_err_status'
> > 
> > Cc: Hannes Reinecke <hare@kernel.org>
> > Cc: Linux GmbH <hare@suse.com>
> 
> Please, do fix your mailer/script.
> This is my company e-mail address, but my name is actually the same even
> when working for the company ...

I think it's the file that needs fixing.

If you're adamant that the formatting in the file should be accepted
then perhaps amend get_maintainer.pl instead.

To get those lines, I run:

 ./scripts/get_maintainer.pl --file-emails --git-min-percent 75 -f drivers/scsi/myrs.c

> > Cc: "Leonard N. Zubkoff" <lnz@dandelion.com>
> > Signed-off-by: Lee Jones <lee.jones@linaro.org>
> > ---
> >  drivers/scsi/myrs.c | 34 +++++++++++++++++-----------------
> >  1 file changed, 17 insertions(+), 17 deletions(-)
> > 
> I had been wanting to convert this to proper kernel-doc style, but never
> found the time to actually do it.
> So this will serve for now.
> 
> Reviewed-by: Hannes Reinecke <hare@suse.com>

Thanks for all your reviews.  Much appreciated.

-- 
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog