diff --git a/src/cocoa_platform.h b/src/cocoa_platform.h
index f8bfe3e6..21d83bcc 100644
--- a/src/cocoa_platform.h
+++ b/src/cocoa_platform.h
@@ -41,6 +41,9 @@
 typedef void* id;
 #endif
 
+// NOTE: Many Cocoa enum values have been renamed and we need to build across
+//       SDK versions where one is unavailable or the other deprecated
+//       We use the newer names in code and these macros to handle compatibility
 #if MAC_OS_X_VERSION_MAX_ALLOWED < 101200
  #define NSBitmapFormatAlphaNonpremultiplied NSAlphaNonpremultipliedBitmapFormat
  #define NSEventMaskAny NSAnyEventMask
diff --git a/src/nsgl_context.h b/src/nsgl_context.h
index 2c8eb23f..edd958e1 100644
--- a/src/nsgl_context.h
+++ b/src/nsgl_context.h
@@ -24,6 +24,9 @@
 //
 //========================================================================
 
+// NOTE: Many Cocoa enum values have been renamed and we need to build across
+//       SDK versions where one is unavailable or the other deprecated
+//       We use the newer names in code and these macros to handle compatibility
 #if MAC_OS_X_VERSION_MAX_ALLOWED < 101400
  #define NSOpenGLContextParameterSwapInterval NSOpenGLCPSwapInterval
  #define NSOpenGLContextParameterSurfaceOpacity NSOpenGLCPSurfaceOpacity