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;
Date:   Tue, 17 Nov 2020 20:14:51 +0100
From:   Daniel Vetter <daniel@ffwll.ch>
To:     Lee Jones <lee.jones@linaro.org>
Cc:     Christian =?iso-8859-1?Q?K=F6nig?= <christian.koenig@amd.com>,
        linux-kernel@vger.kernel.org, Huang Rui <ray.huang@amd.com>,
        David Airlie <airlied@linux.ie>,
        Daniel Vetter <daniel@ffwll.ch>,
        dri-devel@lists.freedesktop.org
Subject: Re: [PATCH 32/42] drm/ttm/ttm_tt: Demote kernel-doc header format
 abuses
Message-ID: <20201117191451.GT401619@phenom.ffwll.local>
Mail-Followup-To: Lee Jones <lee.jones@linaro.org>,
        Christian =?iso-8859-1?Q?K=F6nig?= <christian.koenig@amd.com>,
        linux-kernel@vger.kernel.org, Huang Rui <ray.huang@amd.com>,
        David Airlie <airlied@linux.ie>, dri-devel@lists.freedesktop.org
References: <20201116174112.1833368-1-lee.jones@linaro.org>
 <20201116174112.1833368-33-lee.jones@linaro.org>
 <bcb40255-312f-8cdb-28a8-7ee2e6596f90@amd.com>
 <20201117083346.GB1869941@dell>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <20201117083346.GB1869941@dell>
Precedence: bulk

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

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