From 366b90be1ab9ef38db38e5008f2138df6ff04f16 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Camilla=20L=C3=B6wy?= <elmindreda@glfw.org>
Date: Thu, 9 Feb 2017 20:55:29 +0100
Subject: [PATCH] Documentation work

---
 src/win32_window.c | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/src/win32_window.c b/src/win32_window.c
index c82a3d31..e4f20267 100644
--- a/src/win32_window.c
+++ b/src/win32_window.c
@@ -369,20 +369,19 @@ static int getAsyncKeyMods(void)
 //
 static int translateKey(WPARAM wParam, LPARAM lParam)
 {
+    // The Ctrl keys require special handling
     if (wParam == VK_CONTROL)
     {
-        // The CTRL keys require special handling
-
         MSG next;
         DWORD time;
 
-        // Is this an extended key (i.e. right key)?
+        // Right side keys have the extended key bit set
         if (lParam & 0x01000000)
             return GLFW_KEY_RIGHT_CONTROL;
 
-        // Here is a trick: "Alt Gr" sends LCTRL, then RALT. We only
-        // want the RALT message, so we try to see if the next message
-        // is a RALT message. In that case, this is a false LCTRL!
+        // HACK: Alt Gr sends Left Ctrl and then Right Alt in close sequence
+        //       We only want the Right Alt message, so if the next message is
+        //       Right Alt we ignore this (synthetic) Left Ctrl message
         time = GetMessageTime();
 
         if (PeekMessageW(&next, NULL, 0, 0, PM_NOREMOVE))
@@ -396,8 +395,7 @@ static int translateKey(WPARAM wParam, LPARAM lParam)
                     (next.lParam & 0x01000000) &&
                     next.time == time)
                 {
-                    // Next message is a RALT down message, which
-                    // means that this is not a proper LCTRL message
+                    // Next message is Right Alt down so discard this
                     return _GLFW_KEY_INVALID;
                 }
             }
@@ -580,14 +578,15 @@ static LRESULT CALLBACK windowProc(HWND hWnd, UINT uMsg,
 
             if (action == GLFW_RELEASE && wParam == VK_SHIFT)
             {
-                // Release both Shift keys on Shift up event, as only one event
-                // is sent even if both keys are released
+                // HACK: Release both Shift keys on Shift up event, as when both
+                //       are pressed the first release does not emit any event
+                // NOTE: The other half of this is in _glfwPlatformPollEvents
                 _glfwInputKey(window, GLFW_KEY_LEFT_SHIFT, scancode, action, mods);
                 _glfwInputKey(window, GLFW_KEY_RIGHT_SHIFT, scancode, action, mods);
             }
             else if (wParam == VK_SNAPSHOT)
             {
-                // Key down is not reported for the Print Screen key
+                // HACK: Key down is not reported for the Print Screen key
                 _glfwInputKey(window, key, scancode, GLFW_PRESS, mods);
                 _glfwInputKey(window, key, scancode, GLFW_RELEASE, mods);
             }
@@ -891,7 +890,7 @@ static int createNativeWindow(_GLFWwindow* window,
 
         // NOTE: This window placement is temporary and approximate, as the
         //       correct position and size cannot be known until the monitor
-        //       video mode has been set
+        //       video mode has been picked in _glfwSetVideoModeWin32
         _glfwPlatformGetMonitorPos(window->monitor, &xpos, &ypos);
         _glfwPlatformGetVideoMode(window->monitor, &mode);
         fullWidth  = mode.width;
@@ -1393,9 +1392,9 @@ void _glfwPlatformPollEvents(void)
     {
         if (msg.message == WM_QUIT)
         {
-            // Treat WM_QUIT as a close on all windows
-            // While GLFW does not itself post WM_QUIT, other processes may post
-            // it to this one, for example Task Manager
+            // NOTE: While GLFW does not itself post WM_QUIT, other processes
+            //       may post it to this one, for example Task Manager
+            // HACK: Treat WM_QUIT as a close on all windows
 
             window = _glfw.windowListHead;
             while (window)
@@ -1416,6 +1415,7 @@ void _glfwPlatformPollEvents(void)
     {
         // NOTE: Shift keys on Windows tend to "stick" when both are pressed as
         //       no key up message is generated by the first key release
+        //       The other half of this is in the handling of WM_KEYUP
         // HACK: Query actual key state and synthesize release events as needed
         window = GetPropW(handle, L"GLFW");
         if (window)