[Qemu-devel] [RFC v2 01/15] Add an explanation of when a function should be marked coroutine_fn

[Charlie Shepherd <charlie@ctshepherd.com>]

Coroutine functions that can yield directly or indirectly should be annotated
with a coroutine_fn annotation. Add an explanation to that effect in
include/block/coroutine.h.

Signed-off-by: Charlie Shepherd <charlie@ctshepherd.com>
---
 include/block/coroutine.h | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/include/block/coroutine.h b/include/block/coroutine.h
index 1f2db3e..1aae6e9 100644
--- a/include/block/coroutine.h
+++ b/include/block/coroutine.h
@@ -37,6 +37,14 @@
  * static checker support for catching such errors.  This annotation might make
  * it possible and in the meantime it serves as documentation.
  *
+ * A function must be marked with coroutine_fn if it can yield execution, either
+ * directly or indirectly.
+ *
+ * Some functions dynamically determine whether to yield or not based on
+ * whether they are executing in a coroutine context or not. These functions
+ * do not need to be annotated coroutine_fn. Note that this practice is
+ * deprecated and is being phased out, new code should not do this.
+ *
  * For example:
  *
  *   static void coroutine_fn foo(void) {
-- 
1.8.3.2