Message-ID: <20211130123032.035e06a3.alex.williamson@redhat.com>
Date:   Tue, 30 Nov 2021 12:30:32 -0700
From:   Alex Williamson <alex.williamson@...hat.com>
To:     Randy Dunlap <rdunlap@...radead.org>
Cc:     Jason Gunthorpe <jgg@...dia.com>,
        kernel test robot <lkp@...el.com>, kbuild-all@...ts.01.org,
        linux-kernel@...r.kernel.org, Eric Auger <eric.auger@...hat.com>,
        Cornelia Huck <cohuck@...hat.com>, kvm@...r.kernel.org
Subject: Re: drivers/vfio/vfio.c:293: warning: expecting prototype for
 Container objects(). Prototype was for vfio_container_get() instead

On Wed, 10 Nov 2021 15:19:40 -0800
Randy Dunlap <rdunlap@...radead.org> wrote:

> On 11/10/21 8:42 AM, Jason Gunthorpe wrote:
> > On Wed, Nov 10, 2021 at 11:12:39PM +0800, kernel test robot wrote:  
> >> Hi Jason,
> >>
> >> FYI, the error/warning still remains.  
> > 
> > This is just a long standing kdoc misuse.
> > 
> > vfio is not W=1 kdoc clean.
> > 
> > Until someone takes a project to fix this comprehensively there is not
> > much point in reporting new complaints related the existing mis-use..  
> 
> Hi,
> 
> Can we just remove all misused "/**" comments in vfio.c until
> someone cares enough to use proper kernel-doc there?
> 
> ---
> From: Randy Dunlap <rdunlap@...radead.org>
> Subject: [PATCH] vfio/vfio: remove all kernel-doc notation
> 
> vfio.c abuses (misuses) "/**", which indicates the beginning of
> kernel-doc notation in the kernel tree. This causes a bunch of
> kernel-doc complaints about this source file, so quieten all of
> them by changing all "/**" to "/*".
> 
> vfio.c:236: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>   * IOMMU driver registration
> vfio.c:236: warning: missing initial short description on line:
>   * IOMMU driver registration
> vfio.c:295: warning: expecting prototype for Container objects(). Prototype was for vfio_container_get() instead
> vfio.c:317: warning: expecting prototype for Group objects(). Prototype was for __vfio_group_get_from_iommu() instead
> vfio.c:496: warning: Function parameter or member 'device' not described in 'vfio_device_put'
> vfio.c:496: warning: expecting prototype for Device objects(). Prototype was for vfio_device_put() instead
> vfio.c:599: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>   * Async device support
> vfio.c:599: warning: missing initial short description on line:
>   * Async device support
> vfio.c:693: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>   * VFIO driver API
> vfio.c:693: warning: missing initial short description on line:
>   * VFIO driver API
> vfio.c:835: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>   * Get a reference to the vfio_device for a device.  Even if the
> vfio.c:835: warning: missing initial short description on line:
>   * Get a reference to the vfio_device for a device.  Even if the
> vfio.c:969: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>   * VFIO base fd, /dev/vfio/vfio
> vfio.c:969: warning: missing initial short description on line:
>   * VFIO base fd, /dev/vfio/vfio
> vfio.c:1187: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>   * VFIO Group fd, /dev/vfio/$GROUP
> vfio.c:1187: warning: missing initial short description on line:
>   * VFIO Group fd, /dev/vfio/$GROUP
> vfio.c:1540: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>   * VFIO Device fd
> vfio.c:1540: warning: missing initial short description on line:
>   * VFIO Device fd
> vfio.c:1615: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>   * External user API, exported by symbols to be linked dynamically.
> vfio.c:1615: warning: missing initial short description on line:
>   * External user API, exported by symbols to be linked dynamically.
> vfio.c:1663: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>   * External user API, exported by symbols to be linked dynamically.
> vfio.c:1663: warning: missing initial short description on line:
>   * External user API, exported by symbols to be linked dynamically.
> vfio.c:1742: warning: Function parameter or member 'caps' not described in 'vfio_info_cap_add'
> vfio.c:1742: warning: Function parameter or member 'size' not described in 'vfio_info_cap_add'
> vfio.c:1742: warning: Function parameter or member 'id' not described in 'vfio_info_cap_add'
> vfio.c:1742: warning: Function parameter or member 'version' not described in 'vfio_info_cap_add'
> vfio.c:1742: warning: expecting prototype for Sub(). Prototype was for vfio_info_cap_add() instead
> vfio.c:2276: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>   * Module/class support
> vfio.c:2276: warning: missing initial short description on line:
>   * Module/class support
> 
> Signed-off-by: Randy Dunlap <rdunlap@...radead.org>
> Reported-by: kernel test robot <lkp@...el.com>
> Cc: Jason Gunthorpe <jgg@...dia.com>
> Cc: Alex Williamson <alex.williamson@...hat.com>
> Cc: Eric Auger <eric.auger@...hat.com>
> Cc: Cornelia Huck <cohuck@...hat.com>
> Cc: kvm@...r.kernel.org
> ---
>   drivers/vfio/vfio.c |   28 ++++++++++++++--------------
>   1 file changed, 14 insertions(+), 14 deletions(-)

These were never intended to be kernel-doc, thanks for the cleanup.
I've scraped this into my for-linus branch with Jason and Connie's acks
for v5.16.  Thanks,

Alex

Powered by blists - more mailing lists