Documentation work.

docs/monitor.dox

@@ -9,6 +9,9 @@
 
 The @ref GLFWmonitor object represents a currently connected monitor.
 
+
+@section monitor_monitors Retrieving monitors
+
 The primary monitor is returned by @ref glfwGetPrimaryMonitor.  It is usually
 the user's preferred monitor and the one with global UI elements like task bar
 or menu bar.
@@ -25,7 +28,7 @@ GLFWmonitor** monitors = glfwGetMonitors(&count);
 @endcode
 
 
-@section monitor_modes Querying video modes
+@section monitor_modes Retrieving video modes
 
 Although GLFW generally does a good job at selecting a suitable video
 mode for you when you open a full screen window, it is sometimes useful to

docs/quick.dox

@@ -140,9 +140,9 @@ full screen, just pass along the monitor handle:
 GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", glfwGetPrimaryMonitor(), NULL);
 @endcode
 
-Full screen windows cover the entire screen, have no border or decorations, and
-change the monitor's resolution to the one most closely matching the requested
-window size.
+Full screen windows cover the entire display area of a monitor, have no border
+or decorations, and change the monitor's resolution to the one most closely
+matching the requested window size.
 
 When you are done with the window, destroy it with the @ref glfwDestroyWindow
 function.

docs/window.dox

@@ -17,6 +17,51 @@ created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow (or
 linked, the object pointer is used as both a context and window handle.
 
 
+@section window_creation Window creation
+
+The window and its context are created with @ref glfwCreateWindow, which
+returns a handle to the created window object.  For example, this creates a 640
+by 480 windowed mode window:
+
+@code
+GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL);
+@endcode
+
+If window creation fails, `NULL` will be returned, so you need to check whether
+it did.
+
+This handle is then passed to all window related functions, and is provided to
+you along with input events, so you know which window received the input.
+
+To create a full screen window, you need to specify which monitor the window
+should use.  In most cases, the user's primary monitor is a good choice.  For
+more information about monitors, see the @ref monitor.
+
+@code
+GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", glfwGetPrimaryMonitor(), NULL);
+@endcode
+
+Full screen windows cover the entire display area of a monitor, have no border
+or decorations, and change the monitor's resolution to the one most closely
+matching the requested window size.
+
+For more control over how the window and its context are created, see @ref
+window_hints below.
+
+
+@section window_destruction Window destruction
+
+When you are done with the window, destroy it with the @ref glfwDestroyWindow
+function.
+
+@code
+glfwDestroyWindow(window);
+@endcode
+
+Once this function is called, no more events will be delivered for that window
+and its handle becomes invalid.
+
+
 @section window_hints Window creation hints
 
 There are a number of hints that can be set before the creation of a window and
@@ -227,13 +272,11 @@ the system, you can set the size callback with @ref glfwSetWindowSizeCallback.
 glfwSetWindowSizeCallback(window, window_size_callback);
 @endcode
 
-The callback function receives the new size of the client area of the window,
-which can for example be used to update the viewport.
+The callback function receives the new size of the client area of the window.
 
 @code
 void window_size_callback(GLFWwindow* window, int width, int height)
 {
-    glViewport(0, 0, width, height);
 }
 @endcode
 
@@ -243,9 +286,49 @@ a window.
 @code
 int width, height;
 glfwGetWindowSize(window, &width, &height);
+@endcode
+
+
+@section window_fbsize Window framebuffer size
+
+While the size of a window is measured in screen coordinates, OpenGL works with
+pixels.  The size you pass into `glViewport`, for example, should be in pixels
+and not screen coordinates.  On some platforms screen coordinates and pixels are
+the same, but this is not the case on all platforms supported by GLFW.  There is
+a second set of functions to retrieve the size in pixels of the framebuffer of
+a window.
+
+If you wish to be notified when the framebuffer of a window is resized, whether
+by the user or the system, you can set the size callback with @ref
+glfwSetFramebufferSizeCallback.
+
+@code
+glfwSetFramebufferSizeCallback(window, framebuffer_size_callback);
+@endcode
+
+The callback function receives the new size of the client area of the window,
+which can for example be used to update the OpenGL viewport.
+
+@code
+void framebuffer_size_callback(GLFWwindow* window, int width, int height)
+{
+    glViewport(0, 0, width, height);
+}
+@endcode
+
+There is also @ref glfwGetFramebufferSize for directly retrieving the current
+size of the framebuffer of a window.
+
+@code
+int width, height;
+glfwGetFramebufferSize(window, &width, &height);
 glViewport(0, 0, width, height);
 @endcode
 
+Note that the size of a framebuffer may change independently of the size of
+a window, for example if the window is dragged between a regular monitor and
+a high-DPI one.
+
 
 @section window_pos Window position
 

include/GLFW/glfw3.h

@@ -1208,6 +1208,12 @@ GLFWAPI void glfwWindowHint(int target, int hint);
  *  attributes of the created window and context, use queries like @ref
  *  glfwGetWindowAttrib and @ref glfwGetWindowSize.
  *
+ *  To create a full screen window, you need to specify the monitor to use.  If
+ *  no monitor is specified, windowed mode will be used.  Unless you have a way
+ *  for the user to choose a specific monitor, it is recommended that you pick
+ *  the primary monitor.  For more information on how to retrieve monitors, see
+ *  @ref monitor_monitors.
+ *
  *  To create the window at a specific position, make it initially invisible
  *  using the `GLFW_VISIBLE` window hint, set its position and then show it.
  *