Documentation work.

docs/context.dox

@@ -70,20 +70,21 @@ GLFWwindow* offscreen_context = glfwCreateWindow(640, 480, "", NULL, NULL);
 @endcode
 
 The window never needs to be shown and its context can be used as a plain
-offscreen context.  The size of a hidden window's framebuffer may not be usable
-or modifiable, so framebuffer objects are recommended for rendering with such
-contexts.
+offscreen context.  Depending on the window manager, the size of a hidden
+window's framebuffer may not be usable or modifiable, so framebuffer
+objects are recommended for rendering with such contexts.
 
 __OS X:__ The first time a window is created the menu bar is populated with
-common commands like Hide, Quit and About.  This can be disabled with a
-[compile-time option](@ref compile_options_osx).
+common commands like Hide, Quit and About.  This is not desirable for example
+when writing a command-line only application.  The menu bar setup can be
+disabled with a [compile-time option](@ref compile_options_osx).
 
 
 @section context_current Current context
 
 Before you can make OpenGL or OpenGL ES calls, you need to have a current
-context of the proper type.  The context encapsulates all render state and all
-objects like textures and shaders.
+context of the correct type.  A context can only be current for a single thread
+at a time, and a thread can only have a single context current at a time.
 
 A context is made current with @ref glfwMakeContextCurrent.
 
@@ -97,9 +98,14 @@ The current context is returned by @ref glfwGetCurrentContext.
 GLFWwindow* window = glfwGetCurrentContext();
 @endcode
 
-@note A context can only be current for a single thread at a time, and a thread
-can only have a single context current at a time.
+The following GLFW functions require a context to be current:
 
+ - @ref glfwSwapInterval
+ - @ref glfwExtensionSupported
+ - @ref glfwGetProcAddress
+
+Calling any these functions without a current context will generate a @ref
+GLFW_NO_CURRENT_CONTEXT error.
 
 @section context_swap Buffer swapping
 
@@ -150,9 +156,9 @@ written to the `output` directory.
 python main.py --no-loader --out-path output
 @endcode
 
-@note The `--no-loader` option is used because GLFW already provides a function
-for loading OpenGL and OpenGL ES function pointers and glad can use this instead
-of having to add its own.
+The `--no-loader` option is added because GLFW already provides a function for
+loading OpenGL and OpenGL ES function pointers and glad can call this instead of
+having to implement its own.
 
 Add the generated `output/src/glad.c`, `output/include/glad/glad.h` and
 `output/include/KHR/khrplatform.h` files to your build.  Then you need to

include/GLFW/glfw3.h

@@ -527,6 +527,20 @@ extern "C" {
 #define GLFW_OUT_OF_MEMORY          0x00010005
 /*! @brief GLFW could not find support for the requested client API on the
  *  system.
+ *
+ *  GLFW could not find support for the requested client API on the system.
+ *
+ *  @par Analysis
+ *  The installed graphics driver does not support the requested client API, or
+ *  does not support it via the chosen context creation backend.  Below are
+ *  a few examples.
+ *
+ *  @par
+ *  Some pre-installed Windows graphics drivers do not support OpenGL.  AMD only
+ *  supports OpenGL ES via EGL, while nVidia and Intel only supports it via
+ *  a WGL or GLX extension.  OS X does not provide OpenGL ES at all.  The Mesa
+ *  EGL, OpenGL and OpenGL ES libraries do not interface with the nVidia binary
+ *  driver.
  */
 #define GLFW_API_UNAVAILABLE        0x00010006
 /*! @brief The requested OpenGL or OpenGL ES version is not available.
@@ -540,10 +554,11 @@ extern "C" {
  *  Otherwise, inform the user that their machine does not match your
  *  requirements.
  *
- *  @note Because GLFW is not psychic, future invalid OpenGL and OpenGL ES
- *  versions, say for example OpenGL 4.8 if 5.0 comes out before the 4.x series
- *  gets that far, also fail with this error and not @ref GLFW_INVALID_VALUE.
- *  The version logic is updated in every patch release, as needed.
+ *  @par
+ *  Future invalid OpenGL and OpenGL ES versions, for example OpenGL 4.8 if 5.0
+ *  comes out before the 4.x series gets that far, also fail with this error and
+ *  not @ref GLFW_INVALID_VALUE, because GLFW cannot know what future versions
+ *  will exist.
  */
 #define GLFW_VERSION_UNAVAILABLE    0x00010007
 /*! @brief A platform-specific error occurred that does not match any of the
@@ -557,7 +572,24 @@ extern "C" {
  *  [issue tracker](https://github.com/glfw/glfw/issues).
  */
 #define GLFW_PLATFORM_ERROR         0x00010008
-/*! @brief The clipboard did not contain data in the requested format.
+/*! @brief The requested format is not supported or available.
+ *
+ *  If emitted during window creation, the requested pixel format is not
+ *  supported.
+ *
+ *  If emitted when querying the clipboard, the contents of the clipboard could
+ *  not be converted to the requested format.
+ *
+ *  @par Analysis
+ *  If emitted during window creation, one or more
+ *  [hard constraints](@ref window_hints_hard) did not match any of the
+ *  available pixel formats.  If your application is sufficiently flexible,
+ *  downgrade your requirements and try again.  Otherwise, inform the user that
+ *  their machine does not match your requirements.
+ *
+ *  @par
+ *  If emitted when querying the clipboard, ignore the error or report it to
+ *  the user, as appropriate.
  */
 #define GLFW_FORMAT_UNAVAILABLE     0x00010009
 /*! @} */