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

[Daniel Vetter]

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@xxxxxxx>
> > > Cc: Huang Rui <ray.huang@xxxxxxx>
> > > Cc: David Airlie <airlied@xxxxxxxx>
> > > Cc: Daniel Vetter <daniel@xxxxxxxx>
> > > Cc: dri-devel@xxxxxxxxxxxxxxxxxxxxx
> > > Signed-off-by: Lee Jones <lee.jones@xxxxxxxxxx>
> > > ---
> > >   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