of: overlay: Fix kerneldoc warning in of_overlay_remove()
Rob Herring
maintainerPATCH 1/1 of: overlay: Fix kerneldoc warning in of_overlay_remove()
'*ovcs_id' causes a warning because '*' is treated as bold markup:
Documentation/devicetree/kernel-api:56: ../drivers/of/overlay.c:1184: WARNING: Inline emphasis start-string without end-string.
Fix this to use the normal '@' markup for function parameters.
--- drivers/of/overlay.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/of/overlay.c +1 -1
@@ -1181,7 +1181,7 @@ static int overlay_removal_is_ok(struct overlay_changeset *remove_ovcs)* If an error is returned by an overlay changeset post-remove notifier * then no further overlay changeset post-remove notifier will be called. * -* Return: 0 on success, or a negative error number. *ovcs_id is set to +* Return: 0 on success, or a negative error number. @ovcs_id is set to * zero after reverting the changeset, even if a subsequent error occurs. */ int of_overlay_remove (int *ovcs_id)
Signature · 1 line
2.27.0
Quoted 19 lines · Rob Herring
'
*ovcs_id' causes a warning because '*' is treated as bold markup:
Documentation/devicetree/kernel-api:56:../drivers/of/overlay.c:1184: WARNING: Inline emphasis start-string without end-string.Fix this to use the normal '@' markup for function parameters.
Reported-by Stephen Rothwell <[email protected]>Cc Frank Rowand <[email protected]>Signed-off-by Rob Herring <[email protected]>--- drivers/of/overlay.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)drivers/of/overlay.c +0
-0
drivers/of/overlay.c static int overlay_removal_is_ok(struct overlay_changeset *remove_ovcs) · line 1187
Quoted 8 lines
drivers/of/overlay.c +1
-1@@ -1181,7 +1181,7 @@ static int overlay_removal_is_ok(struct overlay_changeset *remove_ovcs)* If an error is returned by an overlay changeset post-remove notifier * then no further overlay changeset post-remove notifier will be called. * -* Return: 0 on success, or a negative error number. *ovcs_id is set to +* Return: 0 on success, or a negative error number. @ovcs_id is set to * zero after reverting the changeset, even if a subsequent error occurs. */ int of_overlay_remove (int *ovcs_id)
The change results in incorrect information. I am guessing that "@*ovcs_id" would not be valid syntax (I have not tried it). The changed version says that the pointer ovcs_id is changed to zero, but the actual action is to change the value pointed to by ovcs_id is changed to zero. Is there a valid syntax to say this?
-Frank
Rob Herring
maintainerQuoted 27 lines · Frank Rowand
Quoted 25 lines · Rob Herring
'
*ovcs_id' causes a warning because '*' is treated as bold markup:
Documentation/devicetree/kernel-api:56:../drivers/of/overlay.c:1184: WARNING: Inline emphasis start-string without end-string.Fix this to use the normal '@' markup for function parameters.
Reported-by Stephen Rothwell <[email protected]>Cc Frank Rowand <[email protected]>Signed-off-by Rob Herring <[email protected]>--- drivers/of/overlay.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)drivers/of/overlay.c +1
-1@@ -1181,7 +1181,7 @@ static int overlay_removal_is_ok(struct overlay_changeset *remove_ovcs)* If an error is returned by an overlay changeset post-remove notifier * then no further overlay changeset post-remove notifier will be called. * -* Return: 0 on success, or a negative error number. *ovcs_id is set to +* Return: 0 on success, or a negative error number. @ovcs_id is set to * zero after reverting the changeset, even if a subsequent error occurs. */
Quoted 8 lines
drivers/of/overlay.c static int overlay_removal_is_ok(struct overlay_changeset *remove_ovcs) · line 1187
Quoted 2 lines
drivers/of/overlay.c +0
-0int of_overlay_remove (int *ovcs_id)The change results in incorrect information. I am guessing that "@*ovcs_id" would not be valid syntax (I have not tried it). The changed version says that the pointer
ovcs_idis changed to zero, but the actual action is to change the value pointed to byovcs_idis changed to zero. Is there a valid syntax to say this?
I was assuming the reader should know how parameters work in C... Having previously beat my head with the syntax here, I went with the easy route. Normal rSt syntax would be ``*`` to escape it. But kerneldoc isn't normal syntax. Turns out just plain "*@ovcs_id" works without warning and highlights the parameter (which was missing before).
I'll update the commit.
Rob