docs: Justify additional common.h file

runtime/include/arch/common.h

@@ -9,7 +9,12 @@
 #include "software_interrupt.h"
 
 /*
- * This file contains the common dependencies of the architecture-dependent code
+ * This file contains the common dependencies of the architecture-dependent code.
+ *
+ * While all of the content in this file could alternatively be placed in context.h
+ * above the conditional preprocessor includes, IDEs generally assume each file includes
+ * their own dependent headers directly and form a clean independent subtree that
+ * can be walked to resolve all symbols when the file is active
  */
 
 typedef uint64_t reg_t;

runtime/include/arch/context.h

@@ -2,12 +2,21 @@
 
 /*
  * This header is the single entry point into the arch_context code.
- * This includes both dependent and independent code
+ * It includes processor independent code and conditionally includes architecture
+ * dependent code.
  */
 
 /*
- * Conditionally load architecture-dependent code
- * Each of these headers include common.h
+ * These preprocessor conditionals load architecture-dependent code.
+ *
+ * Each of these headers include common.h, a sibling header that contains common
+ * structures, enums, and externs used by the processor independent code. Those
+ * definitions are thus transitively loaded here with the appropriate architecture
+ * specific code.
+ *
+ * While the code in common.h could be located in this file above the conditionals,
+ * structuring the code as such prevents IDEs from knowing how to resolve the
+ * symbols when aarch64/context.h or x86_64/context is the active file.
  */
 #if defined(AARCH64) || defined(aarch64)
 #include "aarch64/context.h"