Generally APIs to the rest of QEMU should be documented in the headers.
Comments on individual functions or internal details are fine to live
in the C files. Make qemu_add_vm_change_state_handler_prio[_full]()
docstrings consistent by moving them from source to header.

Suggested-by: Xiaoyao Li <xiaoyao.li@intel.com>
Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
---
Based-on: <20250703173248.44995-4-philmd@linaro.org>
---
 include/system/runstate.h | 30 ++++++++++++++++++++++++++++++
 system/runstate.c         | 30 ------------------------------
 2 files changed, 30 insertions(+), 30 deletions(-)

diff --git a/include/system/runstate.h b/include/system/runstate.h
index b6e8d6beab7..b8d1bc3d273 100644
--- a/include/system/runstate.h
+++ b/include/system/runstate.h
@@ -26,9 +26,39 @@ typedef int VMChangeStateHandlerWithRet(void *opaque, bool running, RunState sta
  */
 VMChangeStateEntry *qemu_add_vm_change_state_handler(VMChangeStateHandler *cb,
                                                      void *opaque);
+/**
+ * qemu_add_vm_change_state_handler_prio:
+ * @cb: the callback to invoke
+ * @opaque: user data passed to the callback
+ * @priority: low priorities execute first when the vm runs and the reverse is
+ *            true when the vm stops
+ *
+ * Register a callback function that is invoked when the vm starts or stops
+ * running.
+ *
+ * Returns: an entry to be freed using qemu_del_vm_change_state_handler()
+ */
 VMChangeStateEntry *qemu_add_vm_change_state_handler_prio(
         VMChangeStateHandler *cb, void *opaque, int priority);
 VMChangeStateEntry *
+/**
+ * qemu_add_vm_change_state_handler_prio_full:
+ * @cb: the main callback to invoke
+ * @prepare_cb: a callback to invoke before the main callback
+ * @cb_ret: the main callback to invoke with return value
+ * @opaque: user data passed to the callbacks
+ * @priority: low priorities execute first when the vm runs and the reverse is
+ *            true when the vm stops
+ *
+ * Register a main callback function and an optional prepare callback function
+ * that are invoked when the vm starts or stops running. The main callback and
+ * the prepare callback are called in two separate phases: First all prepare
+ * callbacks are called and only then all main callbacks are called. As its
+ * name suggests, the prepare callback can be used to do some preparatory work
+ * before invoking the main callback.
+ *
+ * Returns: an entry to be freed using qemu_del_vm_change_state_handler()
+ */
 qemu_add_vm_change_state_handler_prio_full(VMChangeStateHandler *cb,
                                            VMChangeStateHandler *prepare_cb,
                                            VMChangeStateHandlerWithRet *cb_ret,
diff --git a/system/runstate.c b/system/runstate.c
index 38900c935a3..fa32aa47958 100644
--- a/system/runstate.c
+++ b/system/runstate.c
@@ -306,18 +306,6 @@ struct VMChangeStateEntry {
 static QTAILQ_HEAD(, VMChangeStateEntry) vm_change_state_head =
     QTAILQ_HEAD_INITIALIZER(vm_change_state_head);
 
-/**
- * qemu_add_vm_change_state_handler_prio:
- * @cb: the callback to invoke
- * @opaque: user data passed to the callback
- * @priority: low priorities execute first when the vm runs and the reverse is
- *            true when the vm stops
- *
- * Register a callback function that is invoked when the vm starts or stops
- * running.
- *
- * Returns: an entry to be freed using qemu_del_vm_change_state_handler()
- */
 VMChangeStateEntry *qemu_add_vm_change_state_handler_prio(
         VMChangeStateHandler *cb, void *opaque, int priority)
 {
@@ -325,24 +313,6 @@ VMChangeStateEntry *qemu_add_vm_change_state_handler_prio(
                                                       opaque, priority);
 }
 
-/**
- * qemu_add_vm_change_state_handler_prio_full:
- * @cb: the main callback to invoke
- * @prepare_cb: a callback to invoke before the main callback
- * @cb_ret: the main callback to invoke with return value
- * @opaque: user data passed to the callbacks
- * @priority: low priorities execute first when the vm runs and the reverse is
- *            true when the vm stops
- *
- * Register a main callback function and an optional prepare callback function
- * that are invoked when the vm starts or stops running. The main callback and
- * the prepare callback are called in two separate phases: First all prepare
- * callbacks are called and only then all main callbacks are called. As its
- * name suggests, the prepare callback can be used to do some preparatory work
- * before invoking the main callback.
- *
- * Returns: an entry to be freed using qemu_del_vm_change_state_handler()
- */
 VMChangeStateEntry *
 qemu_add_vm_change_state_handler_prio_full(VMChangeStateHandler *cb,
                                            VMChangeStateHandler *prepare_cb,
-- 
2.49.0

On Tue, Jul 15, 2025 at 07:19:20PM +0200, Philippe Mathieu-Daudé wrote:
> Date: Tue, 15 Jul 2025 19:19:20 +0200
> From: Philippe Mathieu-Daudé <philmd@linaro.org>
> Subject: [PATCH-for-10.1] system/runstate: Document
>  qemu_add_vm_change_state_handler_prio* in hdr
> X-Mailer: git-send-email 2.49.0
> 
> Generally APIs to the rest of QEMU should be documented in the headers.
> Comments on individual functions or internal details are fine to live
> in the C files. Make qemu_add_vm_change_state_handler_prio[_full]()
> docstrings consistent by moving them from source to header.
> 
> Suggested-by: Xiaoyao Li <xiaoyao.li@intel.com>
> Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
> ---
> Based-on: <20250703173248.44995-4-philmd@linaro.org>
> ---
>  include/system/runstate.h | 30 ++++++++++++++++++++++++++++++
>  system/runstate.c         | 30 ------------------------------
>  2 files changed, 30 insertions(+), 30 deletions(-)

Reviewed-by: Zhao Liu <zhao1.liu@intel.com>

On 7/16/2025 1:19 AM, Philippe Mathieu-Daudé wrote:
> Generally APIs to the rest of QEMU should be documented in the headers.
> Comments on individual functions or internal details are fine to live
> in the C files. Make qemu_add_vm_change_state_handler_prio[_full]()
> docstrings consistent by moving them from source to header.
> 
> Suggested-by: Xiaoyao Li <xiaoyao.li@intel.com>
> Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>

Reviewed-by: Xiaoyao Li <xiaoyao.li@intel.com>

> ---
> Based-on: <20250703173248.44995-4-philmd@linaro.org>
> ---
>   include/system/runstate.h | 30 ++++++++++++++++++++++++++++++
>   system/runstate.c         | 30 ------------------------------
>   2 files changed, 30 insertions(+), 30 deletions(-)
> 

On 15/7/25 19:19, Philippe Mathieu-Daudé wrote:
> Generally APIs to the rest of QEMU should be documented in the headers.
> Comments on individual functions or internal details are fine to live
> in the C files. Make qemu_add_vm_change_state_handler_prio[_full]()
> docstrings consistent by moving them from source to header.
> 
> Suggested-by: Xiaoyao Li <xiaoyao.li@intel.com>
> Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
> ---
> Based-on: <20250703173248.44995-4-philmd@linaro.org>
> ---
>   include/system/runstate.h | 30 ++++++++++++++++++++++++++++++
>   system/runstate.c         | 30 ------------------------------
>   2 files changed, 30 insertions(+), 30 deletions(-)

Queued, thanks.

On 7/15/25 10:19 AM, Philippe Mathieu-Daudé wrote:
> Generally APIs to the rest of QEMU should be documented in the headers.
> Comments on individual functions or internal details are fine to live
> in the C files. Make qemu_add_vm_change_state_handler_prio[_full]()
> docstrings consistent by moving them from source to header.
> 
> Suggested-by: Xiaoyao Li <xiaoyao.li@intel.com>
> Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
> ---
> Based-on: <20250703173248.44995-4-philmd@linaro.org>
> ---
>   include/system/runstate.h | 30 ++++++++++++++++++++++++++++++
>   system/runstate.c         | 30 ------------------------------
>   2 files changed, 30 insertions(+), 30 deletions(-)

Reviewed-by: Pierrick Bouvier <pierrick.bouvier@linaro.org>