Re: [PATCH] xen/xenbus: client: fix kernel-doc comments
On 12/7/23 01:27, Juergen Gross wrote: > On 06.12.23 19:17, Randy Dunlap wrote: >> Correct function kernel-doc notation to prevent warnings from >> scripts/kernel-doc. >> >> >> Signed-off-by: Randy Dunlap >> Cc: Juergen Gross >> Cc: Stefano Stabellini >> Cc: Oleksandr Tyshchenko >> Cc: xen-devel@lists.xenproject.org > > Reviewed-by: Juergen Gross > > with one nit below (can be fixed while committing) ... Ah yes, thanks. -- ~Randy
Re: [PATCH] xen/xenbus: client: fix kernel-doc comments
On 06.12.23 19:17, Randy Dunlap wrote: Correct function kernel-doc notation to prevent warnings from scripts/kernel-doc. xenbus_client.c:134: warning: No description found for return value of 'xenbus_watch_path' xenbus_client.c:177: warning: No description found for return value of 'xenbus_watch_pathfmt' xenbus_client.c:258: warning: missing initial short description on line: * xenbus_switch_state xenbus_client.c:267: warning: No description found for return value of 'xenbus_switch_state' xenbus_client.c:308: warning: missing initial short description on line: * xenbus_dev_error xenbus_client.c:327: warning: missing initial short description on line: * xenbus_dev_fatal xenbus_client.c:350: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst * Equivalent to xenbus_dev_fatal(dev, err, fmt, args), but helps xenbus_client.c:457: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst * Allocate an event channel for the given xenbus_device, assigning the newly xenbus_client.c:486: warning: expecting prototype for Free an existing event channel. Returns 0 on success or(). Prototype was for xenbus_free_evtchn() instead xenbus_client.c:502: warning: missing initial short description on line: * xenbus_map_ring_valloc xenbus_client.c:517: warning: No description found for return value of 'xenbus_map_ring_valloc' xenbus_client.c:602: warning: missing initial short description on line: * xenbus_unmap_ring xenbus_client.c:614: warning: No description found for return value of 'xenbus_unmap_ring' xenbus_client.c:715: warning: missing initial short description on line: * xenbus_unmap_ring_vfree xenbus_client.c:727: warning: No description found for return value of 'xenbus_unmap_ring_vfree' xenbus_client.c:919: warning: missing initial short description on line: * xenbus_read_driver_state xenbus_client.c:926: warning: No description found for return value of 'xenbus_read_driver_state' Signed-off-by: Randy Dunlap Cc: Juergen Gross Cc: Stefano Stabellini Cc: Oleksandr Tyshchenko Cc: xen-devel@lists.xenproject.org Reviewed-by: Juergen Gross with one nit below (can be fixed while committing) ... --- drivers/xen/xenbus/xenbus_client.c | 59 +++ 1 file changed, 34 insertions(+), 25 deletions(-) diff -- a/drivers/xen/xenbus/xenbus_client.c b/drivers/xen/xenbus/xenbus_client.c --- a/drivers/xen/xenbus/xenbus_client.c +++ b/drivers/xen/xenbus/xenbus_client.c @@ -119,11 +119,13 @@ EXPORT_SYMBOL_GPL(xenbus_strstate); * @callback: callback to register * * Register a @watch on the given path, using the given xenbus_watch structure - * for storage, and the given @callback function as the callback. Return 0 on - * success, or -errno on error. On success, the given @path will be saved as - * @watch->node, and remains the caller's to free. On error, @watch->node will + * for storage, and the given @callback function as the callback. On success, + * the given @path will be saved as @watch->node, and remains the + * caller's to free. On error, @watch->node will * be NULL, the device will switch to %XenbusStateClosing, and the error will * be saved in the store. + * + * Returns: %0 on success or -errno on error */ int xenbus_watch_path(struct xenbus_device *dev, const char *path, struct xenbus_watch *watch, @@ -160,12 +162,14 @@ EXPORT_SYMBOL_GPL(xenbus_watch_path); * @pathfmt: format of path to watch * * Register a watch on the given @path, using the given xenbus_watch - * structure for storage, and the given @callback function as the callback. - * Return 0 on success, or -errno on error. On success, the watched path - * (@path/@path2) will be saved as @watch->node, and becomes the caller's to - * kfree(). On error, watch->node will be NULL, so the caller has nothing to + * structure for storage, and the given @callback function as the + * callback. On success, the watched path (@path/@path2) will be saved + * as @watch->node, and becomes the caller's to kfree(). + * On error, watch->node will be NULL, so the caller has nothing to * free, the device will switch to %XenbusStateClosing, and the error will be * saved in the store. + * + * Returns: %0 on success or -errno on error */ int xenbus_watch_pathfmt(struct xenbus_device *dev, struct xenbus_watch *watch, @@ -255,13 +259,15 @@ abort: } /** - * xenbus_switch_state + * xenbus_switch_state - save the new state of a driver * @dev: xenbus device * @state: new state * * Advertise in the store a change of the given driver to the given new_state. - * Return 0 on success, or -errno on error. On error, the device will switch - * to XenbusStateClosing, and the error will be saved in the store. + * On error, the device will switch to XenbusStateClosing, and the error + * will be saved
[PATCH] xen/xenbus: client: fix kernel-doc comments
Correct function kernel-doc notation to prevent warnings from
scripts/kernel-doc.
xenbus_client.c:134: warning: No description found for return value of
'xenbus_watch_path'
xenbus_client.c:177: warning: No description found for return value of
'xenbus_watch_pathfmt'
xenbus_client.c:258: warning: missing initial short description on line:
* xenbus_switch_state
xenbus_client.c:267: warning: No description found for return value of
'xenbus_switch_state'
xenbus_client.c:308: warning: missing initial short description on line:
* xenbus_dev_error
xenbus_client.c:327: warning: missing initial short description on line:
* xenbus_dev_fatal
xenbus_client.c:350: warning: This comment starts with '/**', but isn't a
kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
* Equivalent to xenbus_dev_fatal(dev, err, fmt, args), but helps
xenbus_client.c:457: warning: This comment starts with '/**', but isn't a
kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
* Allocate an event channel for the given xenbus_device, assigning the newly
xenbus_client.c:486: warning: expecting prototype for Free an existing event
channel. Returns 0 on success or(). Prototype was for xenbus_free_evtchn()
instead
xenbus_client.c:502: warning: missing initial short description on line:
* xenbus_map_ring_valloc
xenbus_client.c:517: warning: No description found for return value of
'xenbus_map_ring_valloc'
xenbus_client.c:602: warning: missing initial short description on line:
* xenbus_unmap_ring
xenbus_client.c:614: warning: No description found for return value of
'xenbus_unmap_ring'
xenbus_client.c:715: warning: missing initial short description on line:
* xenbus_unmap_ring_vfree
xenbus_client.c:727: warning: No description found for return value of
'xenbus_unmap_ring_vfree'
xenbus_client.c:919: warning: missing initial short description on line:
* xenbus_read_driver_state
xenbus_client.c:926: warning: No description found for return value of
'xenbus_read_driver_state'
Signed-off-by: Randy Dunlap
Cc: Juergen Gross
Cc: Stefano Stabellini
Cc: Oleksandr Tyshchenko
Cc: xen-devel@lists.xenproject.org
---
drivers/xen/xenbus/xenbus_client.c | 59 +++
1 file changed, 34 insertions(+), 25 deletions(-)
diff -- a/drivers/xen/xenbus/xenbus_client.c
b/drivers/xen/xenbus/xenbus_client.c
--- a/drivers/xen/xenbus/xenbus_client.c
+++ b/drivers/xen/xenbus/xenbus_client.c
@@ -119,11 +119,13 @@ EXPORT_SYMBOL_GPL(xenbus_strstate);
* @callback: callback to register
*
* Register a @watch on the given path, using the given xenbus_watch structure
- * for storage, and the given @callback function as the callback. Return 0 on
- * success, or -errno on error. On success, the given @path will be saved as
- * @watch->node, and remains the caller's to free. On error, @watch->node will
+ * for storage, and the given @callback function as the callback. On success,
+ * the given @path will be saved as @watch->node, and remains the
+ * caller's to free. On error, @watch->node will
* be NULL, the device will switch to %XenbusStateClosing, and the error will
* be saved in the store.
+ *
+ * Returns: %0 on success or -errno on error
*/
int xenbus_watch_path(struct xenbus_device *dev, const char *path,
struct xenbus_watch *watch,
@@ -160,12 +162,14 @@ EXPORT_SYMBOL_GPL(xenbus_watch_path);
* @pathfmt: format of path to watch
*
* Register a watch on the given @path, using the given xenbus_watch
- * structure for storage, and the given @callback function as the callback.
- * Return 0 on success, or -errno on error. On success, the watched path
- * (@path/@path2) will be saved as @watch->node, and becomes the caller's to
- * kfree(). On error, watch->node will be NULL, so the caller has nothing to
+ * structure for storage, and the given @callback function as the
+ * callback. On success, the watched path (@path/@path2) will be saved
+ * as @watch->node, and becomes the caller's to kfree().
+ * On error, watch->node will be NULL, so the caller has nothing to
* free, the device will switch to %XenbusStateClosing, and the error will be
* saved in the store.
+ *
+ * Returns: %0 on success or -errno on error
*/
int xenbus_watch_pathfmt(struct xenbus_device *dev,
struct xenbus_watch *watch,
@@ -255,13 +259,15 @@ abort:
}
/**
- * xenbus_switch_state
+ * xenbus_switch_state - save the new state of a driver
* @dev: xenbus device
* @state: new state
*
* Advertise in the store a change of the given driver to the given new_state.
- * Return 0 on success, or -errno on error. On error, the device will switch
- * to XenbusStateClosing, and the error will be saved in the store.
+ * On error, the device will switch to XenbusStateClosing, and the error
+ * will be saved in the store.
+ *
+ * Returns: %0 on success or -errno on error
*/
int xenbus_switch_state(struct xenbus_device *dev, enum xenbus_state state)
{
@@ -305,7
