linux-kernel - Re: [PATCH 2/2] remoteproc: Fix various kernel-doc warnings

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <YLBeaE8IWlmDjHaY@builder.lan>
Date:   Thu, 27 May 2021 22:07:20 -0500
From:   Bjorn Andersson <bjorn.andersson@...aro.org>
To:     Mathieu Poirier <mathieu.poirier@...aro.org>
Cc:     Suman Anna <s-anna@...com>, linux-remoteproc@...r.kernel.org,
        linux-arm-kernel@...ts.infradead.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH 2/2] remoteproc: Fix various kernel-doc warnings

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@...aro.org>
> 

Thanks Mathieu, and thanks Suman.

Regards,
Bjorn