Documentation work.

docs/build.dox

@@ -35,21 +35,21 @@ with the entire Win32 API.
 
 Instead, the GLFW header takes care of this for you, not by including
 `windows.h`, but by duplicating only the very few necessary parts of it.  It
-does this only when needed, so if `windows.h` *is* included, the GLFW header
+does this only when needed, so if `windows.h` _is_ included, the GLFW header
 does not try to redefine those symbols.  The reverse is not true, i.e.
 `windows.h` cannot cope if any of its symbols have already been defined.
 
 In other words:
 
- - Do *not* include the OpenGL headers yourself, as GLFW does this for you
- - Do *not* include `windows.h` or other platform-specific headers unless you
+ - Do _not_ include the OpenGL headers yourself, as GLFW does this for you
+ - Do _not_ include `windows.h` or other platform-specific headers unless you
    plan on using those APIs directly
- - If you *do* need to include such headers, do it *before* including
+ - If you _do_ need to include such headers, do it _before_ including
    the GLFW header and it will handle this
 
 If you are using an OpenGL extension loading library such as
 [glad](https://github.com/Dav1dde/glad), the extension loader header should
-either be included *before* the GLFW one, or the `GLFW_INCLUDE_NONE` macro
+either be included _before_ the GLFW one, or the `GLFW_INCLUDE_NONE` macro
 (described below) should be defined.
 
 
@@ -85,7 +85,7 @@ header.  This is useful in combination with an extension loading library.
 If none of the above inclusion macros are defined, the standard OpenGL `GL/gl.h`
 header (`OpenGL/gl.h` on OS X) is included.
 
-`GLFW_INCLUDE_GLU` makes the header include the GLU header *in addition to* the
+`GLFW_INCLUDE_GLU` makes the header include the GLU header _in addition to_ the
 header selected above.  This should only be used with legacy code.  GLU has been
 deprecated and should not be used in new code.
 
@@ -124,7 +124,7 @@ set of default libraries along with other dependencies like `user32` and
 
 The link library for the GLFW DLL is named `glfw3dll`.  When compiling an
 application that uses the DLL version of GLFW, you need to define the `GLFW_DLL`
-macro *before* any inclusion of the GLFW header.  This can be done either with
+macro _before_ any inclusion of the GLFW header.  This can be done either with
 a compiler switch or by defining it in your source code.
 
 An application using the GLFW DLL does not need to link against any of its
@@ -293,6 +293,6 @@ against it from the command-line.
 The OpenGL framework contains both the OpenGL and GLU APIs, so there is nothing
 special to do when using GLU.  Also note that even though your machine may have
 `libGL`-style OpenGL libraries, they are for use with the X Window System and
-will *not* work with the OS X native version of GLFW.
+will _not_ work with the OS X native version of GLFW.
 
 */

docs/compat.dox

@@ -9,7 +9,7 @@ It lists what are essentially implementation details, but which are nonetheless
 vital knowledge for developers intending to deploy their applications on a wide
 range of machines.
 
-@note The information in this guide is not a part of GLFW API, but merely
+The information in this guide is not a part of GLFW API, but merely
 preconditions for some parts of the library to function on a given machine.  Any
 part of this information may change in future versions of GLFW and that will not
 be considered a breaking API change.

docs/compile.dox

@@ -92,8 +92,8 @@ example, on Ubuntu and other distributions based on Debian GNU/Linux, you need
 to install the `xorg-dev` and `libglu1-mesa-dev` packages.  The former pulls in
 all X.org header packages and the latter pulls in the Mesa OpenGL and GLU
 packages.  GLFW itself doesn't need or use GLU, but some of the examples do.
-Note that using header files and libraries from Mesa during compilation *will
-not* tie your binaries to the Mesa implementation of OpenGL.
+Note that using header files and libraries from Mesa during compilation
+_will not_ tie your binaries to the Mesa implementation of OpenGL.
 
 Once you have installed the necessary packages, move on to @ref
 compile_generate.
@@ -103,8 +103,8 @@ compile_generate.
 
 Once you have all necessary dependencies it is time to generate the project
 files or makefiles for your development environment.  CMake needs to know two
-paths for this: the path to the *root* directory of the GLFW source tree (i.e.
-*not* the `src` subdirectory) and the target path for the generated files and
+paths for this: the path to the _root_ directory of the GLFW source tree (i.e.
+_not_ the `src` subdirectory) and the target path for the generated files and
 compiled binaries.  If these are the same, it is called an in-tree build,
 otherwise it is called an out-of-tree build.
 
@@ -117,8 +117,8 @@ to compile the GLFW library, not about compiling the actual library.
 
 @subsubsection compile_generate_cli Generating files with the CMake command-line tool
 
-To make an in-tree build, enter the *root* directory of the GLFW source tree
-(i.e. *not* the `src` subdirectory) and run CMake.  The current directory is
+To make an in-tree build, enter the _root_ directory of the GLFW source tree
+(i.e. _not_ the `src` subdirectory) and run CMake.  The current directory is
 used as target path, while the path provided as an argument is used to find the
 source tree.
 
@@ -146,8 +146,8 @@ development environment, move on to @ref compile_compile.
 
 If you are using the GUI version, choose the root of the GLFW source tree as
 source location and the same directory or another, empty directory as the
-destination for binaries.  Choose *Configure*, change any options you wish to,
-*Configure* again to let the changes take effect and then *Generate*.
+destination for binaries.  Choose _Configure_, change any options you wish to,
+_Configure_ again to let the changes take effect and then _Generate_.
 
 Once you have generated the project files or makefiles for your chosen
 development environment, move on to @ref compile_compile.
@@ -252,7 +252,7 @@ defines `_GLFW_USE_CONFIG_H`, which causes this header to be included by
 `internal.h`.  Without this macro, GLFW will expect the necessary configuration
 macros to be defined on the command-line.
 
-Three macros *must* be defined when compiling GLFW: one for selecting the window
+Three macros _must_ be defined when compiling GLFW: one for selecting the window
 creation API, one selecting the context creation API and one client library.
 Exactly one of each kind must be defined for GLFW to compile and link.
 
@@ -289,7 +289,7 @@ libraries.
 If you are building GLFW as a shared library / dynamic library / DLL then you
 must also define `_GLFW_BUILD_DLL`.  Otherwise, you may not define it.
 
-If you are using the X11 window creation API then you *must* also select an entry
+If you are using the X11 window creation API then you _must_ also select an entry
 point retrieval mechanism.
 
  - `_GLFW_HAS_GLXGETPROCADDRESS` to use `glXGetProcAddress` (recommended)

docs/context.dox

@@ -50,8 +50,8 @@ requests that all types are shared.
 See the relevant chapter of the [OpenGL](https://www.opengl.org/registry/) or
 [OpenGL ES](http://www.khronos.org/opengles/) reference documents for more
 information.  The name and number of this chapter unfortunately varies between
-versions and APIs, but has at times been named *Shared Objects and Multiple
-Contexts*.
+versions and APIs, but has at times been named _Shared Objects and Multiple
+Contexts_.
 
 GLFW comes with a simple object sharing test program called `sharing`.
 

docs/input.dox

@@ -65,7 +65,7 @@ glfwPostEmptyEvent.
 glfwPostEmptyEvent();
 @endcode
 
-Do not assume that callbacks will *only* be called through either of the above
+Do not assume that callbacks will _only_ be called through either of the above
 functions.  While it is necessary to process events in the event queue, some
 window systems will send some events directly to the application, which in turn
 causes callbacks to be called outside of regular event processing.
@@ -86,7 +86,7 @@ same keyboard layout, input method or even operating system as you.
 @subsection input_key Key input
 
 If you wish to be notified when a physical key is pressed or released or when it
-repeats, set a key callback with @ref glfwSetKeyCallback.
+repeats, set a key callback.
 
 @code
 glfwSetKeyCallback(window, key_callback);
@@ -110,7 +110,7 @@ have unique, if platform-specific scancodes.
 The scancode is unique for every key but is platform-specific, so a scancode
 will map to different keys on different platforms.
 
-The key will be `GLFW_KEY_UNKNOWN` for special keys like *E-mail* or *Play* that
+The key will be `GLFW_KEY_UNKNOWN` for special keys like _E-mail_ or _Play_ that
 don't have a key token.  Those keys will still have unique, if platform-specific
 scancodes.
 
@@ -148,8 +148,7 @@ The `GLFW_KEY_LAST` constant holds the highest value of any
 
 @subsection input_char Unicode character input
 
-If you wish to receive Unicode code point input, set a character callback with
-@ref glfwSetCharCallback.
+If you wish to receive Unicode code point input, set a character callback.
 
 @code
 glfwSetCharCallback(window, character_callback);
@@ -166,7 +165,7 @@ void character_callback(GLFWwindow* window, unsigned int codepoint)
 
 If you wish to receive all Unicode code point events generated by the system, or
 just want to know exactly what modifier keys were used, set a character with
-modifiers callback with @ref glfwSetCharModsCallback.
+modifiers callback.
 
 @code
 glfwSetCharCallback(window, charmods_callback);
@@ -192,7 +191,7 @@ these are supported by GLFW.
 @subsection input_cursor_pos Cursor position
 
 If you wish to be notified when the system cursor moves over the window, set
-a cursor position callback with @ref glfwSetCursorPosCallback.
+a cursor position callback.
 
 @code
 glfwSetCursorPosCallback(window, cursor_pos_callback);
@@ -287,6 +286,9 @@ image.pixels = pixels;
 GLFWcursor* cursor = glfwCreateCursor(&image, 0, 0);
 @endcode
 
+If cursor creation fails, `NULL` will be returned, so it is necessary to check
+the return value.
+
 The image data is 32-bit RGBA, i.e. eight bits per channel.  The pixels are
 arranged canonically as sequental rows, starting from the top-left corner.
 
@@ -299,7 +301,7 @@ When a cursor is no longer needed, destroy it with @ref glfwDestroyCursor.
 glfwDestroyCursor(cursor);
 @endcode
 
-Cursor destruction always succeeds.  All cursors remaining at the time of @ref
+Cursor destruction always succeeds.  All cursors remaining when @ref
 glfwTerminate is called are destroyed as well.
 
 
@@ -330,7 +332,7 @@ does not affect the cursor modes of those windows.
 @subsection input_cursor_enter Cursor enter/leave events
 
 If you wish to be notified when the cursor enters or leaves the client area of
-a window, set a cursor enter/leave callback with @ref glfwSetCursorEnterCallback.
+a window, set a cursor enter/leave callback.
 
 @code
 glfwSetCursorEnterCallback(window, cursor_enter_callback);
@@ -356,7 +358,7 @@ void cursor_enter_callback(GLFWwindow* window, int entered)
 @subsection input_mouse_button Mouse button input
 
 If you wish to be notified when a mouse button is pressed or released, set
-a mouse button callback with @ref glfwSetMouseButtonCallback.
+a mouse button callback.
 
 @code
 glfwSetMouseButtonCallback(window, mouse_button_callback);
@@ -412,7 +414,7 @@ The `GLFW_MOUSE_BUTTON_LAST` constant holds the highest value of any
 @subsection input_scroll Scroll input
 
 If you wish to be notified when the user scrolls, whether with a mouse wheel or
-touchpad gesture, set a scroll callback with @ref glfwSetScrollCallback.
+touchpad gesture, set a scroll callback.
 
 @code
 glfwSetScrollCallback(window, scroll_callback);
@@ -539,7 +541,7 @@ window may be used.
 @section input_drop Path drop input
 
 If you wish to receive the paths of files and/or directories dropped on
-a window, set a file drop callback with @ref glfwSetDropCallback.
+a window, set a file drop callback.
 
 @code
 glfwSetDropCallback(window, drop_callback);

docs/intro.dox

@@ -78,7 +78,7 @@ additional calls return 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
+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.
 

docs/main.dox

@@ -18,11 +18,11 @@ API.
 
 There are guides for each of the various areas of the API.
 
- - @ref intro
- - @ref window
- - @ref context
- - @ref monitor
- - @ref input
+ - @ref intro – initialization, error handling and high-level design
+ - @ref window – creating and working with windows and framebuffers
+ - @ref context – working with OpenGL and OpenGL ES contexts
+ - @ref monitor – enumerating and working with monitors and video modes
+ - @ref input – receiving events, polling and processing input
 
 The [FAQ](http://www.glfw.org/faq.html) answers many common questions about the
 design, implementation and use of GLFW.

docs/monitor.dox

@@ -24,9 +24,9 @@ a pointer to the [opaque](https://en.wikipedia.org/wiki/Opaque_data_type) type
 application and retain their addresses until the monitors they represent are
 disconnected or until the library is [terminated](@ref intro_init_terminate).
 
-Each monitor has a human-readable name, a current video mode, a list of
-supported video modes, a virtual position, an estimated physical size and
-a gamma ramp.  
+Each monitor has a current video mode, a list of supported video modes,
+a virtual position, a human-readable name, an estimated physical size and
+a gamma ramp.  One of the monitors is the primary monitor.
 
 The virtual position of a monitor is in screen coordinates and, together with
 the current video mode, describes the viewports that the connected monitors
@@ -37,7 +37,7 @@ provide into the virtual desktop that spans them.
 
 The primary monitor is returned by @ref glfwGetPrimaryMonitor.  It is the user's
 preferred monitor and is usually the one with global UI elements like task bar
-or menu bar.  The returned structure is allocated and freed by GLFW.
+or menu bar.
 
 @code
 GLFWmonitor* primary = glfwGetPrimaryMonitor();
@@ -59,7 +59,7 @@ disconnected.
 @subsection monitor_event Monitor configuration changes
 
 If you wish to be notified when a monitor is connected or disconnected, set
-a monitor callback with @ref glfwSetMonitorCallback.
+a monitor callback.
 
 @code
 glfwSetMonitorCallback(monitor_callback);
@@ -79,6 +79,11 @@ The action is one of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`.
 
 @section monitor_properties Monitor properties
 
+Each monitor has a current video mode, a list of supported video modes,
+a virtual position, a human-readable name, an estimated physical size and
+a gamma ramp.
+
+
 @subsection monitor_modes Video modes
 
 Although GLFW generally does a good job at selecting a suitable video
@@ -87,7 +92,7 @@ know exactly which modes are available on a certain system. For example,
 you may want to present the user with a list of video modes to select
 from.
 
-To get a list of available video modes, you can use the function @ref
+To get a list of supported video modes, you can use the function @ref
 glfwGetVideoModes.  See the reference documentation for the lifetime of the
 returned array.
 

docs/moving.dox

@@ -5,7 +5,7 @@
 @tableofcontents
 
 This is a transition guide for moving from GLFW 2 to 3.  It describes what has
-changed or been removed, but does *not* include
+changed or been removed, but does _not_ include
 [new features](@ref news) unless they are required when moving an existing code
 base onto the new API.  For example, the new multi-monitor functions are
 required to create full screen windows with GLFW 3.
@@ -50,7 +50,7 @@ the original author of GLFW.  These libraries implement a usable subset of the
 threading APIs in C++11 and C11, and in fact some GLFW 3 test programs use
 TinyCThread.
 
-However, GLFW 3 has better support for *use from multiple threads* than GLFW
+However, GLFW 3 has better support for _use from multiple threads_ than GLFW
 2 had.  Contexts can be made current on any thread, although only a single
 thread at a time, and the documentation explicitly states which functions may be
 used from any thread and which may only be used from the main thread.
@@ -149,7 +149,7 @@ into [window hints](@ref window_hints), but as they have been given
 
 GLFW 3 does not automatically poll for events on @ref glfwSwapBuffers, which
 means you need to call @ref glfwPollEvents or @ref glfwWaitEvents yourself.
-Unlike buffer swap, which acts on a single window, **glfwPollEvents** and
+Unlike buffer swap, which acts on a single window, __glfwPollEvents__ and
 __glfwWaitEvents__ process events for all windows at once.
 
 @par Old basic main loop
@@ -428,8 +428,8 @@ invalidating any window handles you may still have.
 @subsection moving_glu GLU header inclusion
 
 GLFW 3 does not by default include the GLU header and GLU itself has been
-deprecated by [Khronos](https://en.wikipedia.org/wiki/Khronos_Group).  **New
-projects should avoid using GLU**, but if you need to compile legacy code that
+deprecated by [Khronos](https://en.wikipedia.org/wiki/Khronos_Group).  __New
+projects should avoid using GLU__, but if you need to compile legacy code that
 has been moved to GLFW 3, you can request that the GLFW header includes it by
 defining `GLFW_INCLUDE_GLU` before the inclusion of the GLFW header.
 

docs/news.dox

@@ -139,7 +139,7 @@ glfwSetGamma, which generates a ramp from a gamma value and then sets it.
 
 GLFW now supports the creation of OpenGL ES contexts, by setting the
 `GLFW_CLIENT_API` window hint to `GLFW_OPENGL_ES_API`, where creation of such
-contexts are supported.  Note that GLFW *does not implement* OpenGL ES, so your
+contexts are supported.  Note that GLFW _does not implement_ OpenGL ES, so your
 driver must provide support in a way usable by GLFW.  Modern nVidia and Intel
 drivers support creation of OpenGL ES context using the GLX and WGL APIs, while
 AMD provides an EGL implementation instead.

docs/quick.dox

@@ -35,15 +35,15 @@ and pollute your code's namespace with the whole Win32 API.
 
 Instead, the GLFW header takes care of this for you, not by including
 `windows.h`, but rather by itself duplicating only the necessary parts of it.
-It does this only where needed, so if `windows.h` *is* included, the GLFW header
+It does this only where needed, so if `windows.h` _is_ included, the GLFW header
 does not try to redefine those symbols.
 
 In other words:
 
-- Do *not* include the OpenGL headers yourself, as GLFW does this for you
-- Do *not* include `windows.h` or other platform-specific headers unless
+- Do _not_ include the OpenGL headers yourself, as GLFW does this for you
+- Do _not_ include `windows.h` or other platform-specific headers unless
   you plan on using those APIs directly
-- If you *do* need to include such headers, do it *before* including the
+- If you _do_ need to include such headers, do it _before_ including the
   GLFW one and it will detect this
 
 Starting with version 3.0, the GLU header `glu.h` is no longer included by
@@ -162,7 +162,7 @@ Each window has a flag indicating whether the window should be closed.
 
 When the user attempts to close the window, either by pressing the close widget
 in the title bar or using a key combination like Alt+F4, this flag is set to 1.
-Note that **the window isn't actually closed**, so you are expected to monitor
+Note that __the window isn't actually closed__, so you are expected to monitor
 this flag and either destroy the window or give some kind of feedback to the
 user.
 
@@ -248,7 +248,7 @@ glfwSwapBuffers(window);
 @endcode
 
 The swap interval indicates how many frames to wait until swapping the buffers,
-commonly known as *vsync*.  By default, the swap interval is zero, meaning
+commonly known as _vsync_.  By default, the swap interval is zero, meaning
 buffer swapping will occur immediately.  On fast machines, many of those frames
 will never be seen, as the screen is still only updated typically 60-75 times
 per second, so this wastes a lot of CPU and GPU cycles.

docs/window.dox

@@ -38,32 +38,65 @@ GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL);
 If window creation fails, `NULL` will be returned, so it is necessary to check
 the return value.
 
-@code
-if (!window)
-{
-    // Handle window creation failure
-}
-@endcode
-
 The window handle is passed to all window related functions and is provided to
 along with all input events, so event handlers can tell which window received
 the event.
 
+
+@subsubsection window_full_screen Full screen windows
+
 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.  You
-can get this with @ref glfwGetPrimaryMonitor.  For more information about
-monitors, see the @ref monitor.
+should use.  In most cases, the user's primary monitor is a good choice.
+For more information about retrieving monitors, see @ref monitor_monitors. 
 
 @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.
+or decorations.
+
+The requested window size combined with the window hints below form the _desired
+video mode_.  The supported video mode most closely matching the desired video
+mode will be set for the chosen monitor as long as the window is focused.  For
+more information about video modes supported by a monitor, see @ref
+monitor_modes.
+
+Video mode field        | Corresponds to
+----------------------- | ------------------------
+GLFWvidmode.width       | `width` parameter
+GLFWvidmode.height      | `height` parameter
+GLFWvidmode.redBits     | `GLFW_RED_BITS` hint
+GLFWvidmode.greenBits   | `GLFW_GREEN_BITS` hint
+GLFWvidmode.blueBits    | `GLFW_BLUE_BITS` hint
+GLFWvidmode.refreshRate | `GLFW_REFRESH_RATE` hint
+
+Once you have a full screen window, you can change its resolution with @ref
+glfwSetWindowSize.  The new video mode will be selected and set the same way as
+the video mode chosen by @ref glfwCreateWindow.
+
+By default, the original video mode of the monitor will be restored and the
+window iconified if it loses input focus, to allow the user to switch back to
+the desktop.  This can be disabled with the `GLFW_AUTO_ICONIFY` window hint, for
+example if you wish to simultaneously cover multiple windows with full screen
+windows.
 
-For more control over how the window and its context are created, see @ref
-window_hints below.
+To create a so called _windowed full screen_ or _borderless full screen_ window,
+i.e. a full screen window that doesn't change the video mode of the monitor, you
+need to request the current video mode of the chosen monitor.
+
+@code
+const GLFWvidmode* mode = glfwGetVideoMode(monitor);
+
+glfwWindowHint(GLFW_RED_BITS, mode->redBits);
+glfwWindowHint(GLFW_GREEN_BITS, mode->greenBits);
+glfwWindowHint(GLFW_BLUE_BITS, mode->blueBits);
+glfwWindowHint(GLFW_REFRESH_RATE, mode->refreshRate);
+
+GLFWwindow* window = glfwCreateWindow(mode->width, mode->height, "My Title", monitor, NULL);
+@endcode
+
+GLFW will detect this and will not perform any mode setting for that window.   
 
 
 @subsection window_destruction Window destruction
@@ -80,8 +113,7 @@ callbacks are removed so no further events will be delivered for the window.
 When a full screen window is destroyed, the original video mode of its monitor
 is restored, but the gamma ramp is left untouched.
 
-All windows remaining at the time @ref glfwTerminate is called are destroyed as
-well.
+All windows remaining when @ref glfwTerminate is called are destroyed as well.
 
 
 @subsection window_hints Window creation hints
@@ -92,14 +124,14 @@ context.  These hints are set to their default values each time the library is
 initialized with @ref glfwInit, can be set individually with @ref glfwWindowHint
 and reset all at once to their defaults with @ref glfwDefaultWindowHints.
 
-Note that hints need to be set *before* the creation of the window and context
+Note that hints need to be set _before_ the creation of the window and context
 you wish to have the specified attributes.
 
 
 @subsubsection window_hints_hard Hard and soft constraints
 
 Some window hints are hard constraints.  These must match the available
-capabilities *exactly* for window and context creation to succeed.  Hints
+capabilities _exactly_ for window and context creation to succeed.  Hints
 that are not hard constraints are matched as closely as possible, but the
 resulting window and context may differ from what these hints requested.  To
 find out the actual attributes of the created window and context, use the
@@ -119,7 +151,7 @@ context, but are ignored when requesting an OpenGL ES context:
 @subsubsection window_hints_wnd Window related hints
 
 `GLFW_RESIZABLE` specifies whether the (windowed mode) window will be resizable
-*by the user*.  The window will still be resizable using the @ref
+_by the user_.  The window will still be resizable using the @ref
 glfwSetWindowSize function.  This hint is ignored for full screen windows.
 
 `GLFW_VISIBLE` specifies whether the (windowed mode) window will be initially
@@ -306,7 +338,7 @@ The initial value of the pointer is `NULL`.
 @subsection window_close Closing and close flag
 
 When the user attempts to close the window, for example by clicking the close
-widget or using a key chord like Alt+F4, the *close flag* of the window is set.
+widget or using a key chord like Alt+F4, the _close flag_ of the window is set.
 The window is however not actually destroyed and, unless you watch for this
 state change, nothing further happens.
 
@@ -325,13 +357,13 @@ while (!glfwWindowShouldClose(window))
 @endcode
 
 If you wish to be notified when the user attempts to close a window, set a close
-callback with @ref glfwSetWindowCloseCallback.
+callback.
 
 @code
 glfwSetWindowCloseCallback(window, window_close_callback);
 @endcode
 
-The callback function is called directly *after* the close flag has been set.
+The callback function is called directly _after_ the close flag has been set.
 It can be used for example to filter close requests and clear the close flag
 again unless certain conditions are met.
 
@@ -344,20 +376,23 @@ void window_close_callback(GLFWwindow* window)
 @endcode
 
 
-@subsection window_size Client area size
+@subsection window_size Size
 
 The size of a window can be changed with @ref glfwSetWindowSize.  For windowed
-mode windows, this resizes the window so that its *client area* has the
-specified size.  The window system may impose limits on window size.  For full
-screen windows, it selects and sets the video mode most closely matching the
-specified size and the color bit depth and refresh rate hints set at creation.
+mode windows, this sets the size of the _client area_ or _content area_ of the
+window.  The window system may impose limits on window size.
 
 @code
-void glfwSetWindowSize(window, 640, 480);
+glfwSetWindowSize(window, 640, 480);
 @endcode
 
+For full screen windows, the specified size becomes the new resolution of the
+window's *desired video mode*.  The video mode most closely matching the new
+desired video mode is set immediately.  The window is resized to fit the
+resolution of the set video mode.
+
 If you wish to be notified when a window is resized, whether by the user or
-the system, set a size callback with @ref glfwSetWindowSizeCallback.
+the system, set a size callback.
 
 @code
 glfwSetWindowSizeCallback(window, window_size_callback);
@@ -409,8 +444,7 @@ 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, set a size callback with @ref
-glfwSetFramebufferSizeCallback.
+by the user or the system, set a size callback.
 
 @code
 glfwSetFramebufferSizeCallback(window, framebuffer_size_callback);
@@ -452,7 +486,7 @@ glfwSetWindowPos(window, 100, 100);
 @endcode
 
 If you wish to be notified when a window is moved, whether by the user, system
-or your own code, set a position callback with @ref glfwSetWindowPosCallback.
+or your own code, set a position callback.
 
 @code
 glfwSetWindowPosCallback(window, window_pos_callback);
@@ -533,8 +567,7 @@ When a full screen window is restored, the desired video mode is restored to its
 monitor as well.
 
 If you wish to be notified when a window is iconified or restored, whether by
-the user, system or your own code, set a iconify callback with @ref
-glfwSetWindowIconifyCallback.
+the user, system or your own code, set a iconify callback.
 
 @code
 glfwSetWindowIconifyCallback(window, window_iconify_callback);
@@ -597,8 +630,7 @@ int visible = glfwGetWindowAttrib(window, GLFW_VISIBLE);
 @subsection window_focus Input focus
 
 If you wish to be notified when a window gains or loses focus, whether by
-the user, system or your own code, set a focus callback with @ref
-glfwSetWindowFocusCallback.
+the user, system or your own code, set a focus callback.
 
 @code
 glfwSetWindowFocusCallback(window, window_focus_callback);
@@ -630,8 +662,7 @@ int focused = glfwGetWindowAttrib(window, GLFW_FOCUSED);
 @subsection window_refresh Damage and refresh
 
 If you wish to be notified when the contents of a window is damaged and needs
-to be refreshed, set a window refresh callback with @ref
-glfwSetWindowRefreshCallback.
+to be refreshed, set a window refresh callback.
 
 @code
 glfwSetWindowRefreshCallback(m_handle, window_refresh_callback);
@@ -681,8 +712,8 @@ visibility can be controlled with @ref glfwShowWindow and @ref glfwHideWindow
 and initial visibility is controlled by the [window hint](@ref window_hints)
 with the same name.  
 
-`GLFW_RESIZABLE` indicates whether the specified window is resizable *by the
-user*.  This is controlled by the [window hint](@ref window_hints) with the same
+`GLFW_RESIZABLE` indicates whether the specified window is resizable _by the
+user_.  This is controlled by the [window hint](@ref window_hints) with the same
 name.
 
 `GLFW_DECORATED` indicates whether the specified window has decorations such as

include/GLFW/glfw3.h

@@ -263,7 +263,7 @@ extern "C" {
 
 /*! @defgroup keys Keyboard keys
  *
- * These key codes are inspired by the *USB HID Usage Tables v1.12* (p. 53-60),
+ * These key codes are inspired by the _USB HID Usage Tables v1.12_ (p. 53-60),
  * but re-arranged to map to 7-bit ASCII for printable keys (function keys are
  * put in the 256+ range).
  *
@@ -839,7 +839,7 @@ typedef void (* GLFWscrollfun)(GLFWwindow*,double,double);
  *  @param[in] window The window that received the event.
  *  @param[in] key The [keyboard key](@ref keys) that was pressed or released.
  *  @param[in] scancode The system-specific scancode of the key.
- *  @param[in] action @ref GLFW_PRESS, @ref GLFW_RELEASE or @ref GLFW_REPEAT.
+ *  @param[in] action `GLFW_PRESS`, `GLFW_RELEASE` or `GLFW_REPEAT`.
  *  @param[in] mods Bit field describing which [modifier keys](@ref mods) were
  *  held down.
  *
@@ -997,7 +997,7 @@ typedef struct GLFWimage
  *  @return `GL_TRUE` if successful, or `GL_FALSE` if an
  *  [error](@ref error_handling) occurred.
  *
- *  @remarks **OS X:** This function will change the current directory of the
+ *  @remarks __OS X:__ This function will change the current directory of the
  *  application to the `Contents/Resources` subdirectory of the application's
  *  bundle, if present.  This can be disabled with a
  *  [compile-time option](@ref compile_options_osx).
@@ -1012,7 +1012,7 @@ typedef struct GLFWimage
  *  Added in GLFW 1.0.
  *
  *  @par
- *  **GLFW 3:** This function no longer registers @ref glfwTerminate with `atexit`.
+ *  __GLFW 3:__ This function no longer registers @ref glfwTerminate with `atexit`.
  *
  *  @ingroup init
  */
@@ -1277,7 +1277,7 @@ GLFWAPI const char* glfwGetMonitorName(GLFWmonitor* monitor);
  *  @return The previously set callback, or `NULL` if no callback was set or the
  *  library had not been [initialized](@ref intro_init).
  *
- *  @bug **X11:** This callback is not yet called on monitor configuration
+ *  @bug __X11:__ This callback is not yet called on monitor configuration
  *  changes.
  *
  *  @par Thread Safety
@@ -1320,7 +1320,7 @@ GLFWAPI GLFWmonitorfun glfwSetMonitorCallback(GLFWmonitorfun cbfun);
  *  Added in GLFW 1.0.
  *
  *  @par
- *  **GLFW 3:** Changed to return a dynamic array of video modes for a specific
+ *  __GLFW 3:__ Changed to return a dynamic array of video modes for a specific
  *  monitor.
  *
  *  @ingroup monitor
@@ -1463,7 +1463,7 @@ GLFWAPI void glfwDefaultWindowHints(void);
  *  Added in GLFW 2.2.
  *
  *  @par
- *  **GLFW 3:** Renamed from `glfwOpenWindowHint`.  Hints are no longer reset to
+ *  __GLFW 3:__ Renamed from `glfwOpenWindowHint`.  Hints are no longer reset to
  *  default values on window creation.
  *
  *  @ingroup window
@@ -1494,17 +1494,24 @@ GLFWAPI void glfwWindowHint(int target, int hint);
  *  that you pick the primary monitor.  For more information on how to query
  *  connected monitors, see @ref monitor_monitors.
  *
+ *  For full screen windows, the specified size becomes the resolution of the
+ *  window's _desired video mode_.  As long as a full screen window has input
+ *  focus, the supported video mode most closely matching the desired video mode
+ *  is set for the specified monitor.  For more information about full screen
+ *  windows, including the creation of so called _windowed full screen_ or
+ *  _borderless full screen_ windows, see @ref window_full_screen.
+ *
  *  By default, newly created windows use the placement recommended by the
  *  window system.  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.
+ *  initially invisible using the `GLFW_VISIBLE` window hint, set its
+ *  [position](@ref window_pos) and then [show](@ref window_hide) it.
  *
- *  If a full screen window is active, the screensaver is prohibited from
+ *  If a full screen window is focused, the screensaver is prohibited from
  *  starting.
  *
  *  Window systems put limits on window sizes.  Very large or very small window
  *  dimensions may be overridden by the window system on creation.  Check the
- *  actual [window size](@ref window_size) after creation.
+ *  actual [size](@ref window_size) after creation.
  *
  *  The [swap interval](@ref window_swap) is not set during window creation and
  *  the initial value may vary depending on driver settings and defaults.
@@ -1521,27 +1528,27 @@ GLFWAPI void glfwWindowHint(int target, int hint);
  *  @return The handle of the created window, or `NULL` if an
  *  [error](@ref error_handling) occurred.
  *
- *  @remarks **Windows:** Window creation will fail if the Microsoft GDI
+ *  @remarks __Windows:__ Window creation will fail if the Microsoft GDI
  *  software OpenGL implementation is the only one available.
  *
- *  @remarks **Windows:** If the executable has an icon resource named
+ *  @remarks __Windows:__ If the executable has an icon resource named
  *  `GLFW_ICON,` it will be set as the icon for the window.  If no such icon is
  *  present, the `IDI_WINLOGO` icon will be used instead.
  *
- *  @remarks **OS X:** The GLFW window has no icon, as it is not a document
+ *  @remarks __OS X:__ The GLFW window has no icon, as it is not a document
  *  window, but the dock icon will be the same as the application bundle's icon.
  *  For more information on bundles, see the
  *  [Bundle Programming Guide](https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/)
  *  in the Mac Developer Library.
  *
- *  @remarks **OS X:** The first time a window is opened the menu bar is populated with
+ *  @remarks __OS X:__ The first time a window is opened the menu bar is populated with
  *  common commands like Hide, Quit and About.  The About entry opens a minimal
  *  about dialog with information from the application's bundle.  The menu bar can be
  *  disabled with a [compile-time option](@ref compile_options_osx).
  *
- *  @remarks **X11:** There is no mechanism for setting the window icon yet.
+ *  @remarks __X11:__ There is no mechanism for setting the window icon yet.
  *
- *  @remarks **X11:** Some window managers will not respect the placement of
+ *  @remarks __X11:__ Some window managers will not respect the placement of
  *  initially hidden windows.
  *
  *  @note This function may not be called from a callback.
@@ -1556,7 +1563,7 @@ GLFWAPI void glfwWindowHint(int target, int hint);
  *  Added in GLFW 1.0.
  *
  *  @par
- *  **GLFW 3:** Renamed from `glfwOpenWindow`.  Complete signature overhaul.
+ *  __GLFW 3:__ Renamed from `glfwOpenWindow`.  Complete signature overhaul.
  *
  *  @ingroup window
  */
@@ -1587,7 +1594,7 @@ GLFWAPI GLFWwindow* glfwCreateWindow(int width, int height, const char* title, G
  *  Added in GLFW 1.0.
  *
  *  @par
- *  **GLFW 3:** Renamed from `glfwCloseWindow`.  Added window handle parameter.
+ *  __GLFW 3:__ Renamed from `glfwCloseWindow`.  Added window handle parameter.
  *
  *  @ingroup window
  */
@@ -1650,7 +1657,7 @@ GLFWAPI void glfwSetWindowShouldClose(GLFWwindow* window, int value);
  *  Added in GLFW 1.0.
  *
  *  @par
- *  **GLFW 3:** Added window handle parameter.
+ *  __GLFW 3:__ Added window handle parameter.
  *
  *  @ingroup window
  */
@@ -1708,7 +1715,7 @@ GLFWAPI void glfwGetWindowPos(GLFWwindow* window, int* xpos, int* ypos);
  *  Added in GLFW 1.0.
  *
  *  @par
- *  **GLFW 3:** Added window handle parameter.
+ *  __GLFW 3:__ Added window handle parameter.
  *
  *  @ingroup window
  */
@@ -1739,7 +1746,7 @@ GLFWAPI void glfwSetWindowPos(GLFWwindow* window, int xpos, int ypos);
  *  Added in GLFW 1.0.
  *
  *  @par
- *  **GLFW 3:** Added window handle parameter.
+ *  __GLFW 3:__ Added window handle parameter.
  *
  *  @ingroup window
  */
@@ -1771,7 +1778,7 @@ GLFWAPI void glfwGetWindowSize(GLFWwindow* window, int* width, int* height);
  *  Added in GLFW 1.0.
  *
  *  @par
- *  **GLFW 3:** Added window handle parameter.
+ *  __GLFW 3:__ Added window handle parameter.
  *
  *  @ingroup window
  */
@@ -1862,7 +1869,7 @@ GLFWAPI void glfwGetWindowFrameSize(GLFWwindow* window, int* left, int* top, int
  *  Added in GLFW 2.1.
  *
  *  @par
- *  **GLFW 3:** Added window handle parameter.
+ *  __GLFW 3:__ Added window handle parameter.
  *
  *  @ingroup window
  */
@@ -1888,7 +1895,7 @@ GLFWAPI void glfwIconifyWindow(GLFWwindow* window);
  *  Added in GLFW 2.1.
  *
  *  @par
- *  **GLFW 3:** Added window handle parameter.
+ *  __GLFW 3:__ Added window handle parameter.
  *
  *  @ingroup window
  */
@@ -1977,7 +1984,7 @@ GLFWAPI GLFWmonitor* glfwGetWindowMonitor(GLFWwindow* window);
  *  Added in GLFW 1.0.
  *
  *  @par
- *  **GLFW 3:** Renamed from `glfwGetWindowParam`.  Added window handle
+ *  __GLFW 3:__ Renamed from `glfwGetWindowParam`.  Added window handle
  *  parameter.
  *
  *  @ingroup window
@@ -2047,7 +2054,7 @@ GLFWAPI void* glfwGetWindowUserPointer(GLFWwindow* window);
  *  Added in GLFW 3.0.
  *
  *  @par
- *  **GLFW 3:** Added window handle parameter.  Updated callback signature.
+ *  __GLFW 3:__ Added window handle parameter.  Updated callback signature.
  *
  *  @ingroup window
  */
@@ -2074,7 +2081,7 @@ GLFWAPI GLFWwindowposfun glfwSetWindowPosCallback(GLFWwindow* window, GLFWwindow
  *  Added in GLFW 1.0.
  *
  *  @par
- *  **GLFW 3:** Added window handle parameter.  Updated callback signature.
+ *  __GLFW 3:__ Added window handle parameter.  Updated callback signature.
  *
  *  @ingroup window
  */
@@ -2097,7 +2104,7 @@ GLFWAPI GLFWwindowsizefun glfwSetWindowSizeCallback(GLFWwindow* window, GLFWwind
  *  @return The previously set callback, or `NULL` if no callback was set or the
  *  library had not been [initialized](@ref intro_init).
  *
- *  @remarks **OS X:** Selecting Quit from the application menu will
+ *  @remarks __OS X:__ Selecting Quit from the application menu will
  *  trigger the close callback for all windows.
  *
  *  @par Thread Safety
@@ -2109,7 +2116,7 @@ GLFWAPI GLFWwindowsizefun glfwSetWindowSizeCallback(GLFWwindow* window, GLFWwind
  *  Added in GLFW 2.5.
  *
  *  @par
- *  **GLFW 3:** Added window handle parameter.  Updated callback signature.
+ *  __GLFW 3:__ Added window handle parameter.  Updated callback signature.
  *
  *  @ingroup window
  */
@@ -2140,7 +2147,7 @@ GLFWAPI GLFWwindowclosefun glfwSetWindowCloseCallback(GLFWwindow* window, GLFWwi
  *  Added in GLFW 2.5.
  *
  *  @par
- *  **GLFW 3:** Added window handle parameter.  Updated callback signature.
+ *  __GLFW 3:__ Added window handle parameter.  Updated callback signature.
  *
  *  @ingroup window
  */
@@ -2250,7 +2257,7 @@ GLFWAPI GLFWframebuffersizefun glfwSetFramebufferSizeCallback(GLFWwindow* window
  *  Added in GLFW 1.0.
  *
  *  @par
- *  **GLFW 3:** This function is no longer called by @ref glfwSwapBuffers.
+ *  __GLFW 3:__ This function is no longer called by @ref glfwSwapBuffers.
  *
  *  @ingroup window
  */
@@ -2322,6 +2329,10 @@ GLFWAPI void glfwWaitEvents(void);
 GLFWAPI void glfwPostEmptyEvent(void);
 
 /*! @brief Returns the value of an input option for the specified window.
+ *
+ *  This function returns the value of an input option for the specified window.
+ *  The mode must be one of `GLFW_CURSOR`, `GLFW_STICKY_KEYS` or
+ *  `GLFW_STICKY_MOUSE_BUTTONS`.
  *
  *  @param[in] window The window to query.
  *  @param[in] mode One of `GLFW_CURSOR`, `GLFW_STICKY_KEYS` or
@@ -2340,10 +2351,10 @@ GLFWAPI void glfwPostEmptyEvent(void);
 GLFWAPI int glfwGetInputMode(GLFWwindow* window, int mode);
 
 /*! @brief Sets an input option for the specified window.
- *  @param[in] window The window whose input mode to set.
- *  @param[in] mode One of `GLFW_CURSOR`, `GLFW_STICKY_KEYS` or
+ *
+ *  This function sets an input mode option for the specified window.  The mode
+ *  must be one of `GLFW_CURSOR`, `GLFW_STICKY_KEYS` or
  *  `GLFW_STICKY_MOUSE_BUTTONS`.
- *  @param[in] value The new value of the specified input mode.
  *
  *  If the mode is `GLFW_CURSOR`, the value must be one of the following cursor
  *  modes:
@@ -2358,18 +2369,23 @@ GLFWAPI int glfwGetInputMode(GLFWwindow* window, int mode);
  *
  *  If the mode is `GLFW_STICKY_KEYS`, the value must be either `GL_TRUE` to
  *  enable sticky keys, or `GL_FALSE` to disable it.  If sticky keys are
- *  enabled, a key press will ensure that @ref glfwGetKey returns @ref
- *  GLFW_PRESS the next time it is called even if the key had been released
- *  before the call.  This is useful when you are only interested in whether
- *  keys have been pressed but not when or in which order.
+ *  enabled, a key press will ensure that @ref glfwGetKey returns `GLFW_PRESS`
+ *  the next time it is called even if the key had been released before the
+ *  call.  This is useful when you are only interested in whether keys have been
+ *  pressed but not when or in which order.
  *
  *  If the mode is `GLFW_STICKY_MOUSE_BUTTONS`, the value must be either
  *  `GL_TRUE` to enable sticky mouse buttons, or `GL_FALSE` to disable it.  If
  *  sticky mouse buttons are enabled, a mouse button press will ensure that @ref
- *  glfwGetMouseButton returns @ref GLFW_PRESS the next time it is called even
- *  if the mouse button had been released before the call.  This is useful when
- *  you are only interested in whether mouse buttons have been pressed but not
- *  when or in which order.
+ *  glfwGetMouseButton returns `GLFW_PRESS` the next time it is called even if
+ *  the mouse button had been released before the call.  This is useful when you
+ *  are only interested in whether mouse buttons have been pressed but not when
+ *  or in which order.
+ *
+ *  @param[in] window The window whose input mode to set.
+ *  @param[in] mode One of `GLFW_CURSOR`, `GLFW_STICKY_KEYS` or
+ *  `GLFW_STICKY_MOUSE_BUTTONS`.
+ *  @param[in] value The new value of the specified input mode.
  *
  *  @par Thread Safety
  *  This function may only be called from the main thread.
@@ -2416,7 +2432,7 @@ GLFWAPI void glfwSetInputMode(GLFWwindow* window, int mode, int value);
  *  Added in GLFW 1.0.
  *
  *  @par
- *  **GLFW 3:** Added window handle parameter.
+ *  __GLFW 3:__ Added window handle parameter.
  *
  *  @ingroup input
  */
@@ -2447,7 +2463,7 @@ GLFWAPI int glfwGetKey(GLFWwindow* window, int key);
  *  Added in GLFW 1.0.
  *
  *  @par
- *  **GLFW 3:** Added window handle parameter.
+ *  __GLFW 3:__ Added window handle parameter.
  *
  *  @ingroup input
  */
@@ -2487,7 +2503,7 @@ GLFWAPI int glfwGetMouseButton(GLFWwindow* window, int button);
  *  Added in GLFW 1.0.
  *
  *  @par
- *  **GLFW 3:** Renamed from `glfwGetMousePos`.  Added window handle parameter.
+ *  __GLFW 3:__ Renamed from `glfwGetMousePos`.  Added window handle parameter.
  *  Moved to floating-point coordinates.
  *
  *  @ingroup input
@@ -2512,7 +2528,7 @@ GLFWAPI void glfwGetCursorPos(GLFWwindow* window, double* xpos, double* ypos);
  *  @param[in] ypos The desired y-coordinate, relative to the top edge of the
  *  client area.
  *
- *  @remarks **X11:** Due to the asynchronous nature of a modern X desktop, it
+ *  @remarks __X11:__ Due to the asynchronous nature of a modern X desktop, it
  *  may take a moment for the window focus event to arrive.  This means you will
  *  not be able to set the cursor position directly after window creation.
  *
@@ -2526,7 +2542,7 @@ GLFWAPI void glfwGetCursorPos(GLFWwindow* window, double* xpos, double* ypos);
  *  Added in GLFW 1.0.
  *
  *  @par
- *  **GLFW 3:** Renamed from `glfwSetMousePos`.  Added window handle parameter.
+ *  __GLFW 3:__ Renamed from `glfwSetMousePos`.  Added window handle parameter.
  *  Moved to floating-point coordinates.
  *
  *  @ingroup input
@@ -2650,7 +2666,7 @@ GLFWAPI void glfwSetCursor(GLFWwindow* window, GLFWcursor* cursor);
  *  Added in GLFW 1.0.
  *
  *  @par
- *  **GLFW 3:** Added window handle parameter.  Updated callback signature.
+ *  __GLFW 3:__ Added window handle parameter.  Updated callback signature.
  *
  *  @ingroup input
  */
@@ -2690,7 +2706,7 @@ GLFWAPI GLFWkeyfun glfwSetKeyCallback(GLFWwindow* window, GLFWkeyfun cbfun);
  *  Added in GLFW 2.4.
  *
  *  @par
- *  **GLFW 3:** Added window handle parameter.  Updated callback signature.
+ *  __GLFW 3:__ Added window handle parameter.  Updated callback signature.
  *
  *  @ingroup input
  */
@@ -2755,7 +2771,7 @@ GLFWAPI GLFWcharmodsfun glfwSetCharModsCallback(GLFWwindow* window, GLFWcharmods
  *  Added in GLFW 1.0.
  *
  *  @par
- *  **GLFW 3:** Added window handle parameter.  Updated callback signature.
+ *  __GLFW 3:__ Added window handle parameter.  Updated callback signature.
  *
  *  @ingroup input
  */
@@ -2783,7 +2799,7 @@ GLFWAPI GLFWmousebuttonfun glfwSetMouseButtonCallback(GLFWwindow* window, GLFWmo
  *  Added in GLFW 1.0.
  *
  *  @par
- *  **GLFW 3:** Renamed from `glfwSetMousePosCallback`. Added window handle
+ *  __GLFW 3:__ Renamed from `glfwSetMousePosCallback`. Added window handle
  *  parameter.  Updated callback signature.
  *
  *  @ingroup input
@@ -2838,7 +2854,7 @@ GLFWAPI GLFWcursorenterfun glfwSetCursorEnterCallback(GLFWwindow* window, GLFWcu
  *  Added in GLFW 2.1.
  *
  *  @par
- *  **GLFW 3:** Renamed from `glfwSetMouseWheelCallback`.  Added window handle.
+ *  __GLFW 3:__ Renamed from `glfwSetMouseWheelCallback`.  Added window handle.
  *  Updated callback signature.
  *
  *  @ingroup input
@@ -2916,7 +2932,7 @@ GLFWAPI int glfwJoystickPresent(int joy);
  *  Added in GLFW 2.2.
  *
  *  @par
- *  **GLFW 3:** Renamed from `glfwGetJoystickPos`.  Changed to return a dynamic
+ *  __GLFW 3:__ Renamed from `glfwGetJoystickPos`.  Changed to return a dynamic
  *  array.
  *
  *  @ingroup input
@@ -2947,7 +2963,7 @@ GLFWAPI const float* glfwGetJoystickAxes(int joy, int* count);
  *  Added in GLFW 2.2.
  *
  *  @par
- *  **GLFW 3:** Changed to return a dynamic array.
+ *  __GLFW 3:__ Changed to return a dynamic array.
  *
  *  @ingroup input
  */
@@ -3143,7 +3159,7 @@ GLFWAPI GLFWwindow* glfwGetCurrentContext(void);
  *  Added in GLFW 1.0.
  *
  *  @par
- *  **GLFW 3:** Added window handle parameter.  Removed call to @ref
+ *  __GLFW 3:__ Added window handle parameter.  Removed call to @ref
  *  glfwPollEvents.
  *
  *  @ingroup window