kernel: cpu idle: add info about IRQ unlocking in k_cpu_idle

We add a note in k_cpu_idle() documentation, stressing that for
certain architectures. the function unmasks interrupts
unconditionally before returning. In the
documentation of the architecture-specific API (arch_cpu_idle)
we describe the expected behavior with regards to the wake-up
event.

Signed-off-by: Ioannis Glaropoulos <Ioannis.Glaropoulos@nordicsemi.no>

include/kernel.h

diff --git a/include/kernel.h b/include/kernel.h
index 44f85ec..412e0e0 100644
--- a/include/kernel.h
+++ b/include/kernel.h
@@ -4999,6 +4999,9 @@
  * However, in some more constrained systems, such as a single-threaded system,
  * the only thread would be responsible for this if needed.
  *
+ * @note In some architectures, before returning, the function unmasks interrupts
+ * unconditionally.
+ *
  * @return N/A
  * @req K-CPU-IDLE-001
  */