diff --git a/glfw/cocoa_platform.h b/glfw/cocoa_platform.h
index 0b399d02e..4af0a54ce 100644
--- a/glfw/cocoa_platform.h
+++ b/glfw/cocoa_platform.h
@@ -36,6 +36,9 @@ typedef void* id;
 typedef void* CVDisplayLinkRef;
 #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