Skip to contentSkip to conversation

of: overlay: Fix kerneldoc warning in of_overlay_remove()

PATCH In review Rob Herring 2 participants 3 messages Apr 21, 2021 Device tree

lore
Share & tools
lore

Rob Herring

author maintainer
#0 lore raw

PATCH 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
index d241273170fd..67c9aa6f14da 100644
@@ -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
#1 lore raw
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.

---
 drivers/of/overlay.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/of/overlay.c +0 -0
index d241273170fd..67c9aa6f14da 100644

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

author maintainer
#2 lore raw
Quoted 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.

---
 drivers/of/overlay.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/of/overlay.c +1 -1
index d241273170fd..67c9aa6f14da 100644
@@ -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 -0
 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?

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