Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
MIME-Version: 1.0
References: <20190123000057.31477-1-oded.gabbay@gmail.com> <20190123000057.31477-2-oded.gabbay@gmail.com>
 <20190123122804.GB2194@rapoport-lnx> <20190123124004.GA19703@kroah.com> <20190123125502.GF4747@rapoport-lnx>
In-Reply-To: <20190123125502.GF4747@rapoport-lnx>
From:   Oded Gabbay <oded.gabbay@gmail.com>
Date:   Fri, 25 Jan 2019 22:09:17 +0200
Message-ID: <CAFCwf13JJK8BDE6DChxiMT9hOV99MBPffU0EK=aM2WrW3FxEPA@mail.gmail.com>
Subject: Re: [PATCH 01/15] habanalabs: add skeleton driver
To:     Mike Rapoport <rppt@linux.ibm.com>
Cc:     Greg KH <gregkh@linuxfoundation.org>,
        "Linux-Kernel@Vger. Kernel. Org" <linux-kernel@vger.kernel.org>,
        ogabbay@habana.ai
Content-Type: text/plain; charset="UTF-8"
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

On Wed, Jan 23, 2019 at 2:55 PM Mike Rapoport <rppt@linux.ibm.com> wrote:
>
> On Wed, Jan 23, 2019 at 01:40:04PM +0100, Greg KH wrote:
> > On Wed, Jan 23, 2019 at 02:28:05PM +0200, Mike Rapoport wrote:
> > > On Wed, Jan 23, 2019 at 02:00:43AM +0200, Oded Gabbay wrote:
> > > > +/**
> > > > + * hl_device_release - release function for habanalabs device
> > > > + *
> > > > + * @inode: pointer to inode structure
> > > > + * @filp: pointer to file structure
> > > > + *
> > > > + * Called when process closes an habanalabs device
> > > > + */
> > >
> > > It's nice to see docs coming along with the codei
> > > I have some comments for the formatting.
> > >
> > > kernel-doc won't be happy about missing return value descriptions, and
> > > although they are sometimes redundant or too obvious their absence makes
> > > 'make V=1 htmldocs' really noisy.
> > >
> > > In general, it would be nice if you could link hanabnalabs driver
> > > kernel-doc somewhere in Documentation/ run 'make V=1 htmldocs'.
> > >
> > > > +static int hl_device_release(struct inode *inode, struct file *filp)
> >
> > There's no need for kerneldoc comments for static functions, as no one
> > can call them and they are not part of any api.
> >
> > So what would be better here is to just drop the /** line and use /*
>
> Maybe it'd make sense to use /* for most of the comments in this driver as
> there are kernel-doc formatting issues in non-static functions as well, I
> was just too lazy to go over all of them.
>
Hi Mike,
That's what I'm going to do for v2, except for the comments in
habanalabs.h, which we made sure are written according to kernel-doc.
I promise that we will go over the entire code and make everything
kernel-doc compatible (I'm opening a jira ticket now :) ) but it may
take a couple of weeks or more.

In any case, I fixed all of your other comments for this patch.
Thanks,
Oded

> > thanks,
> >
> > greg k-h
> >
>
> --
> Sincerely yours,
> Mike.
>