diff --git a/kernel/atomport-template.h b/kernel/atomport-template.h
index 68772e7..9f17635 100755
--- a/kernel/atomport-template.h
+++ b/kernel/atomport-template.h
@@ -60,7 +60,12 @@
 #define POINTER   void *
 
 
-/* Critical region protection */
+/**
+ * Critical region protection: this should disable interrupts
+ * to protect OS data structures during modification. It must
+ * allow nested calls, which means that interrupts should only
+ * be re-enabled when the outer CRITICAL_END() is reached.
+ */
 #define CRITICAL_STORE      uint8_t sreg
 #define CRITICAL_START()    sreg = SREG; cli();
 #define CRITICAL_END()      SREG = sreg
diff --git a/ports/avr/atomport.h b/ports/avr/atomport.h
index ba4dead..875bd15 100644
--- a/ports/avr/atomport.h
+++ b/ports/avr/atomport.h
@@ -54,7 +54,12 @@
 #define POINTER void *
 
 
-/* Critical region protection */
+/**
+ * Critical region protection: this should disable interrupts
+ * to protect OS data structures during modification. It must
+ * allow nested calls, which means that interrupts should only
+ * be re-enabled when the outer CRITICAL_END() is reached.
+ */
 #define CRITICAL_STORE      uint8_t sreg
 #define CRITICAL_START()    sreg = SREG; cli();
 #define CRITICAL_END()      SREG = sreg
diff --git a/ports/stm8/atomport.h b/ports/stm8/atomport.h
index caf87de..2063bfb 100644
--- a/ports/stm8/atomport.h
+++ b/ports/stm8/atomport.h
@@ -60,7 +60,12 @@
 #define POINTER  void *
 
 
-/* Critical region protection */
+/**
+ * Critical region protection: this should disable interrupts
+ * to protect OS data structures during modification. It must
+ * allow nested calls, which means that interrupts should only
+ * be re-enabled when the outer CRITICAL_END() is reached.
+ */
 
 /* COSMIC: Use inline assembler */
 #if defined(__CSMC__)