linux-kernel - Re: [PATCH 32/42] drm/ttm/ttm_tt: Demote kernel-doc header format abuses

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] [thread-next>] [day] [month] [year] [list]

Message-ID: <20201117191451.GT401619@phenom.ffwll.local>
Date:   Tue, 17 Nov 2020 20:14:51 +0100
From:   Daniel Vetter <daniel@...ll.ch>
To:     Lee Jones <lee.jones@...aro.org>
Cc:     Christian König <christian.koenig@....com>,
        linux-kernel@...r.kernel.org, Huang Rui <ray.huang@....com>,
        David Airlie <airlied@...ux.ie>,
        Daniel Vetter <daniel@...ll.ch>,
        dri-devel@...ts.freedesktop.org
Subject: Re: [PATCH 32/42] drm/ttm/ttm_tt: Demote kernel-doc header format
 abuses

On Tue, Nov 17, 2020 at 08:33:46AM +0000, Lee Jones wrote:
> On Mon, 16 Nov 2020, Christian König wrote:
> 
> > Am 16.11.20 um 18:41 schrieb Lee Jones:
> > > Fixes the following W=1 kernel build warning(s):
> > > 
> > >   drivers/gpu/drm/ttm/ttm_tt.c:45: warning: Function parameter or member 'bo' not described in 'ttm_tt_create'
> > >   drivers/gpu/drm/ttm/ttm_tt.c:45: warning: Function parameter or member 'zero_alloc' not described in 'ttm_tt_create'
> > >   drivers/gpu/drm/ttm/ttm_tt.c:83: warning: Function parameter or member 'ttm' not described in 'ttm_tt_alloc_page_directory'
> > 
> > Couldn't we rather describe the missing parameters? Shouldn't be much work.
> 
> My rule is; if a substantial attempt has been made to document
> something, I'll patch it up.  If little or no attempt has been made,
> then it gets demoted.
> 
> Please feel free to document and upgrade them once more.
> 
> Bear in mind however, there is a script that reports on all files
> which utilise kernel-doc notation but do not have matching references
> from the Documentation area.
> 
> See: scripts/find-unused-docs.sh

ttm docs need some serious love anyway, so I think this is fine. I applied
it.
-Daniel

> 
> > > Cc: Christian Koenig <christian.koenig@....com>
> > > Cc: Huang Rui <ray.huang@....com>
> > > Cc: David Airlie <airlied@...ux.ie>
> > > Cc: Daniel Vetter <daniel@...ll.ch>
> > > Cc: dri-devel@...ts.freedesktop.org
> > > Signed-off-by: Lee Jones <lee.jones@...aro.org>
> > > ---
> > >   drivers/gpu/drm/ttm/ttm_tt.c | 4 ++--
> > >   1 file changed, 2 insertions(+), 2 deletions(-)
> > > 
> > > diff --git a/drivers/gpu/drm/ttm/ttm_tt.c b/drivers/gpu/drm/ttm/ttm_tt.c
> > > index cfd633c7e7643..da9eeffe0c6d7 100644
> > > --- a/drivers/gpu/drm/ttm/ttm_tt.c
> > > +++ b/drivers/gpu/drm/ttm/ttm_tt.c
> > > @@ -38,7 +38,7 @@
> > >   #include <drm/drm_cache.h>
> > >   #include <drm/ttm/ttm_bo_driver.h>
> > > -/**
> > > +/*
> > >    * Allocates a ttm structure for the given BO.
> > >    */
> > >   int ttm_tt_create(struct ttm_buffer_object *bo, bool zero_alloc)
> > > @@ -73,7 +73,7 @@ int ttm_tt_create(struct ttm_buffer_object *bo, bool zero_alloc)
> > >   	return 0;
> > >   }
> > > -/**
> > > +/*
> > >    * Allocates storage for pointers to the pages that back the ttm.
> > >    */
> > >   static int ttm_tt_alloc_page_directory(struct ttm_tt *ttm)
> > 
> 
> -- 
> Lee Jones [李琼斯]
> Senior Technical Lead - Developer Services
> Linaro.org │ Open source software for Arm SoCs
> Follow Linaro: Facebook | Twitter | Blog

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch