Comment updates and formatting.

src/cocoa_gamma.c

@@ -40,7 +40,7 @@
 //************************************************************************
 
 //========================================================================
-// Save the original gamma ramp so that we can restore it later
+// Save the original gamma ramp so that it can be restored later
 //========================================================================
 
 void _glfwPlatformGetGammaRamp(GLFWgammaramp* ramp)

src/cocoa_input.m

@@ -40,13 +40,14 @@
 
 void _glfwPlatformEnableSystemKeys(_GLFWwindow* window)
 {
-    // This is checked in macosx_window.m; we take no action here
+    // This is checked in cocoa_window.m; no action needed here
 }
 
 void _glfwPlatformDisableSystemKeys(_GLFWwindow* window)
 {
-    // This is checked in macosx_window.m; we take no action here
+    // This is checked in cocoa_window.m; no action needed here
-    // I don't think it's really possible to disable stuff like Exposé
+
+    // Note that it may not be possible to disable things like Exposé
     // except in full-screen mode.
 }
 

src/cocoa_joystick.m

@@ -46,7 +46,6 @@
 //------------------------------------------------------------------------
 // Joystick element information
 //------------------------------------------------------------------------
-
 typedef struct
 {
     IOHIDElementCookie cookie;
@@ -65,7 +64,6 @@ typedef struct
 //------------------------------------------------------------------------
 // Joystick information & state
 //------------------------------------------------------------------------
-
 typedef struct
 {
     int present;
@@ -213,7 +211,7 @@ static long getElementValue(_glfwJoystick* joystick, _glfwJoystickElement* eleme
                                                            &hidEvent);
         if (kIOReturnSuccess == result)
         {
-            /* record min and max for auto calibration */
+            // Record min and max for auto calibration
             if (hidEvent.value < element->minReport)
                 element->minReport = hidEvent.value;
             if (hidEvent.value > element->maxReport)
@@ -221,7 +219,7 @@ static long getElementValue(_glfwJoystick* joystick, _glfwJoystickElement* eleme
         }
     }
 
-    /* auto user scale */
+    // Auto user scale
     return (long) hidEvent.value;
 }
 
@@ -384,14 +382,14 @@ void _glfwInitJoysticks(void)
         if (result != kIOReturnSuccess)
             continue;
 
-        /* Check device type */
+        // Check device type
         refCF = CFDictionaryGetValue(hidProperties, CFSTR(kIOHIDPrimaryUsagePageKey));
         if (refCF)
         {
             CFNumberGetValue(refCF, kCFNumberLongType, &usagePage);
             if (usagePage != kHIDPage_GenericDesktop)
             {
-                /* We are not interested in this device */
+                // This device is not relevant to GLFW
                 continue;
             }
         }
@@ -405,7 +403,7 @@ void _glfwInitJoysticks(void)
                  usage != kHIDUsage_GD_GamePad &&
                  usage != kHIDUsage_GD_MultiAxisController))
             {
-                /* We are not interested in this device */
+                // This device is not relevant to GLFW
                 continue;
             }
         }
@@ -439,7 +437,7 @@ void _glfwInitJoysticks(void)
                                                      joystick,
                                                      joystick);
 
-        /* Get product string */
+        // Get product string
         refCF = CFDictionaryGetValue(hidProperties, CFSTR(kIOHIDProductKey));
         if (refCF)
         {
@@ -561,8 +559,6 @@ int _glfwPlatformGetJoystickPos(int joy, float* pos, int numaxes)
         else
             pos[i] = (2.0f * (axes->value - axes->minReport) / readScale) - 1.0f;
 
-        //printf("%ld, %ld, %ld\n", axes->value, axes->minReport, axes->maxReport);
-
         if (i & 1)
             pos[i] = -pos[i];
     }

src/cocoa_window.m

@@ -277,9 +277,6 @@ static int convertMacKeyCode(unsigned int macKeyCode)
     if (macKeyCode >= 128)
         return -1;
 
-    // This treats keycodes as *positional*; that is, we'll return 'a'
-    // for the key left of 's', even on an AZERTY keyboard.  The charInput
-    // function should still get 'q' though.
     return table[macKeyCode];
 }
 
@@ -541,7 +538,7 @@ static NSString* findAppName(void)
         }
     }
 
-    // If we get here, we're unbundled
+    // If we get here, the application is unbundled
     ProcessSerialNumber psn = { 0, kCurrentProcess };
     TransformProcessType(&psn, kProcessTransformToForegroundApplication);
 
@@ -551,10 +548,7 @@ static NSString* findAppName(void)
 
     char** progname = _NSGetProgname();
     if (progname && *progname)
-    {
-        // TODO: UTF-8?
         return [NSString stringWithUTF8String:*progname];
-    }
 
     // Really shouldn't get here
     return @"GLFW Application";
@@ -866,8 +860,8 @@ int _glfwPlatformCreateWindow(_GLFWwindow* window,
     if (!initializeAppKit())
         return GL_FALSE;
 
-    // We can only have one application delegate, but we only allocate it the
+    // There can only be one application delegate, but we allocate it the
-    // first time we create a window to keep all window code in this file
+    // first time a window is created to keep all window code in this file
     if (_glfwLibrary.NS.delegate == nil)
     {
         _glfwLibrary.NS.delegate = [[GLFWApplicationDelegate alloc] init];

src/fullscreen.c

@@ -87,7 +87,7 @@ void _glfwSplitBPP(int bpp, int* red, int* green, int* blue)
 {
     int delta;
 
-    // We assume that by 32 they really meant 24
+    // We assume that by 32 the user really meant 24
     if (bpp == 32)
         bpp = 24;
 

src/x11_platform.h

@@ -42,20 +42,21 @@
 #include <GL/glx.h>
 
 // This path may need to be changed if you build GLFW using your own setup
-// We ship and use our own copy of glxext.h since GLFW uses fairly new
+// GLFW comes with its own copy of glxext.h since it uses some fairly new
 // extensions and not all operating systems come with an up-to-date version
 #include "../support/GL/glxext.h"
 
-// With XFree86, we can use the XF86VidMode extension
+// The XF86VidMode extension provides mode setting and gamma control
 #if defined(_GLFW_HAS_XF86VIDMODE)
  #include <X11/extensions/xf86vmode.h>
 #endif
 
+// The XRandR extension provides mode setting and gamma control
 #if defined(_GLFW_HAS_XRANDR)
  #include <X11/extensions/Xrandr.h>
 #endif
 
-// Do we have support for dlopen/dlsym?
+// dlopen is used as a fallback function retrieval mechanism
 #if defined(_GLFW_HAS_DLOPEN)
  #include <dlfcn.h>
 #endif
@@ -65,7 +66,7 @@
  #include <X11/XKBlib.h>
 #endif
 
-// We support four different ways for getting addresses for GL/GLX
+// GLFW supports four different ways for getting addresses for GL/GLX
 // extension functions: glXGetProcAddress, glXGetProcAddressARB,
 // glXGetProcAddressEXT, and dlsym
 #if defined(_GLFW_HAS_GLXGETPROCADDRESSARB)

src/x11_window.c

@@ -43,21 +43,18 @@
 #define Button6            6
 #define Button7            7
 
+
 //========================================================================
 // Translates an X Window key to internal coding
 //========================================================================
 
 static int translateKey(int keycode)
 {
-    // Use the pre-filled LUT (see updateKeyCodeLUT() ).
+    // Use the pre-filled LUT (see updateKeyCodeLUT() in x11_init.c)
     if ((keycode >= 0) && (keycode < 256))
-    {
         return _glfwLibrary.X11.keyCodeLUT[keycode];
-    }
     else
-    {
         return -1;
-    }
 }
 
 
@@ -90,6 +87,7 @@ static GLboolean createWindow(_GLFWwindow* window,
 
     // Every window needs a colormap
     // Create one based on the visual used by the current context
+    // TODO: Decouple this from context creation
 
     window->X11.colormap = XCreateColormap(_glfwLibrary.X11.display,
                                            _glfwLibrary.X11.root,
@@ -109,30 +107,29 @@ static GLboolean createWindow(_GLFWwindow* window,
 
         if (wndconfig->mode == GLFW_WINDOWED)
         {
-            // The /only/ reason we are setting the background pixel here is
+            // The /only/ reason for setting the background pixel here is that
-            // that otherwise our window wont get any decorations on systems
+            // otherwise our window won't get any decorations on systems using
-            // using Compiz on Intel hardware
+            // certain versions of Compiz on Intel hardware
             wa.background_pixel = BlackPixel(_glfwLibrary.X11.display,
                                              _glfwLibrary.X11.screen);
             wamask |= CWBackPixel;
         }
 
-        window->X11.handle = XCreateWindow(
+        window->X11.handle = XCreateWindow(_glfwLibrary.X11.display,
-            _glfwLibrary.X11.display,
+                                           _glfwLibrary.X11.root,
-            _glfwLibrary.X11.root,
+                                           0, 0,           // Position
-            0, 0,                            // Upper left corner of this window on root
+                                           window->width, window->height,
-            window->width, window->height,
+                                           0,              // Border width
-            0,                               // Border width
+                                           visual->depth,  // Color depth
-            visual->depth,                   // Color depth
+                                           InputOutput,
-            InputOutput,
+                                           visual->visual,
-            visual->visual,
+                                           wamask,
-            wamask,
+                                           &wa);
-            &wa
-        );
 
         if (!window->X11.handle)
         {
-            // TODO: Handle all the various error codes here
+            // TODO: Handle all the various error codes here and translate them
+            // to GLFW errors
 
             _glfwSetError(GLFW_PLATFORM_ERROR,
                           "X11/GLX: Failed to create window");
@@ -147,8 +144,8 @@ static GLboolean createWindow(_GLFWwindow* window,
         // manager ignore the window completely (ICCCM, section 4)
         // The good thing is that this makes undecorated fullscreen windows
         // easy to do; the bad thing is that we have to do everything manually
-        // and some things (like iconify/restore) won't work at all, as they're
+        // and some things (like iconify/restore) won't work at all, as those
-        // usually performed by the window manager
+        // are tasks usually performed by the window manager
 
         XSetWindowAttributes attributes;
         attributes.override_redirect = True;
@@ -165,7 +162,7 @@ static GLboolean createWindow(_GLFWwindow* window,
                                                   "WM_DELETE_WINDOW",
                                                   False);
 
-    // Declare the WM protocols we support
+    // Declare the WM protocols supported by GLFW
     {
         int count = 0;
         Atom protocols[2];
@@ -176,8 +173,8 @@ static GLboolean createWindow(_GLFWwindow* window,
             protocols[count++] = _glfwLibrary.X11.wmDeleteWindow;
 
         // The _NET_WM_PING EWMH protocol
-        // Tells the WM to ping our window and flag us as unresponsive if we
+        // Tells the WM to ping the GLFW window and flag the application as
-        // don't reply within a few seconds
+        // unresponsive if the WM doesn't get a reply within a few seconds
         if (_glfwLibrary.X11.wmPing != None)
             protocols[count++] = _glfwLibrary.X11.wmPing;
 
@@ -283,7 +280,7 @@ static void captureCursor(_GLFWwindow* window)
 
 static void showCursor(_GLFWwindow* window)
 {
-    // Un-grab cursor (only in windowed mode: in fullscreen mode we still
+    // Un-grab cursor (in windowed mode only; in fullscreen mode we still
     // want the cursor grabbed in order to confine the cursor to the window
     // area)
     if (window->X11.cursorGrabbed)
@@ -377,7 +374,7 @@ static void enterFullscreenMode(_GLFWwindow* window)
     }
     else if (window->X11.overrideRedirect)
     {
-        // In override-redirect mode, we have divorced ourselves from the
+        // In override-redirect mode we have divorced ourselves from the
         // window manager, so we need to do everything manually
 
         XRaiseWindow(_glfwLibrary.X11.display, window->X11.handle);
@@ -405,7 +402,6 @@ static void leaveFullscreenMode(_GLFWwindow* window)
 {
     _glfwRestoreVideoMode();
 
-    // Did we change the screen saver setting?
     if (_glfwLibrary.X11.saver.changed)
     {
         // Restore old screen saver settings
@@ -648,7 +644,8 @@ static void processSingleEvent(void)
             if (event.xmotion.x != window->X11.cursorPosX ||
                 event.xmotion.y != window->X11.cursorPosY)
             {
-                // The cursor was moved and we didn't do it
+                // The cursor was moved by something other than GLFW
+
                 int x, y;
 
                 if (window->cursorMode == GLFW_CURSOR_CAPTURED)
@@ -716,8 +713,8 @@ static void processSingleEvent(void)
             else if (_glfwLibrary.X11.wmPing != None &&
                      (Atom) event.xclient.data.l[0] == _glfwLibrary.X11.wmPing)
             {
-                // The window manager is pinging us to make sure we are still
+                // The window manager is pinging the application to ensure it's
-                // responding to events
+                // still responding to events
 
                 event.xclient.window = _glfwLibrary.X11.root;
                 XSendEvent(_glfwLibrary.X11.display,
@@ -864,7 +861,6 @@ static void processSingleEvent(void)
             {
                 case RRScreenChangeNotify:
                 {
-                    // Show XRandR that we really care
                     XRRUpdateConfiguration(&event);
                     break;
                 }
@@ -1071,8 +1067,8 @@ void _glfwPlatformIconifyWindow(_GLFWwindow* window)
 {
     if (window->X11.overrideRedirect)
     {
-        // We can't iconify/restore override-redirect windows, as that's
+        // Override-redirect windows cannot be iconified or restored, as those
-        // performed by the window manager
+        // tasks are performed by the window manager
         return;
     }
 
@@ -1090,8 +1086,8 @@ void _glfwPlatformRestoreWindow(_GLFWwindow* window)
 {
     if (window->X11.overrideRedirect)
     {
-        // We can't iconify/restore override-redirect windows, as that's
+        // Override-redirect windows cannot be iconified or restored, as those
-        // performed by the window manager
+        // tasks are performed by the window manager
         return;
     }
 
@@ -1195,7 +1191,7 @@ void _glfwPlatformWaitEvents(void)
 
 void _glfwPlatformSetCursorPos(_GLFWwindow* window, int x, int y)
 {
-    // Store the new position so we can recognise it later
+    // Store the new position so it can be recognized later
     window->X11.cursorPosX = x;
     window->X11.cursorPosY = y;