Documentation work.

docs/compat.dox

@@ -91,7 +91,7 @@ formats.  If GLX 1.3 is not supported, @ref glfwInit will fail.
 
 GLFW uses the `GLX_MESA_swap_control,` `GLX_EXT_swap_control` and
 `GLX_SGI_swap_control` extensions to provide vertical retrace synchronization
-(or "vsync"), in that order of preference.  Where none of these extension are
+(or _vsync_), in that order of preference.  Where none of these extension are
 available, calling @ref glfwSwapInterval will have no effect.
 
 GLFW uses the `GLX_ARB_multisample` extension to create contexts with
@@ -128,7 +128,7 @@ neither is available, no other extensions are used and many GLFW features
 related to context creation will have no effect or cause errors when used.
 
 GLFW uses the `WGL_EXT_swap_control` extension to provide vertical retrace
-synchronization (or 'vsync').  Where this extension is unavailable, calling @ref
+synchronization (or _vsync_).  Where this extension is unavailable, calling @ref
 glfwSwapInterval will have no effect.
 
 GLFW uses the `WGL_ARB_pixel_format` and `WGL_ARB_multisample` extensions to

docs/context.dox

@@ -4,12 +4,8 @@
 
 @tableofcontents
 
-The primary purpose of GLFW is to provide a simple interface to window
+This guide introduces the OpenGL and OpenGL ES context related functions of
-management and OpenGL and OpenGL ES context creation.  GLFW supports
+GLFW.  There are also guides for the other areas of the GLFW API.
-multiple windows, with each window having its own context.
-
-This guide introduces the functions related to managing OpenGL and OpenGL ES
-contexts.  There are also guides for the other areas of the GLFW API.
 
  - @ref intro
  - @ref window
@@ -27,6 +23,10 @@ information.
 As the window and context are inseparably linked, the window object also serves
 as the context handle.
 
+To test the creation of various kinds of contexts and see their properties, run
+the `glfwinfo` test program.
+
+
 @subsection context_hints Context creation hints
 
 There are a number of hints, specified using @ref glfwWindowHint, related to

docs/intro.dox

@@ -151,10 +151,10 @@ which monitor the window is currently considered to be on.
 @section guarantees_limitations Guarantees and limitations
 
 This section describes the conditions under which GLFW can be expected to
-function, barring any bugs in GLFW, the operating system or drivers.  Use of
+function, barring bugs in the operating system or drivers.  Use of GLFW outside
-GLFW outside of these limits may work on some platforms, or on some machines, or
+of these limits may work on some platforms, or on some machines, or some of the
-some of the time, or on some versions of GLFW, but it may break at any time and
+time, or on some versions of GLFW, but it may break at any time and this will
-will not be considered a bug.
+not be considered a bug.
 
 
 @subsection lifetime Pointer lifetimes
@@ -171,9 +171,10 @@ If you need to keep this data, you must copy it before its lifetime expires.
 Many GLFW functions accept pointers to structures or strings allocated by the
 application.  These are never freed by GLFW and are always the responsibility of
 the application.  If GLFW needs to keep the data in these structures or strings,
-they are copied before the function returns.
+it is copied before the function returns.
 
-Pointer lifetimes are guaranteed not to be shortened in future minor releases.
+Pointer lifetimes are guaranteed not to be shortened in future minor or patch
+releases.
 
 
 @subsection reentrancy Reentrancy
@@ -191,16 +192,22 @@ function:
  - @ref glfwWaitEvents
  - @ref glfwTerminate
 
+These functions may be made reentrant in future minor or patch releases, but
+functions not on this list will not be made non-reentrant.
+
 
 @subsection thread_safety Thread safety
 
-Most GLFW functions may only be called from the main thread.  The reference
+Most GLFW functions may only be called from the main thread, but some may be
-documentation for every GLFW function states whether it is limited to the main
+called from any thread.  However, no GLFW function may be called from any other
-thread.
+thread until GLFW has been successfully initialized on the main thread,
+including functions that may called before initialization.
 
-There are some general rules that make it easier to remember which functions are
+The reference documentation for every GLFW function states whether it is limited
-limited to the main thread.  The following tasks may only be performed on the
+to the main thread.                                                        
-main thread:
+
+The following categories of functions are and will remain limited to the main
+thread due to the limitations of one or several platforms:
 
  - Initialization and termination
  - Event processing
@@ -236,9 +243,11 @@ The following timer related functions may be called from any thread:
 
  - @ref glfwGetTime
 
-No GLFW function may be called from any other thread until GLFW has been
+Library version information may be queried from any thread.  The following
-successfully initialized on the main thread, including functions that may called
+version related functions may be called from any thread:
-before initialization.
+
+ - @ref glfwGetVersion
+ - @ref glfwGetVersionString
 
 GLFW uses no synchronization objects internally except for thread-local storage
 to keep track of the current context for each thread.  Synchronization is left
@@ -259,8 +268,8 @@ Once a function or constant has been added, the signature of that function or
 value of that constant will remain unchanged until the next major version of
 GLFW.  No compatibility of any kind is guaranteed between major versions.
 
-Undefined behavior, i.e. behavior that is not described in reference
+Undocumented behavior, i.e. behavior that is not described in the documentation,
-documentation, may change at any time until it is documented.
+may change at any time until it is documented.
 
 If the reference documentation and the implementation differ, the reference
 documentation is correct and the implementation will be fixed in the next
@@ -318,6 +327,10 @@ see which code paths are enabled in a binary.
 The version string is returned by @ref glfwGetVersionString, a function that may
 be called regardless of whether GLFW is initialized.
 
+__Do not use the version string__ to find the GLFW library version.  The @ref
+glfwGetVersion function already provides the version of the running library
+binary.
+
 The format of the string is as follows:
  - The version of GLFW
  - The name of the window system API
@@ -331,8 +344,4 @@ back ends, the version string may look something like this:
 3.0.0 Win32 WGL MinGW
 @endcode
 
-@note Do not parse the version string to find the GLFW library version.  The
-@ref glfwGetVersion function provides the version of the library binary in
-numeric form.
-
 */

docs/monitor.dox

@@ -12,9 +12,6 @@ guides for the other areas of GLFW.
  - @ref context
  - @ref input
 
-To see how GLFW views your monitor setup and its available video modes, run the
-`modes` test program.
-
 
 @section monitor_objects Monitor objects
 
@@ -33,6 +30,9 @@ The virtual position of a monitor is in
 video mode, describes the viewports that the connected monitors provide into the
 virtual desktop that spans them.
 
+To see how GLFW views your monitor setup and its available video modes, run the
+`modes` test program.
+
 
 @subsection monitor_monitors Retrieving monitors
 

docs/quick.dox

@@ -145,15 +145,14 @@ and its handle becomes invalid.
 
 @subsection quick_context_current Making the OpenGL context current
 
-Before you can use the OpenGL API, it must have a current OpenGL context.  You
+Before you can use the OpenGL API, you must have a current OpenGL context.
-make a window's context current.
 
 @code
 glfwMakeContextCurrent(window);
 @endcode
 
-The context will then remain as current until you make another context current
+The context will remain current until you make another context current or until
-or until the window owning the current context is destroyed.                    
+the window owning the current context is destroyed.
 
 
 @subsection quick_window_close Checking the window close flag

docs/window.dox

@@ -4,10 +4,6 @@
  
 @tableofcontents
 
-The primary purpose of GLFW is to provide a simple interface to window
-management and OpenGL and OpenGL ES context creation.  GLFW supports multiple
-windows, which can be either a normal desktop window or a full screen window.
-
 This guide introduces the window related functions of GLFW.  There are also
 guides for the other areas of GLFW.
 
@@ -24,6 +20,9 @@ created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow (or
 @ref glfwTerminate, if any remain).  As the window and context are inseparably
 linked, the object pointer is used as both a context and window handle.
 
+To see the event stream provided to the various window related callbacks, run
+the `events` test program.
+
 
 @subsection window_creation Window creation