Improved documentation of hacks.

deps/GL/glext.h

@@ -4130,6 +4130,9 @@ GLAPI void APIENTRY glVertexBlendARB (GLint count);
 
 #ifndef GL_ARB_vertex_buffer_object
 #define GL_ARB_vertex_buffer_object 1
+/* HACK: This is a workaround for gltypes.h on OS X 10.9 defining these types as
+ *       long instead of ptrdiff_t
+ */
 #if defined(__APPLE__)
 typedef long GLsizeiptrARB;
 typedef long GLintptrARB;

src/cocoa_window.m

@@ -67,7 +67,7 @@ static void enterFullscreenMode(_GLFWwindow* window)
                              withOptions:options];
 
     // HACK: Synthesize focus event as window does not become key when the view
-    // is made full screen
+    //       is made full screen
     // TODO: Remove this when moving to a full screen window
     _glfwInputWindowFocus(window, GL_TRUE);
 }
@@ -80,7 +80,7 @@ static void leaveFullscreenMode(_GLFWwindow* window)
         return;
 
     // HACK: Synthesize focus event as window does not become key when the view
-    // is made full screen
+    //       is made full screen
     // TODO: Remove this when moving to a full screen window
     _glfwInputWindowFocus(window, GL_FALSE);
 
@@ -1036,6 +1036,9 @@ void _glfwPlatformRestoreWindow(_GLFWwindow* window)
 void _glfwPlatformShowWindow(_GLFWwindow* window)
 {
     // Make us the active application
+    // HACK: This has been moved here from initializeAppKit to prevent
+    //       applications using only hidden windows from being activated, but
+    //       should probably not be done every time any window is shown
     [NSApp activateIgnoringOtherApps:YES];
 
     [window->ns.object makeKeyAndOrderFront:nil];

src/context.c

@@ -402,8 +402,8 @@ GLboolean _glfwRefreshContextAttribs(void)
             else if (glfwExtensionSupported("GL_ARB_debug_output"))
             {
                 // HACK: This is a workaround for older drivers (pre KHR_debug)
-                // not setting the debug bit in the context flags for debug
+                //       not setting the debug bit in the context flags for
-                // contexts
+                //       debug contexts
                 window->glDebug = GL_TRUE;
             }
         }

src/glx_context.c

@@ -75,7 +75,7 @@ static GLboolean chooseFBConfig(const _GLFWfbconfig* desired, GLXFBConfig* resul
     if (strcmp(vendor, "Chromium") == 0)
     {
         // HACK: This is a (hopefully temporary) workaround for Chromium
-        // (VirtualBox GL) not setting the window bit on any GLXFBConfigs
+        //       (VirtualBox GL) not setting the window bit on any GLXFBConfigs
         trustWindowBit = GL_FALSE;
     }
 
@@ -485,8 +485,9 @@ int _glfwCreateContext(_GLFWwindow* window,
         if (window->glx.context == NULL)
         {
             // HACK: This is a fallback for the broken Mesa implementation of
-            // GLX_ARB_create_context_profile, which fails default 1.0 context
+            //       GLX_ARB_create_context_profile, which fails default 1.0
-            // creation with a GLXBadProfileARB error in violation of the spec
+            //       context creation with a GLXBadProfileARB error in violation
+            //       of the extension spec
             if (_glfw.x11.errorCode == _glfw.glx.errorBase + GLXBadProfileARB &&
                 wndconfig->clientAPI == GLFW_OPENGL_API &&
                 wndconfig->glProfile == GLFW_OPENGL_ANY_PROFILE &&

src/x11_window.c

@@ -129,8 +129,8 @@ static GLboolean createWindow(_GLFWwindow* window,
         if (wndconfig->monitor == NULL)
         {
             // HACK: This is a workaround for windows without a background pixel
-            // not getting any decorations on certain older versions of Compiz
+            //       not getting any decorations on certain older versions of
-            // running on Intel hardware
+            //       Compiz running on Intel hardware
             wa.background_pixel = BlackPixel(_glfw.x11.display,
                                              _glfw.x11.screen);
             wamask |= CWBackPixel;
@@ -258,6 +258,9 @@ static GLboolean createWindow(_GLFWwindow* window,
         }
         else
         {
+            // HACK: Explicitly setting PPosition to any value causes some WMs,
+            //       notably Compiz and Metacity, to honor the position of
+            //       unmapped windows set by XMoveWindow
             hints->flags |= PPosition;
             hints->x = hints->y = 0;
         }
@@ -275,7 +278,7 @@ static GLboolean createWindow(_GLFWwindow* window,
 
     // Set ICCCM WM_CLASS property
     // HACK: Until a mechanism for specifying the application name is added, the
-    // initial window title is used as the window class name
+    //       initial window title is used as the window class name
     if (strlen(wndconfig->title))
     {
         XClassHint* hint = XAllocClassHint();