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 <char...@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 4232569..e11a587 100644
--- a/include/block/coroutine.h
+++ b/include/block/coroutine.h
@@ -38,6 +38,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.4.rc3
