Documentation work

[ci skip]

docs/input.dox

@@ -145,7 +145,9 @@ per-window state arrays that can be polled with @ref glfwGetKey.
 @code
 int state = glfwGetKey(window, GLFW_KEY_E);
 if (state == GLFW_PRESS)
+{
     activate_airship();
+}
 @endcode
 
 The returned state is one of `GLFW_PRESS` or `GLFW_RELEASE`.
@@ -449,7 +451,9 @@ per-window state arrays that can be polled with @ref glfwGetMouseButton.
 @code
 int state = glfwGetMouseButton(window, GLFW_MOUSE_BUTTON_LEFT);
 if (state == GLFW_PRESS)
+{
     upgrade_cow();
+}
 @endcode
 
 The returned state is one of `GLFW_PRESS` or `GLFW_RELEASE`.
@@ -642,7 +646,9 @@ reference documentation for the lifetime of the returned string.
 @code
 const char* text = glfwGetClipboardString(window);
 if (text)
+{
     insert_text(text);
+}
 @endcode
 
 If the clipboard is empty or if its contents could not be converted, `NULL` is

docs/intro.dox

@@ -83,9 +83,9 @@ immediately.
 @section error_handling Error handling
 
 Some GLFW functions have return values that indicate an error, but this is often
-not very helpful when trying to figure out _why_ the error occurred.  Some
-functions also return otherwise valid values on error.  Finally, far from all
-GLFW functions have return values.
+not very helpful when trying to figure out _why_ the error occurred.  Other
+functions have no return value reserved for errors, so error notification needs
+a separate channel.  Finally, far from all GLFW functions have return values.
 
 This is where the error callback comes in.  This callback is called whenever an
 error occurs.  It is set with @ref glfwSetErrorCallback, a function that may be
@@ -110,6 +110,12 @@ The error code indicates the general category of the error.  Some error codes,
 such as @ref GLFW_NOT_INITIALIZED has only a single meaning, whereas others like
 @ref GLFW_PLATFORM_ERROR are used for many different errors.
 
+Reported errors are never fatal.  As long as GLFW was successfully initialized,
+it will remain initialized and in a safe state until terminated regardless of
+how many errors occur.  If an error occurs during initialization that causes
+@ref glfwInit to fail, any part of the library that was initialized will be
+safely terminated.
+
 The description string is only valid until the error callback returns, as it may
 have been generated specifically for that error.  This lets GLFW provide much
 more specific error descriptions but means you must make a copy if you want to

docs/window.dox

@@ -179,43 +179,48 @@ context, but are ignored when requesting an OpenGL ES context:
 @anchor GLFW_RESIZABLE_hint
 __GLFW_RESIZABLE__ specifies whether the windowed mode window will be resizable
 _by the user_.  The window will still be resizable using the @ref
-glfwSetWindowSize function.  This hint is ignored for full screen and
-undecorated windows.
+glfwSetWindowSize function.  Possible values are `GLFW_TRUE` and `GLFW_FALSE`.
+This hint is ignored for full screen and undecorated windows.
 
 @anchor GLFW_VISIBLE_hint
 __GLFW_VISIBLE__ specifies whether the windowed mode window will be initially
-visible.  This hint is ignored for full screen windows.
+visible.  Possible values are `GLFW_TRUE` and `GLFW_FALSE`.  This hint is
+ignored for full screen windows.
 
 @anchor GLFW_DECORATED_hint
 __GLFW_DECORATED__ specifies whether the windowed mode window will have window
 decorations such as a border, a close widget, etc.  An undecorated window will
 not be resizable by the user but will still allow the user to generate close
-events on some platforms.  This hint is ignored for full screen windows.
+events on some platforms.  Possible values are `GLFW_TRUE` and `GLFW_FALSE`.
+This hint is ignored for full screen windows.
 
 @anchor GLFW_FOCUSED_hint
 __GLFW_FOCUSED__ specifies whether the windowed mode window will be given input
-focus when created.  This hint is ignored for full screen and initially hidden
-windows.
+focus when created.  Possible values are `GLFW_TRUE` and `GLFW_FALSE`.  This
+hint is ignored for full screen and initially hidden windows.
 
 @anchor GLFW_AUTO_ICONIFY_hint
 __GLFW_AUTO_ICONIFY__ specifies whether the full screen window will
 automatically iconify and restore the previous video mode on input focus loss.
-This hint is ignored for windowed mode windows.
+Possible values are `GLFW_TRUE` and `GLFW_FALSE`.  This hint is ignored for
+windowed mode windows.
 
 @anchor GLFW_FLOATING_hint
 __GLFW_FLOATING__ specifies whether the windowed mode window will be floating
 above other regular windows, also called topmost or always-on-top.  This is
 intended primarily for debugging purposes and cannot be used to implement proper
-full screen windows.  This hint is ignored for full screen windows.
+full screen windows.  Possible values are `GLFW_TRUE` and `GLFW_FALSE`.  This
+hint is ignored for full screen windows.
 
 @anchor GLFW_MAXIMIZED_hint
 __GLFW_MAXIMIZED__ specifies whether the windowed mode window will be maximized
-when created.  This hint is ignored for full screen windows.
+when created.  Possible values are `GLFW_TRUE` and `GLFW_FALSE`.  This hint is
+ignored for full screen windows.
 
 @anchor GLFW_CENTER_CURSOR_hint
 __GLFW_CENTER_CURSOR__ specifies whether the cursor should be centered over
-newly created full screen windows.  This hint is ignored for windowed mode
-windows.
+newly created full screen windows.  Possible values are `GLFW_TRUE` and
+`GLFW_FALSE`.  This hint is ignored for windowed mode windows.
 
 
 @subsubsection window_hints_fb Framebuffer related hints
@@ -253,8 +258,8 @@ Auxiliary buffers are a legacy OpenGL feature and should not be used in new
 code.
 
 @anchor GLFW_STEREO
-__GLFW_STEREO__ specifies whether to use OpenGL stereoscopic rendering.  This is
-a hard constraint.
+__GLFW_STEREO__ specifies whether to use OpenGL stereoscopic rendering.
+Possible values are `GLFW_TRUE` and `GLFW_FALSE`.  This is a hard constraint.
 
 @anchor GLFW_SAMPLES
 __GLFW_SAMPLES__ specifies the desired number of samples to use for
@@ -266,11 +271,12 @@ __GLFW_SRGB_CAPABLE__ specifies whether the framebuffer should be sRGB capable.
 If supported, a created OpenGL context will support the `GL_FRAMEBUFFER_SRGB`
 enable, also called `GL_FRAMEBUFFER_SRGB_EXT`) for controlling sRGB rendering
 and a created OpenGL ES context will always have sRGB rendering enabled.
+Possible values are `GLFW_TRUE` and `GLFW_FALSE`.
 
 @anchor GLFW_DOUBLEBUFFER
 __GLFW_DOUBLEBUFFER__ specifies whether the framebuffer should be double
 buffered.  You nearly always want to use double buffering.  This is a hard
-constraint.
+constraint.  Possible values are `GLFW_TRUE` and `GLFW_FALSE`.
 
 
 @subsubsection window_hints_mtr Monitor related hints
@@ -356,7 +362,8 @@ Forward-compatibility is described in detail in the
 @anchor GLFW_OPENGL_DEBUG_CONTEXT_hint
 __GLFW_OPENGL_DEBUG_CONTEXT__ specifies whether to create a debug OpenGL
 context, which may have additional error and performance issue reporting
-functionality.  If OpenGL ES is requested, this hint is ignored.
+functionality.  Possible values are `GLFW_TRUE` and `GLFW_FALSE`.  If OpenGL ES
+is requested, this hint is ignored.
 
 @anchor GLFW_OPENGL_PROFILE_hint
 __GLFW_OPENGL_PROFILE__ specifies which OpenGL profile to create the context
@@ -393,8 +400,8 @@ extension.
 
 @anchor GLFW_CONTEXT_NO_ERROR_hint
 __GLFW_CONTEXT_NO_ERROR__ specifies whether errors should be generated by the
-context.  If enabled, situations that would have generated errors instead cause
-undefined behavior.
+context.  Possible values are `GLFW_TRUE` and `GLFW_FALSE`.  If enabled,
+situations that would have generated errors instead cause undefined behavior.
 
 @par
 The no error mode for OpenGL and OpenGL ES is described in detail by the
@@ -414,19 +421,21 @@ being listed.
 
 @anchor GLFW_COCOA_RETINA_FRAMEBUFFER_hint
 __GLFW_COCOA_RETINA_FRAMEBUFFER__ specifies whether to use full resolution
-framebuffers on Retina displays.  This is ignored on other platforms.
+framebuffers on Retina displays.  Possible values are `GLFW_TRUE` and
+`GLFW_FALSE`.  This is ignored on other platforms.
 
 @anchor GLFW_COCOA_FRAME_AUTOSAVE_hint
 __GLFW_COCOA_FRAME_AUTOSAVE__ specifies whether to activate frame autosaving
-using the window title specified at window creation.  This is ignored on other
-platforms.
+using the window title specified at window creation.  Possible values are
+`GLFW_TRUE` and `GLFW_FALSE`.  This is ignored on other platforms.
 
 @anchor GLFW_COCOA_GRAPHICS_SWITCHING_hint
 __GLFW_COCOA_GRAPHICS_SWITCHING__ specifies whether to in Automatic Graphics
 Switching, i.e. to allow the system to choose the integrated GPU for the OpenGL
 context and move it between GPUs if necessary or whether to force it to always
 run on the discrete GPU.  This only affects systems with both integrated and
-discrete GPUs.  This is ignored on other platforms.
+discrete GPUs.  Possible values are `GLFW_TRUE` and `GLFW_FALSE`.  This is
+ignored on other platforms.
 
 @par
 Simpler programs and tools may want to enable this to save power, while games