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:   Thu, 27 May 2021 22:07:20 -0500
From:   Bjorn Andersson <bjorn.andersson@linaro.org>
To:     Mathieu Poirier <mathieu.poirier@linaro.org>
Cc:     Suman Anna <s-anna@ti.com>, linux-remoteproc@vger.kernel.org,
        linux-arm-kernel@lists.infradead.org, linux-kernel@vger.kernel.org
Subject: Re: [PATCH 2/2] remoteproc: Fix various kernel-doc warnings
Message-ID: <YLBeaE8IWlmDjHaY@builder.lan>
References: <20210519180304.23563-1-s-anna@ti.com>
 <20210519180304.23563-3-s-anna@ti.com>
 <20210525180006.GD1113058@xps15>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20210525180006.GD1113058@xps15>
Precedence: bulk

On Tue 25 May 13:00 CDT 2021, Mathieu Poirier wrote:
> On Wed, May 19, 2021 at 01:03:04PM -0500, Suman Anna wrote:
> > diff --git a/drivers/remoteproc/remoteproc_elf_loader.c b/drivers/remoteproc/remoteproc_elf_loader.c
[..]
> > @@ -362,7 +366,7 @@ EXPORT_SYMBOL(rproc_elf_load_rsc_table);
> >   * This function finds the location of the loaded resource table. Don't
> >   * call this function if the table wasn't loaded yet - it's a bug if you do.
> >   *
> > - * Returns the pointer to the resource table if it is found or NULL otherwise.
> > + * Return: pointer to the resource table if it is found or NULL otherwise.
> 
> Here the '.' has been kept while it was remove for all of the above.  I don't
> know that the right guidelines are for this. 
> 

Reviewing https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html
I don't see that this is defined. So I'm fine with whatever looks good.

That said, the section about "Return values" shows that the "Return:
..." line should be short and concise and if needed followed by a
newline and then a longer paragraph.


I'll fix the capitalization of "the" below and apply this as is and we
can go back an reformat these multiline Return entries later...

> >   * If the table wasn't loaded yet the result is unspecified.
> >   */
[..]
> > diff --git a/include/linux/remoteproc.h b/include/linux/remoteproc.h
[..]
> > + * 2. immediately following this structure is the virtio config space for
> > + *    this vdev (which is specific to the vdev; for more info, read the virtio
> > + *    spec). the size of the config space is specified by @config_len.
> 
> s/the/The
> 
[..]
> >  struct rproc {
> > @@ -613,10 +617,10 @@ struct rproc_vring {
> >   * struct rproc_vdev - remoteproc state for a supported virtio device
> >   * @refcount: reference counter for the vdev and vring allocations
> >   * @subdev: handle for registering the vdev as a rproc subdevice
> > + * @dev: device struct used for reference count semantics
> >   * @id: virtio device id (as in virtio_ids.h)
> >   * @node: list node
> >   * @rproc: the rproc handle
> > - * @vdev: the virio device
> >   * @vring: the vrings for this vdev
> >   * @rsc_offset: offset of the vdev's resource entry
> >   * @index: vdev position versus other vdev declared in resource table
> 
> With or without the above:
> 
> Reviewed-by: Mathieu Poirier <mathieu.poirier@linaro.org>
> 

Thanks Mathieu, and thanks Suman.

Regards,
Bjorn