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

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'

Cc: Christian Koenig <christian.koenig@amd.com>
Cc: Huang Rui <ray.huang@amd.com>
Cc: David Airlie <airlied@linux.ie>
Cc: Daniel Vetter <daniel@ffwll.ch>
Cc: dri-devel@lists.freedesktop.org
Signed-off-by: Lee Jones <lee.jones@linaro.org>

---
 drivers/gpu/drm/ttm/ttm_tt.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

-- 
2.25.1

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

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.

Regards,
Christian.

>

> Cc: Christian Koenig <christian.koenig@amd.com>

> Cc: Huang Rui <ray.huang@amd.com>

> Cc: David Airlie <airlied@linux.ie>

> Cc: Daniel Vetter <daniel@ffwll.ch>

> Cc: dri-devel@lists.freedesktop.org

> Signed-off-by: Lee Jones <lee.jones@linaro.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)


_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

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

> > Cc: Christian Koenig <christian.koenig@amd.com>
> > Cc: Huang Rui <ray.huang@amd.com>
> > Cc: David Airlie <airlied@linux.ie>
> > Cc: Daniel Vetter <daniel@ffwll.ch>
> > Cc: dri-devel@lists.freedesktop.org
> > Signed-off-by: Lee Jones <lee.jones@linaro.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)
>

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@amd.com>
> > > Cc: Huang Rui <ray.huang@amd.com>
> > > Cc: David Airlie <airlied@linux.ie>
> > > Cc: Daniel Vetter <daniel@ffwll.ch>
> > > Cc: dri-devel@lists.freedesktop.org
> > > Signed-off-by: Lee Jones <lee.jones@linaro.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