Documentation work.

Fixes #212.
Fixes #420.

docs/compile.dox

@@ -229,8 +229,9 @@ can lead to severe jitter.
 
 `GLFW_USE_OPTIMUS_HPG` determines whether to export the `NvOptimusEnablement`
 symbol, which forces the use of the high-performance GPU on Nvidia Optimus
-systems.  This symbol needs to be exported by the EXE, so the override will not
-work if GLFW is built as a DLL.
+systems.  This symbol needs to be exported by the EXE to be detected by the
+driver, so the override will not work if GLFW is built as a DLL.  See _Enabling
+High Performance Graphics Rendering on Optimus Systems_ for more details.
 
 
 @subsubsection compile_options_egl EGL specific CMake options

docs/intro.dox

@@ -327,7 +327,7 @@ 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
+__Do not use the version string__ to parse the GLFW library version.  The @ref
 glfwGetVersion function already provides the version of the running library
 binary.
 

docs/moving.dox

@@ -390,7 +390,7 @@ All explicit support for version of Windows older than XP has been removed.
 There is no code that actively prevents GLFW 3 from running on these earlier
 versions, but it uses Win32 functions that those versions lack.
 
-Windows XP was released in 2001, and by now (2013) it has not only
+Windows XP was released in 2001, and by now (January 2015) it has not only
 replaced almost all earlier versions of Windows, but is itself rapidly being
 replaced by Windows 7 and 8.  The MSDN library doesn't even provide
 documentation for version older than Windows 2000, making it difficult to

docs/rift.dox

@@ -4,53 +4,114 @@
  
 @tableofcontents
 
-GLFW has no explicit support for the Oculus Rift, but 
+This guide requires you to use [native access](@ref native) and assumes
+a certain level of proficiency with LibOVR, OS specific APIs and your chosen
+development environment.  It intends only to fill in the gaps between the
+[Oculus PC SDK documentation](https://developer.oculus.com/documentation/) and
+the GLFW API and is not a replacement for the documentation for those APIs.
 
-This guide requires you to use the [native API](@ref native) and assumes
-a certain level of proficiency with system level APIs and the compiler
-toolchain.
+While GLFW has no explicit support for LibOVR, the Oculus PC SDK library, it is
+tested with and tries to interoperate well with it.
 
+@note Because of the speed of development of the Oculus SDK, this guide may
+become outdated before the next release.  If this is a local copy from a GLFW
+release archive, check the GLFW website for an up-to-date version.
 
-@section rift_init Initializing libOVR and GLFW
 
-libOVR needs to be initialized before GLFW.  This means calling
+@section rift_include Including the LibOVR and GLFW header files
+
+Both the LibOVR OpenGL header and the GLFW native header need macros telling
+them what OS you are building for.  Because LibOVR only supports three major
+desktop OSes, this can be solved with the canonical predefined macros.
+
+@code
+#if defined(_WIN32)
+ #define GLFW_EXPOSE_NATIVE_WIN32
+ #define GLFW_EXPOSE_NATIVE_WGL
+ #define OVR_OS_WIN32
+#elif defined(__APPLE__)
+ #define GLFW_EXPOSE_NATIVE_COCOA
+ #define GLFW_EXPOSE_NATIVE_NSGL
+ #define OVR_OS_MAC
+#elif defined(__linux__)
+ #define GLFW_EXPOSE_NATIVE_X11
+ #define GLFW_EXPOSE_NATIVE_GLX
+ #define OVR_OS_LINUX
+#else
+ #error "Platform unsupported"
+#endif
+
+#include <GLFW/glfw3.h>
+#include <GLFW/glfw3native.h>
+
+#include <OVR_CAPI_GL.h>
+@endcode
+
+Both the GLFW and LibOVR headers by default attempt to include the standard
+OpenGL `GL/gl.h` header (`OpenGL/gl.h` on OS X).  If you wish to use a different
+standard header or an [extension loading library](@ref context_glext_auto),
+include that header before these.
+
+
+@section rift_init Initializing LibOVR and GLFW
+
+LibOVR needs to be initialized before GLFW.  This means calling at least
 `ovr_Initialize`, `ovrHmd_Create` and `ovrHmd_ConfigureTracking` before @ref
-glfwInit.  Similarly, libOVR must be shut down after GLFW.  This means calling
+glfwInit.  Similarly, LibOVR must be shut down after GLFW.  This means calling
 `ovrHmd_Destroy` and `ovr_Shutdown` after @ref glfwTerminate.
 
 
-@section rift_extend Extend Desktop mode
+@section rift_direct Direct HMD mode
 
-@subsection rift_extend_detect Detecting a Rift with GLFW
+Direct HMD mode is the recommended display mode for new applications, but the
+Oculus Rift runtime currently (January 2015) only supports this mode on Windows.
+In direct mode the HMD is not detectable as a GLFW monitor.
 
-If you have an actual Rift connected to your machine you can deduce which GLFW
-monitor it corresponds to.  Doing this requires you to use the
-[native API](@ref native).
 
+@subsection rift_direct_create Creating a window and context
 
-@subsubsection rift_extend_detect_win32 Detecting a Rift on Windows
+If the HMD is in direct mode you can use either a full screen or a windowed mode
+window, but full screen is only recommended if there is a monitor that supports
+the resolution of the HMD.  Due to limitations in LibOVR, the size of the client
+area of the window must equal the resolution of the HMD.
 
-The native display device name of a GLFW monitor, as returned by @ref
-glfwGetWin32Monitor, corresponds to the display device name of the detected Rift
-as stored, in the `DisplayDeviceName` member of `ovrHmdDesc`.
+If the resolution of the HMD is much larger than the regular monitor, the window
+may be resized by the window manager on creation.  One way to avoid this is to
+make it undecorated with the [GLFW_DECORATED](@ref window_hints_wnd) window
+hint.
 
-@code
-int i, count;
-GLFWmonitor** monitors = glfwGetMonitors(&count);
 
-for (i = 0;  i < count;  i++)
-{
-    if (strcmp(glfwGetWin32Monitor(monitors[i]), hmd->DisplayDeviceName) == 0)
-        return monitors[i];
-}
+@subsection rift_direct_attach Attaching the window to the HMD
+
+Once you have created the window and context, you need to attach the native
+handle of the GLFW window to the HMD.
+
+@code
+ovrHmd_AttachToWindow(hmd, glfwGetWin32Window(window), NULL, NULL);
 @endcode
 
 
-@subsubsection rift_extend_detect_osx Detecting a Rift on OS X
+@section rift_extend Extend Desktop mode
+
+Extend desktop mode is a legacy display mode, but is still (January 2015) the
+only available mode on OS X and Linux, as well as on Windows machines that for
+technical reasons do not yet support direct HMD mode.
+
+
+@subsection rift_extend_detect Detecting a HMD with GLFW
+
+If the HMD is in extend desktop mode you can deduce which GLFW monitor it
+corresponds to and create a full screen window on that monitor.
+
+On Windows, the native display device name of a GLFW monitor corresponds to the
+display device name of the detected HMD as stored, in the `DisplayDeviceName`
+member of `ovrHmdDesc`.
 
-The native display ID of a GLFW monitor, as returned by @ref
-glfwGetCocoaMonitor, corresponds to the display ID of the detected Rift, as
-stored in the `DisplayId` member of `ovrHmdDesc`.
+On OS X, the native display ID of a GLFW monitor corresponds to the display ID
+of the detected HMD, as stored in the `DisplayId` member of `ovrHmdDesc`.
+
+At the time of writing (January 2015), the Oculus SDK does not support detecting
+which monitor corresponds to the HMD in any sane fashion.
 
 @code
 int i, count;
@@ -58,24 +119,59 @@ GLFWmonitor** monitors = glfwGetMonitors(&count);
 
 for (i = 0;  i < count;  i++)
 {
+#if defined(_WIN32)
+    if (strcmp(glfwGetWin32Monitor(monitors[i]), hmd->DisplayDeviceName) == 0)
+        return monitors[i];
+#elif defined(__APPLE__)
     if (glfwGetCocoaMonitor(monitors[i]) == hmd->DisplayId)
         return monitors[i];
+#elif defined(__linux__)
+#endif
 }
 @endcode
 
 
-@subsubsection rift_extend_detect_x11 Detecting a Rift on X11
+@subsection rift_extend_create Creating a window and context
 
-At the time of writing, the 0.4 Rift SDK does not yet support X11.
+The window is created as a regular full screen window on the found monitor.  It
+is usually a good idea to create a
+[windowed full screen](@ref window_windowed_full_screen) window, as the HMD will
+very likely already be set to the correct video mode.  However, in extend
+desktop mode it behaves like a regular monitor and any supported video mode can
+be requested.
 
+If other monitors are mirroring the HMD and you request a different video mode,
+all monitors in the mirroring set will get the new video mode.
 
-@subsection rift_extend_create Creating a window and context
 
-LOL create.
+@section rift_render Rendering to the HMD
 
+Once the window and context is created, you can render to it the same as any
+other application using LibOVR.
 
-@section rift_direct Direct HMD mode
+If you wish to use SDK distortion rendering you will need some information from
+GLFW to configure the renderer.  Below are the parts of the `ovrGLConfig` union
+that need to be filled with from GLFW.  Note that there are other fields that
+also need to be filled for `ovrHmd_ConfigureRendering` to succeed.
+
+@code
+    int width, height;
+    union ovrGLConfig config;
+
+    glfwGetFramebufferSize(window, &width, &height);
+
+    config.OGL.Header.BackBufferSize.w = width;
+    config.OGL.Header.BackBufferSize.h = height;
+#if defined(_WIN32)
+    config.OGL.Window = glfwGetWin32Window(window);
+    config.OGL.DC = GetDC(config.OGL.Window);
+#elif defined(__APPLE__)
+#elif defined(__linux__)
+    config.OGL.Disp = glfwGetX11Display();
+#endif
+@endcode
 
-LOL direct.
+When using SDK distortion rendering you should not call @ref glfwSwapBuffers,
+as the HMD is updated by `ovrHmd_EndFrame`.
 
 */

docs/window.dox

@@ -481,9 +481,8 @@ glfwGetFramebufferSize(window, &width, &height);
 glViewport(0, 0, width, height);
 @endcode
 
-Note that the size of a framebuffer may change independently of the size of
-a window, for example if the window is dragged between a regular monitor and
-a high-DPI one.
+The size of a framebuffer may change independently of the size of a window, for
+example if the window is dragged between a regular monitor and a high-DPI one.
 
 
 @subsection window_pos Position

include/GLFW/glfw3.h

@@ -513,7 +513,8 @@ extern "C" {
 /*! @brief One of the arguments to the function was an invalid enum value.
  *
  *  One of the arguments to the function was an invalid enum value, for example
- *  requesting `GLFW_RED_BITS` with @ref glfwGetWindowAttrib.
+ *  requesting [GLFW_RED_BITS](@ref window_hints_fb) with @ref
+ *  glfwGetWindowAttrib.
  *
  *  @par Analysis
  *  Application programmer error.  Fix the offending call.
@@ -1099,9 +1100,6 @@ typedef struct GLFWimage
  *  @par History
  *  Added in GLFW 1.0.
  *
- *  @par
- *  __GLFW 3:__ This function no longer registers @ref glfwTerminate with `atexit`.
- *
  *  @ingroup init
  */
 GLFWAPI int glfwInit(void);
@@ -1174,6 +1172,10 @@ GLFWAPI void glfwGetVersion(int* major, int* minor, int* rev);
  *  describes the version, platform, compiler and any platform-specific
  *  compile-time options.
  *
+ *  __Do not use the version string__ to parse the GLFW library version.  The
+ *  @ref glfwGetVersion function already provides the version of the running
+ *  library binary.
+ *
  *  This function always succeeds.
  *
  *  @return The GLFW version string.
@@ -1313,10 +1315,10 @@ GLFWAPI void glfwGetMonitorPos(GLFWmonitor* monitor, int* xpos, int* ypos);
  *  non-`NULL` size arguments will be set to zero.
  *
  *  @param[in] monitor The monitor to query.
- *  @param[out] width Where to store the width, in mm, of the monitor's display
- *  area, or `NULL`.
- *  @param[out] height Where to store the height, in mm, of the monitor's
- *  display area, or `NULL`.
+ *  @param[out] widthMM Where to store the width, in millimetres, of the
+ *  monitor's display area, or `NULL`.
+ *  @param[out] heightMM Where to store the height, in millimetres, of the
+ *  monitor's display area, or `NULL`.
  *
  *  @note Some systems do not provide accurate monitor size information, either
  *  because the EDID data is incorrect, or because the driver does not report it
@@ -1332,7 +1334,7 @@ GLFWAPI void glfwGetMonitorPos(GLFWmonitor* monitor, int* xpos, int* ypos);
  *
  *  @ingroup monitor
  */
-GLFWAPI void glfwGetMonitorPhysicalSize(GLFWmonitor* monitor, int* width, int* height);
+GLFWAPI void glfwGetMonitorPhysicalSize(GLFWmonitor* monitor, int* widthMM, int* heightMM);
 
 /*! @brief Returns the name of the specified monitor.
  *
@@ -1415,8 +1417,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
- *  monitor.
+ *  __GLFW 3:__ Changed to return an array of modes for a specific monitor.
  *
  *  @ingroup monitor
  */
@@ -1444,7 +1445,7 @@ GLFWAPI const GLFWvidmode* glfwGetVideoModes(GLFWmonitor* monitor, int* count);
  *  @sa glfwGetVideoModes
  *
  *  @par History
- *  Added in GLFW 3.0.  Replaced `glfwGetDesktopMode`.
+ *  Added in GLFW 3.0.  Replaces `glfwGetDesktopMode`.
  *
  *  @ingroup monitor
  */
@@ -1557,11 +1558,7 @@ GLFWAPI void glfwDefaultWindowHints(void);
  *  @sa glfwDefaultWindowHints
  *
  *  @par History
- *  Added in GLFW 2.2.
- *
- *  @par
- *  __GLFW 3:__ Renamed from `glfwOpenWindowHint`.  Hints are no longer reset to
- *  default values on window creation.
+ *  Added in GLFW 3.0.  Replaces `glfwOpenWindowHint`.
  *
  *  @ingroup window
  */
@@ -1596,12 +1593,13 @@ GLFWAPI void glfwWindowHint(int target, int hint);
  *  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.
+ *  _borderless full screen_ windows, see @ref window_windowed_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](@ref window_pos) and then [show](@ref window_hide) it.
+ *  initially invisible using the [GLFW_VISIBLE](@ref window_hints_wnd) window
+ *  hint, set its [position](@ref window_pos) and then [show](@ref window_hide)
+ *  it.
  *
  *  If a full screen window is focused, the screensaver is prohibited from
  *  starting.
@@ -1662,10 +1660,7 @@ GLFWAPI void glfwWindowHint(int target, int hint);
  *  @sa glfwDestroyWindow
  *
  *  @par History
- *  Added in GLFW 1.0.
- *
- *  @par
- *  __GLFW 3:__ Renamed from `glfwOpenWindow`.  Complete signature overhaul.
+ *  Added in GLFW 3.0.  Replaces `glfwOpenWindow`.
  *
  *  @ingroup window
  */
@@ -1694,10 +1689,7 @@ GLFWAPI GLFWwindow* glfwCreateWindow(int width, int height, const char* title, G
  *  @sa glfwCreateWindow
  *
  *  @par History
- *  Added in GLFW 1.0.
- *
- *  @par
- *  __GLFW 3:__ Renamed from `glfwCloseWindow`.  Added window handle parameter.
+ *  Added in GLFW 3.0.  Replaces `glfwCloseWindow`.
  *
  *  @ingroup window
  */
@@ -1799,15 +1791,16 @@ GLFWAPI void glfwGetWindowPos(GLFWwindow* window, int* xpos, int* ypos);
  *  corner of the client area of the specified windowed mode window.  If the
  *  window is a full screen window, this function does nothing.
  *
+ *  __Do not use this function__ to move an already visible window unless you
+ *  have very good reasons for doing so, as it will confuse and annoy the user.
+ *
+ *  The window manager may put limits on what positions are allowed.  GLFW
+ *  cannot and should not override these limits.
+ *
  *  @param[in] window The window to query.
  *  @param[in] xpos The x-coordinate of the upper-left corner of the client area.
  *  @param[in] ypos The y-coordinate of the upper-left corner of the client area.
  *
- *  @note It is very rarely a good idea to move an already visible window, as it
- *  will confuse and annoy the user.
- *
- *  @note The window manager may put limits on what positions are allowed.
- *
  *  @par Thread Safety
  *  This function may only be called from the main thread.
  *
@@ -1828,7 +1821,7 @@ GLFWAPI void glfwSetWindowPos(GLFWwindow* window, int xpos, int ypos);
  *
  *  This function retrieves the size, in screen coordinates, of the client area
  *  of the specified window.  If you wish to retrieve the size of the
- *  framebuffer in pixels, see @ref glfwGetFramebufferSize.
+ *  framebuffer of the window in pixels, see @ref glfwGetFramebufferSize.
  *
  *  Any or all of the size arguments may be `NULL`.  If an error occurs, all
  *  non-`NULL` size arguments will be set to zero.
@@ -1865,12 +1858,13 @@ GLFWAPI void glfwGetWindowSize(GLFWwindow* window, int* width, int* height);
  *  the context is unaffected, the bit depths of the framebuffer remain
  *  unchanged.
  *
+ *  The window manager may put limits on what sizes are allowed.  GLFW cannot
+ *  and should not override these limits.
+ *
  *  @param[in] window The window to resize.
  *  @param[in] width The desired width of the specified window.
  *  @param[in] height The desired height of the specified window.
  *
- *  @note The window manager may put limits on what window sizes are allowed.
- *
  *  @par Thread Safety
  *  This function may only be called from the main thread.
  *
@@ -2084,11 +2078,7 @@ GLFWAPI GLFWmonitor* glfwGetWindowMonitor(GLFWwindow* window);
  *  @sa @ref window_attribs
  *
  *  @par History
- *  Added in GLFW 1.0.
- *
- *  @par
- *  __GLFW 3:__ Renamed from `glfwGetWindowParam`.  Added window handle
- *  parameter.
+ *  Added in GLFW 3.0.  Replaces `glfwGetWindowParam` and `glfwGetGLVersion`.
  *
  *  @ingroup window
  */
@@ -2156,9 +2146,6 @@ GLFWAPI void* glfwGetWindowUserPointer(GLFWwindow* window);
  *  @par History
  *  Added in GLFW 3.0.
  *
- *  @par
- *  __GLFW 3:__ Added window handle parameter.  Updated callback signature.
- *
  *  @ingroup window
  */
 GLFWAPI GLFWwindowposfun glfwSetWindowPosCallback(GLFWwindow* window, GLFWwindowposfun cbfun);
@@ -2360,9 +2347,6 @@ GLFWAPI GLFWframebuffersizefun glfwSetFramebufferSizeCallback(GLFWwindow* window
  *  @par History
  *  Added in GLFW 1.0.
  *
- *  @par
- *  __GLFW 3:__ This function is no longer called by @ref glfwSwapBuffers.
- *
  *  @ingroup window
  */
 GLFWAPI void glfwPollEvents(void);
@@ -2498,7 +2482,7 @@ GLFWAPI int glfwGetInputMode(GLFWwindow* window, int mode);
  *  @sa glfwGetInputMode
  *
  *  @par History
- *  Added in GLFW 3.0.  Replaced `glfwEnable` and `glfwDisable`.
+ *  Added in GLFW 3.0.  Replaces `glfwEnable` and `glfwDisable`.
  *
  *  @ingroup input
  */
@@ -2548,8 +2532,7 @@ GLFWAPI int glfwGetKey(GLFWwindow* window, int key);
  *
  *  This function returns the last state reported for the specified mouse button
  *  to the specified window.  The returned state is one of `GLFW_PRESS` or
- *  `GLFW_RELEASE`.  The higher-level action `GLFW_REPEAT` is only reported to
- *  the mouse button callback.
+ *  `GLFW_RELEASE`.
  *
  *  If the `GLFW_STICKY_MOUSE_BUTTONS` input mode is enabled, this function
  *  `GLFW_PRESS` the first time you call it for a mouse button that was pressed,
@@ -2605,11 +2588,7 @@ GLFWAPI int glfwGetMouseButton(GLFWwindow* window, int button);
  *  @sa glfwSetCursorPos
  *
  *  @par History
- *  Added in GLFW 1.0.
- *
- *  @par
- *  __GLFW 3:__ Renamed from `glfwGetMousePos`.  Added window handle parameter.
- *  Moved to floating-point coordinates.
+ *  Added in GLFW 3.0.  Replaces `glfwGetMousePos`.
  *
  *  @ingroup input
  */
@@ -2649,11 +2628,7 @@ GLFWAPI void glfwGetCursorPos(GLFWwindow* window, double* xpos, double* ypos);
  *  @sa glfwGetCursorPos
  *
  *  @par History
- *  Added in GLFW 1.0.
- *
- *  @par
- *  __GLFW 3:__ Renamed from `glfwSetMousePos`.  Added window handle parameter.
- *  Moved to floating-point coordinates.
+ *  Added in GLFW 3.0.  Replaces `glfwSetMousePos`.
  *
  *  @ingroup input
  */
@@ -2778,9 +2753,8 @@ GLFWAPI void glfwSetCursor(GLFWwindow* window, GLFWcursor* cursor);
  *
  *  When a window loses focus, it will generate synthetic key release events
  *  for all pressed keys.  You can tell these events from user-generated events
- *  by the fact that the synthetic ones are generated after the window has lost
- *  focus, i.e. `GLFW_FOCUSED` will be false and the focus callback will have
- *  already been called.
+ *  by the fact that the synthetic ones are generated after the focus loss event
+ *  has been processed, i.e. after the focus callback has been called.
  *
  *  The scancode of a key is specific to that platform or sometimes even to that
  *  machine.  Scancodes are intended to allow users to bind keys that don't have
@@ -2892,8 +2866,8 @@ GLFWAPI GLFWcharmodsfun glfwSetCharModsCallback(GLFWwindow* window, GLFWcharmods
  *  When a window loses focus, it will generate synthetic mouse button release
  *  events for all pressed mouse buttons.  You can tell these events from
  *  user-generated events by the fact that the synthetic ones are generated
- *  after the window has lost focus, i.e. `GLFW_FOCUSED` will be false and the
- *  focus callback will have already been called.
+ *  after the focus loss event has been processed, i.e. after the focus callback
+ *  has been called.
  *
  *  @param[in] window The window whose callback to set.
  *  @param[in] cbfun The new callback, or `NULL` to remove the currently set
@@ -2935,11 +2909,7 @@ GLFWAPI GLFWmousebuttonfun glfwSetMouseButtonCallback(GLFWwindow* window, GLFWmo
  *  @sa @ref input_cursor_pos
  *
  *  @par History
- *  Added in GLFW 1.0.
- *
- *  @par
- *  __GLFW 3:__ Renamed from `glfwSetMousePosCallback`. Added window handle
- *  parameter.  Updated callback signature.
+ *  Added in GLFW 3.0.  Replaces `glfwSetMousePosCallback`.
  *
  *  @ingroup input
  */
@@ -2990,11 +2960,7 @@ GLFWAPI GLFWcursorenterfun glfwSetCursorEnterCallback(GLFWwindow* window, GLFWcu
  *  @sa @ref input_scroll
  *
  *  @par History
- *  Added in GLFW 2.1.
- *
- *  @par
- *  __GLFW 3:__ Renamed from `glfwSetMouseWheelCallback`.  Added window handle.
- *  Updated callback signature.
+ *  Added in GLFW 3.0.  Replaces `glfwSetMouseWheelCallback`.
  *
  *  @ingroup input
  */
@@ -3041,7 +3007,7 @@ GLFWAPI GLFWdropfun glfwSetDropCallback(GLFWwindow* window, GLFWdropfun cbfun);
  *  @sa @ref input_joy
  *
  *  @par History
- *  Added in GLFW 3.0.  Replaced `glfwGetJoystickParam`.
+ *  Added in GLFW 3.0.  Replaces `glfwGetJoystickParam`.
  *
  *  @ingroup input
  */
@@ -3068,11 +3034,7 @@ GLFWAPI int glfwJoystickPresent(int joy);
  *  @sa @ref input_joy_axis
  *
  *  @par History
- *  Added in GLFW 2.2.
- *
- *  @par
- *  __GLFW 3:__ Renamed from `glfwGetJoystickPos`.  Changed to return a dynamic
- *  array.
+ *  Added in GLFW 3.0.  Replaces `glfwGetJoystickPos`.
  *
  *  @ingroup input
  */
@@ -3242,7 +3204,7 @@ GLFWAPI void glfwSetTime(double time);
  *  By default, making a context non-current implicitly forces a pipeline flush.
  *  On machines that support `GL_KHR_context_flush_control`, you can control
  *  whether a context performs this flush by setting the
- *  `GLFW_CONTEXT_RELEASE_BEHAVIOR` [window hint](@ref window_hints_ctx).
+ *  [GLFW_CONTEXT_RELEASE_BEHAVIOR](@ref window_hints_ctx) window hint.
  *
  *  @param[in] window The window whose context to make current, or `NULL` to
  *  detach the current context.
@@ -3299,8 +3261,7 @@ GLFWAPI GLFWwindow* glfwGetCurrentContext(void);
  *  Added in GLFW 1.0.
  *
  *  @par
- *  __GLFW 3:__ Added window handle parameter.  Removed call to @ref
- *  glfwPollEvents.
+ *  __GLFW 3:__ Added window handle parameter.
  *
  *  @ingroup window
  */
@@ -3322,7 +3283,7 @@ GLFWAPI void glfwSwapBuffers(GLFWwindow* window);
  *  extension specifications.
  *
  *  A context must be current on the calling thread.  Calling this function
- *  without a current context will cause a `GLFW_NO_CURRENT_CONTEXT` error.
+ *  without a current context will cause a @ref GLFW_NO_CURRENT_CONTEXT error.
  *
  *  @param[in] interval The minimum number of screen updates to wait for
  *  until the buffers are swapped by @ref glfwSwapBuffers.
@@ -3357,7 +3318,7 @@ GLFWAPI void glfwSwapInterval(int interval);
  *  platform-specific context creation API extensions.
  *
  *  A context must be current on the calling thread.  Calling this function
- *  without a current context will cause a `GLFW_NO_CURRENT_CONTEXT` error.
+ *  without a current context will cause a @ref GLFW_NO_CURRENT_CONTEXT error.
  *
  *  As this functions retrieves and searches one or more extension strings each
  *  call, it is recommended that you cache its results if it is going to be used
@@ -3388,7 +3349,7 @@ GLFWAPI int glfwExtensionSupported(const char* extension);
  *  by the current context.
  *
  *  A context must be current on the calling thread.  Calling this function
- *  without a current context will cause a `GLFW_NO_CURRENT_CONTEXT` error.
+ *  without a current context will cause a @ref GLFW_NO_CURRENT_CONTEXT error.
  *
  *  @param[in] procname The ASCII encoded name of the function.
  *  @return The address of the function, or `NULL` if the function is

include/GLFW/glfw3native.h

@@ -40,9 +40,9 @@ extern "C" {
 
 /*! @defgroup native Native access
  *
- *  **By using the native API, you assert that you know what you're doing and
- *  how to fix problems caused by using it.  If you don't, you shouldn't be
- *  using it.**
+ *  **By using the native access functions you assert that you know what you're
+ *  doing and how to fix problems caused by using them.  If you don't, you
+ *  shouldn't be using them.**
  *
  *  Before the inclusion of @ref glfw3native.h, you must define exactly one
  *  window system API macro and exactly one context creation API macro.  Failure
@@ -87,7 +87,7 @@ extern "C" {
  #include <X11/Xlib.h>
  #include <X11/extensions/Xrandr.h>
 #else
- #error "No window API specified"
+ #error "No window API selected"
 #endif
 
 #if defined(GLFW_EXPOSE_NATIVE_WGL)
@@ -99,7 +99,7 @@ extern "C" {
 #elif defined(GLFW_EXPOSE_NATIVE_EGL)
  #include <EGL/egl.h>
 #else
- #error "No context API specified"
+ #error "No context API selected"
 #endif
 
 

src/monitor.c

@@ -321,21 +321,21 @@ GLFWAPI void glfwGetMonitorPos(GLFWmonitor* handle, int* xpos, int* ypos)
     _glfwPlatformGetMonitorPos(monitor, xpos, ypos);
 }
 
-GLFWAPI void glfwGetMonitorPhysicalSize(GLFWmonitor* handle, int* width, int* height)
+GLFWAPI void glfwGetMonitorPhysicalSize(GLFWmonitor* handle, int* widthMM, int* heightMM)
 {
     _GLFWmonitor* monitor = (_GLFWmonitor*) handle;
 
-    if (width)
-        *width = 0;
-    if (height)
-        *height = 0;
+    if (widthMM)
+        *widthMM = 0;
+    if (heightMM)
+        *heightMM = 0;
 
     _GLFW_REQUIRE_INIT();
 
-    if (width)
-        *width = monitor->widthMM;
-    if (height)
-        *height = monitor->heightMM;
+    if (widthMM)
+        *widthMM = monitor->widthMM;
+    if (heightMM)
+        *heightMM = monitor->heightMM;
 }
 
 GLFWAPI const char* glfwGetMonitorName(GLFWmonitor* handle)