[PATCH] drm/amd/display: Document the return values of the dc_update_state helpers
From: TAKANO Mitsuhiro
Date: Sat Nov 21 2026 - 01:15:26 EST
kernel-doc -Wall reports:
dc.h:2175 No description found for return value of
'dc_update_state_prepare'
dc.h:2190 No description found for return value of
'dc_update_state_cleanup'
Both functions return bool and their comments explain in prose what the
caller must do next, but neither has a Return: section, so kernel-doc
asks for one. Move the explanation into a Return: section and say when
the scratch slot is released.
No functional change.
Written with Hermes Agent, an LLM assistant; the author reviewed it and
ran kernel-doc on the file with and without the change.
Signed-off-by: TAKANO Mitsuhiro <takano32@xxxxxxxxx>
---
drivers/gpu/drm/amd/display/dc/dc.h | 11 +++++++----
1 file changed, 7 insertions(+), 4 deletions(-)
diff --git a/drivers/gpu/drm/amd/display/dc/dc.h b/drivers/gpu/drm/amd/display/dc/dc.h
index d3c484f45333..231a8ca2b18a 100644
--- a/drivers/gpu/drm/amd/display/dc/dc.h
+++ b/drivers/gpu/drm/amd/display/dc/dc.h
@@ -2170,8 +2170,8 @@ struct dc_update_scratch_space *dc_update_state_init(
* dc_update_state_prepare - Prepare the commit under the global lock.
* @scratch: commit scratch from dc_update_state_init()
*
- * On failure the scratch slot is released and false is returned; the caller
- * must not call execute or cleanup.
+ * Return: true on success, false on failure. On failure the scratch slot has
+ * already been released, so the caller must not call execute or cleanup.
*/
bool dc_update_state_prepare(struct dc_update_scratch_space *scratch);
@@ -2185,8 +2185,11 @@ void dc_update_state_execute(const struct dc_update_scratch_space *scratch);
* dc_update_state_cleanup - Finalise the commit and release the scratch slot.
* @scratch: commit scratch from dc_update_state_init()
*
- * Must be called with the global lock held. Returns true if the caller must
- * loop back to prepare (SEAMLESS continuation).
+ * Must be called with the global lock held.
+ *
+ * Return: true if the caller must loop back to prepare (SEAMLESS
+ * continuation), false otherwise; the scratch slot is released before false
+ * is returned.
*/
bool dc_update_state_cleanup(struct dc_update_scratch_space *scratch);
base-commit: d0f871bfb831705d9f55479f5b2b40f636ea7b16
--
2.53.0