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:

quoted

diff --git a/drivers/remoteproc/remoteproc_elf_loader.c b/drivers/remoteproc/remoteproc_elf_loader.c

[..]

quoted

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

quoted

  * If the table wasn't loaded yet the result is unspecified.
  */

[..]

quoted

diff --git a/include/linux/remoteproc.h b/include/linux/remoteproc.h

[..]

quoted

+ * 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

[..]

quoted

 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

_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel