Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
From:   "Martin K. Petersen" <martin.petersen@oracle.com>
To:     jejb@linux.ibm.com, Lee Jones <lee.jones@linaro.org>
Cc:     "Martin K . Petersen" <martin.petersen@oracle.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:   Wed, 15 Jul 2020 18:14:33 -0400
Message-Id: <159484884355.21107.3732344826044180939.b4-ty@oracle.com>
In-Reply-To: <20200713080001.128044-1-lee.jones@linaro.org>
References: <20200713080001.128044-1-lee.jones@linaro.org>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

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.

[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

-- 
Martin K. Petersen	Oracle Linux Engineering