From: Lee Jones <lee.jones@linaro.org>
To: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: jejb@linux.ibm.com, linux-scsi@vger.kernel.org,
linux-kernel@vger.kernel.org
Subject: Re: [PATCH v2 00/24] Set 3: Fix another set of SCSI related W=1 warnings
Date: Thu, 16 Jul 2020 08:14:45 +0100 [thread overview]
Message-ID: <20200716071445.GK3165313@dell> (raw)
In-Reply-To: <159484884355.21107.3732344826044180939.b4-ty@oracle.com>
On Wed, 15 Jul 2020, Martin K. Petersen wrote:
> On Mon, 13 Jul 2020 08:59:37 +0100, Lee Jones wrote:
>
> > This set is part of a larger effort attempting to clean-up W=1
> > kernel builds, which are currently overwhelmingly riddled with
> > niggly little warnings.
> >
> > Slowly working through the SCSI related ones. There are many.
> >
> > This brings the total of W=1 SCSI wanings from 1690 in v5.8-rc1 to 1109.
> >
> > [...]
>
> Applied to 5.9/scsi-queue. Thanks for cleaning things up!
>
> I do think that in general it makes little sense for low-level drivers
> to document internal functions using kerneldoc. As a general approach
> I would prefer to just switch drivers to '/*' or to remove stale
> comments instead of trying to keep up with the "docrot" warnings.
>
> kerneldoc cleanups are great for functions that actually have more
> than one user (core code, libraries, common code used by multiple
> drivers, etc.). Whereas for driver internals I would much rather
> emphasize function arguments with well-chosen, descriptive names
> instead of a kerneldoc "@p: pointer to a foobar" comment that will
> inevitably become stale next time an interface changes.
I'm inclined to agree.
There is even a script to list the 'offenders':
`scripts/find-unused-docs.sh`
An effort to demote all unused docs is likely to be somewhat more
controversial than one to re-sync the attribute/parameter
descriptions though. I choose the path of least resistance for my
clean-up effort. Nothing stopping us having another pass once they
are all re-synced.
> [01/24] scsi: aacraid: Repair two kerneldoc headers
> https://git.kernel.org/mkp/scsi/c/b115958d91f5
> [02/24] scsi: aacraid: Fix a few kerneldoc issues
> https://git.kernel.org/mkp/scsi/c/cf93fffac261
> [03/24] scsi: aacraid: Fix logical bug when !DBG
> https://git.kernel.org/mkp/scsi/c/2fee77e5b820
> [04/24] scsi: aacraid: Remove unused variable 'status'
> https://git.kernel.org/mkp/scsi/c/0123c7c62d6c
> [05/24] scsi: aacraid: Demote partially documented function header
> https://git.kernel.org/mkp/scsi/c/71aa4d3e0e78
> [06/24] scsi: aic94xx: Document 'lseq' and repair asd_update_port_links() header
> https://git.kernel.org/mkp/scsi/c/966fdadf6fea
> [07/24] scsi: aacraid: Fix a bunch of function header issues
> https://git.kernel.org/mkp/scsi/c/f1134f0eb184
> [08/24] scsi: aic94xx: Fix a couple of formatting and bitrot issues
> https://git.kernel.org/mkp/scsi/c/d2e510505006
> [09/24] scsi: aacraid: Fill in the very parameter descriptions for rx_sync_cmd()
> https://git.kernel.org/mkp/scsi/c/ae272a95133a
> [10/24] scsi: pm8001: Provide descriptions for the many undocumented 'attr's
> https://git.kernel.org/mkp/scsi/c/e1c3e0f8a2ae
> [11/24] scsi: ipr: Fix a mountain of kerneldoc misdemeanours
> https://git.kernel.org/mkp/scsi/c/a96099e2c164
> [12/24] scsi: virtio_scsi: Demote seemingly unintentional kerneldoc header
> https://git.kernel.org/mkp/scsi/c/e31f2661ff41
> [13/24] scsi: ipr: Remove a bunch of set but checked variables
> https://git.kernel.org/mkp/scsi/c/4dc833999e37
> [14/24] scsi: ipr: Fix struct packed-not-aligned issues
> https://git.kernel.org/mkp/scsi/c/f3bdc59f9b11
> [15/24] scsi: myrs: Demote obvious misuse of kerneldoc to standard comment blocks
> https://git.kernel.org/mkp/scsi/c/8a692fdb1d04
> [17/24] scsi: be2iscsi: Fix API/documentation slip
> https://git.kernel.org/mkp/scsi/c/abad069ef0da
> [18/24] scsi: be2iscsi: Fix misdocumentation of 'pcontext'
> https://git.kernel.org/mkp/scsi/c/dbc019a48f97
> [19/24] scsi: be2iscsi: Add missing function parameter description
> https://git.kernel.org/mkp/scsi/c/7405edfdfb96
> [20/24] scsi: lpfc: Correct some pretty obvious misdocumentation
> https://git.kernel.org/mkp/scsi/c/09d99705b5d2
> [21/24] scsi: aic7xxx: Remove unused variable 'ahd'
> https://git.kernel.org/mkp/scsi/c/91b6e191c4dc
> [22/24] scsi: aic7xxx: Remove unused variables 'wait' and 'paused'
> https://git.kernel.org/mkp/scsi/c/532d56c631f1
> [23/24] scsi: aic7xxx: Fix 'amount_xferred' set but not used issue
> https://git.kernel.org/mkp/scsi/c/42b840bcfc16
>
--
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog
next prev parent reply other threads:[~2020-07-16 7:14 UTC|newest]
Thread overview: 48+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-07-13 7:59 [PATCH v2 00/24] Set 3: Fix another set of SCSI related W=1 warnings Lee Jones
2020-07-13 7:59 ` [PATCH v2 01/24] scsi: aacraid: aachba: Repair two kerneldoc headers Lee Jones
2020-07-13 7:59 ` [PATCH v2 02/24] scsi: aacraid: commctrl: Fix a few kerneldoc issues Lee Jones
2020-07-13 7:59 ` [PATCH v2 03/24] scsi: aacraid: dpcsup: Fix logical bug when !DBG Lee Jones
2020-07-13 7:59 ` [PATCH v2 04/24] scsi: aacraid: dpcsup: Remove unused variable 'status' Lee Jones
2020-07-13 7:59 ` [PATCH v2 05/24] scsi: aacraid: dpcsup: Demote partially documented function header Lee Jones
2020-07-13 7:59 ` [PATCH v2 06/24] scsi: aic94xx: aic94xx_seq: Document 'lseq' and repair asd_update_port_links() header Lee Jones
2020-07-13 7:59 ` [PATCH v2 07/24] scsi: aacraid: commsup: Fix a bunch of function header issues Lee Jones
2020-07-13 7:59 ` Lee Jones
2020-07-13 7:59 ` [PATCH v2 08/24] scsi: aic94xx: aic94xx_scb: Fix a couple of formatting and bitrot issues Lee Jones
2020-07-13 7:59 ` [PATCH v2 09/24] scsi: aacraid: rx: Fill in the very parameter descriptions for rx_sync_cmd() Lee Jones
2020-07-13 7:59 ` [PATCH v2 10/24] scsi: pm8001: pm8001_ctl: Provide descriptions for the many undocumented 'attr's Lee Jones
2020-07-13 8:18 ` Jinpu Wang
2020-07-13 7:59 ` [PATCH v2 11/24] scsi: ipr: Fix a mountain of kerneldoc misdemeanours Lee Jones
2020-07-13 7:59 ` [PATCH v2 12/24] scsi: virtio_scsi: Demote seemingly unintentional kerneldoc header Lee Jones
2020-07-13 7:59 ` Lee Jones
2020-07-13 11:23 ` Michael S. Tsirkin
2020-07-13 11:23 ` Michael S. Tsirkin
2020-07-13 11:53 ` Lee Jones
2020-07-13 7:59 ` [PATCH v2 13/24] scsi: ipr: Remove a bunch of set but checked variables Lee Jones
2020-07-13 7:59 ` [PATCH v2 14/24] scsi: ipr: Fix struct packed-not-aligned issues Lee Jones
2020-07-13 7:59 ` [PATCH v2 15/24] scsi: myrs: Demote obvious misuse of kerneldoc to standard comment blocks Lee Jones
2020-07-14 7:45 ` Hannes Reinecke
2020-07-14 8:49 ` Lee Jones
2020-07-13 7:59 ` [PATCH v2 16/24] scsi: megaraid: Fix a whole bunch of function header formatting issues Lee Jones
2020-07-13 7:59 ` [PATCH v2 17/24] scsi: be2iscsi: be_iscsi: Fix API/documentation slip Lee Jones
2020-07-13 7:59 ` [PATCH v2 18/24] scsi: be2iscsi: be_main: Fix misdocumentation of 'pcontext' Lee Jones
2020-07-13 7:59 ` [PATCH v2 19/24] scsi: be2iscsi: be_mgmt: Add missing function parameter description Lee Jones
2020-07-13 7:59 ` [PATCH v2 20/24] scsi: lpfc: lpfc_nvme: Correct some pretty obvious misdocumentation Lee Jones
2020-07-13 7:59 ` [PATCH v2 21/24] scsi: aic7xxx: aic79xx_osm: Remove unused variable 'ahd' Lee Jones
2020-07-14 7:47 ` Hannes Reinecke
2020-07-13 7:59 ` [PATCH v2 22/24] scsi: aic7xxx: aic79xx_osm: Remove unused variables 'wait' and 'paused' Lee Jones
2020-07-14 7:47 ` Hannes Reinecke
2020-07-13 8:00 ` [PATCH v2 23/24] scsi: aic7xxx: aic79xx_osm: Fix 'amount_xferred' set but not used issue Lee Jones
2020-07-14 7:47 ` Hannes Reinecke
2020-07-13 8:00 ` [PATCH v2 24/24] scsi: aic7xxx: aic79xx_osm: Remove set but unused variabes 'saved_scsiid' and 'saved_modes' Lee Jones
2020-07-14 7:46 ` Hannes Reinecke
2020-07-14 15:43 ` James Bottomley
2020-07-14 21:39 ` Lee Jones
2020-07-14 23:03 ` James Bottomley
2020-07-15 6:29 ` Lee Jones
2020-07-21 6:38 ` Hannes Reinecke
2020-07-15 5:58 ` Hannes Reinecke
2020-07-15 6:30 ` Lee Jones
2020-07-15 22:14 ` [PATCH v2 00/24] Set 3: Fix another set of SCSI related W=1 warnings Martin K. Petersen
2020-07-16 7:14 ` Lee Jones [this message]
2020-07-16 7:16 ` Lee Jones
2020-07-16 8:00 ` Lee Jones
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200716071445.GK3165313@dell \
--to=lee.jones@linaro.org \
--cc=jejb@linux.ibm.com \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-scsi@vger.kernel.org \
--cc=martin.petersen@oracle.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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.