Documentation work

docs/context.dox

@@ -129,8 +129,7 @@ error.
 
 @section context_swap Buffer swapping
 
-Buffer swapping is part of the window and framebuffer, not the context.  See
+See @ref buffer_swap in the window guide.
-@ref buffer_swap.
 
 
 @section context_glext OpenGL and OpenGL ES extensions

docs/window.dox

@@ -1334,4 +1334,10 @@ Note that this may not work on all machines, as some drivers have
 user-controlled settings that override any swap interval the application
 requests.
 
+A context that supports either the `WGL_EXT_swap_control_tear` or the
+`GLX_EXT_swap_control_tear` extension also accepts _negative_ swap intervals,
+which allows the driver to swap immediately even if a frame arrives a little bit
+late.  This trades the risk of visible tears for greater framerate stability.
+You can check for these extensions with @ref glfwExtensionSupported.
+
 */

include/GLFW/glfw3.h

@@ -4969,12 +4969,11 @@ GLFWAPI void glfwSwapBuffers(GLFWwindow* window);
  *  is sometimes called _vertical synchronization_, _vertical retrace
  *  synchronization_ or just _vsync_.
  *
- *  Contexts that support either of the `WGL_EXT_swap_control_tear` and
+ *  A context that support either of the `WGL_EXT_swap_control_tear` and
- *  `GLX_EXT_swap_control_tear` extensions also accept negative swap intervals,
+ *  `GLX_EXT_swap_control_tear` extensions also accepts _negative_ swap
- *  which allow the driver to swap even if a frame arrives a little bit late.
+ *  intervals, which allows the driver to swap immediately even if a frame
- *  You can check for the presence of these extensions using @ref
+ *  arrives a little bit late.  You can check for these extensions with @ref
- *  glfwExtensionSupported.  For more information about swap tearing, see the
+ *  glfwExtensionSupported.
- *  extension specifications.
  *
  *  A context must be current on the calling thread.  Calling this function
  *  without a current context will cause a @ref GLFW_NO_CURRENT_CONTEXT error.