diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in
index eb11421a..df840421 100644
--- a/docs/Doxyfile.in
+++ b/docs/Doxyfile.in
@@ -468,14 +468,14 @@ INLINE_INFO            = YES
 # alphabetically by member name. If set to NO the members will appear in
 # declaration order.
 
-SORT_MEMBER_DOCS       = YES
+SORT_MEMBER_DOCS       = NO
 
 # If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the
 # brief documentation of file, namespace and class members alphabetically
 # by member name. If set to NO (the default) the members will appear in
 # declaration order.
 
-SORT_BRIEF_DOCS        = NO
+SORT_BRIEF_DOCS        = YES
 
 # If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen
 # will sort the (brief and detailed) documentation of class members so that
diff --git a/docs/build.dox b/docs/build.dox
index 05c08614..c1584e41 100644
--- a/docs/build.dox
+++ b/docs/build.dox
@@ -49,7 +49,7 @@ In other words:
 
 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 @ref GLFW_INCLUDE_NONE macro
 (described below) should be defined.
 
 
@@ -58,30 +58,37 @@ either be included _before_ the GLFW one, or the `GLFW_INCLUDE_NONE` macro
 These macros may be defined before the inclusion of the GLFW header and affect
 its behavior.
 
-`GLFW_DLL` is required on Windows when using the GLFW DLL, to tell the compiler
-that the GLFW functions are defined in a DLL.
+@anchor GLFW_DLL
+__GLFW_DLL__ is required on Windows when using the GLFW DLL, to tell the
+compiler that the GLFW functions are defined in a DLL.
 
 The following macros control which OpenGL or OpenGL ES API header is included.
 Only one of these may be defined at a time.
 
-`GLFW_INCLUDE_GLCOREARB` makes the GLFW header include the modern
+@anchor GLFW_INCLUDE_GLCOREARB
+__GLFW_INCLUDE_GLCOREARB__ makes the GLFW header include the modern
 `GL/glcorearb.h` header (`OpenGL/gl3.h` on macOS) instead of the regular OpenGL
 header.
 
-`GLFW_INCLUDE_ES1` makes the GLFW header include the OpenGL ES 1.x `GLES/gl.h`
+@anchor GLFW_INCLUDE_ES1
+__GLFW_INCLUDE_ES1__ makes the GLFW header include the OpenGL ES 1.x `GLES/gl.h`
 header instead of the regular OpenGL header.
 
-`GLFW_INCLUDE_ES2` makes the GLFW header include the OpenGL ES 2.0 `GLES2/gl2.h`
-header instead of the regular OpenGL header.
+@anchor GLFW_INCLUDE_ES2
+__GLFW_INCLUDE_ES2__ makes the GLFW header include the OpenGL ES 2.0
+`GLES2/gl2.h` header instead of the regular OpenGL header.
 
-`GLFW_INCLUDE_ES3` makes the GLFW header include the OpenGL ES 3.0 `GLES3/gl3.h`
-header instead of the regular OpenGL header.
+@anchor GLFW_INCLUDE_ES3
+__GLFW_INCLUDE_ES3__ makes the GLFW header include the OpenGL ES 3.0
+`GLES3/gl3.h` header instead of the regular OpenGL header.
 
-`GLFW_INCLUDE_ES31` makes the GLFW header include the OpenGL ES 3.1 `GLES3/gl31.h`
-header instead of the regular OpenGL header.
+@anchor GLFW_INCLUDE_ES31
+__GLFW_INCLUDE_ES31__ makes the GLFW header include the OpenGL ES 3.1
+`GLES3/gl31.h` header instead of the regular OpenGL header.
 
-`GLFW_INCLUDE_NONE` makes the GLFW header not include any OpenGL or OpenGL ES API
-header.  This is useful in combination with an extension loading library.
+@anchor GLFW_INCLUDE_NONE
+__GLFW_INCLUDE_NONE__ makes the GLFW header not include any OpenGL or OpenGL ES
+API 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 macOS) is included.
@@ -90,14 +97,17 @@ The following macros control the inclusion of additional API headers.  Any
 number of these may be defined simultaneously, and/or together with one of the
 above macros.
 
-`GLFW_INCLUDE_VULKAN` makes the GLFW header include the Vulkan `vulkan/vulkan.h`
-header in addition to any selected OpenGL or OpenGL ES header.
+@anchor GLFW_INCLUDE_VULKAN
+__GLFW_INCLUDE_VULKAN__ makes the GLFW header include the Vulkan
+`vulkan/vulkan.h` header in addition to any selected OpenGL or OpenGL ES header.
 
-`GLFW_INCLUDE_GLEXT` makes the GLFW header include the appropriate extension
+@anchor GLFW_INCLUDE_GLEXT
+__GLFW_INCLUDE_GLEXT__ makes the GLFW header include the appropriate extension
 header for the OpenGL or OpenGL ES header selected above after and in addition
 to that header.
 
-`GLFW_INCLUDE_GLU` makes the header include the GLU header in addition to the
+@anchor GLFW_INCLUDE_GLU
+__GLFW_INCLUDE_GLU__ makes the header include the GLU header in addition to the
 header selected above.  This should only be used with the standard OpenGL header
 and only for compatibility with legacy code.  GLU has been deprecated and should
 not be used in new code.
@@ -141,9 +151,9 @@ set of default libraries along with other dependencies like `user32` and
 `kernel32`.  If you are using GLU, you must also link with `glu32`.
 
 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
-a compiler switch or by defining it in your source code.
+application that uses the DLL version of GLFW, you need to define the @ref
+GLFW_DLL 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
 dependencies, but you still have to link against `opengl32` if your application
@@ -178,8 +188,8 @@ add_subdirectory(path/to/glfw)
 
 Once GLFW has been added to the project, link against it with the `glfw` target.
 This adds all link-time dependencies of GLFW as it is currently configured,
-the include directory for the GLFW header and, when applicable, the
-[GLFW_DLL](@ref build_macros) macro.
+the include directory for the GLFW header and, when applicable, the @ref
+GLFW_DLL macro.
 
 @code{.cmake}
 target_link_libraries(myapp glfw)
diff --git a/docs/compile.dox b/docs/compile.dox
index 2b21732a..0e5b3c24 100644
--- a/docs/compile.dox
+++ b/docs/compile.dox
@@ -193,45 +193,56 @@ cmake -DBUILD_SHARED_LIBS=ON .
 
 @subsubsection compile_options_shared Shared CMake options
 
-`BUILD_SHARED_LIBS` determines whether GLFW is built as a static
+@anchor BUILD_SHARED_LIBS
+__BUILD_SHARED_LIBS__ determines whether GLFW is built as a static
 library or as a DLL / shared library / dynamic library.
 
-`LIB_SUFFIX` affects where the GLFW shared /dynamic library is installed.  If it
-is empty, it is installed to `${CMAKE_INSTALL_PREFIX}/lib`.  If it is set to
+@anchor LIB_SUFFIX
+__LIB_SUFFIX__ affects where the GLFW shared /dynamic library is installed.  If
+it is empty, it is installed to `${CMAKE_INSTALL_PREFIX}/lib`.  If it is set to
 `64`, it is installed to `${CMAKE_INSTALL_PREFIX}/lib64`.
 
-`GLFW_BUILD_EXAMPLES` determines whether the GLFW examples are built
+@anchor GLFW_BUILD_EXAMPLES
+__GLFW_BUILD_EXAMPLES__ determines whether the GLFW examples are built
 along with the library.
 
-`GLFW_BUILD_TESTS` determines whether the GLFW test programs are
+@anchor GLFW_BUILD_TESTS
+__GLFW_BUILD_TESTS__ determines whether the GLFW test programs are
 built along with the library.
 
-`GLFW_BUILD_DOCS` determines whether the GLFW documentation is built along with
-the library.
+@anchor GLFW_BUILD_DOCS
+__GLFW_BUILD_DOCS__ determines whether the GLFW documentation is built along
+with the library.
 
-`GLFW_VULKAN_STATIC` determines whether to use the Vulkan loader linked
+@anchor GLFW_VULKAN_STATIC
+__GLFW_VULKAN_STATIC__ determines whether to use the Vulkan loader linked
 statically into the application.
 
 
 @subsubsection compile_options_osx macOS specific CMake options
 
-`GLFW_USE_CHDIR` determines whether `glfwInit` changes the current
+@anchor GLFW_USE_CHDIR
+__GLFW_USE_CHDIR__ determines whether @ref glfwInit changes the current
 directory of bundled applications to the `Contents/Resources` directory.
 
-`GLFW_USE_MENUBAR` determines whether the first call to
-`glfwCreateWindow` sets up a minimal menu bar.
+@anchor GLFW_USE_MENUBAR
+__GLFW_USE_MENUBAR__ determines whether the first call to @ref glfwCreateWindow
+sets up a minimal menu bar.
 
-`GLFW_USE_RETINA` determines whether windows will use the full resolution of
+@anchor GLFW_USE_RETINA
+__GLFW_USE_RETINA__ determines whether windows will use the full resolution of
 Retina displays.
 
 
 @subsubsection compile_options_win32 Windows specific CMake options
 
-`USE_MSVC_RUNTIME_LIBRARY_DLL` determines whether to use the DLL version or the
+@anchor USE_MSVC_RUNTIME_LIBRARY_DLL
+__USE_MSVC_RUNTIME_LIBRARY_DLL__ determines whether to use the DLL version or the
 static library version of the Visual C++ runtime library.  If set to `ON`, the
 DLL version of the Visual C++ library is used.
 
-`GLFW_USE_HYBRID_HPG` determines whether to export the `NvOptimusEnablement` and
+@anchor GLFW_USE_HYBRID_HPG
+__GLFW_USE_HYBRID_HPG__ determines whether to export the `NvOptimusEnablement` and
 `AmdPowerXpressRequestHighPerformance` symbols, which force the use of the
 high-performance GPU on Nvidia Optimus and AMD PowerXpress systems.  These symbols
 need to be exported by the EXE to be detected by the driver, so the override
@@ -248,46 +259,46 @@ features.
 
 When building with CMake, the `glfw_config.h` configuration header is generated
 based on the current platform and CMake options.  The GLFW CMake environment
-defines `_GLFW_USE_CONFIG_H`, which causes this header to be included by
+defines @b 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.
 
 The window creation API is used to create windows, handle input, monitors, gamma
 ramps and clipboard.  The options are:
 
- - `_GLFW_COCOA` to use the Cocoa frameworks
- - `_GLFW_WIN32` to use the Win32 API
- - `_GLFW_X11` to use the X Window System
- - `_GLFW_WAYLAND` to use the Wayland API (experimental and incomplete)
- - `_GLFW_MIR` to use the Mir API (experimental and incomplete)
- - `_GLFW_OSMESA` to use the OSMesa API (headless and non-interactive)
+ - @b _GLFW_COCOA to use the Cocoa frameworks
+ - @b _GLFW_WIN32 to use the Win32 API
+ - @b _GLFW_X11 to use the X Window System
+ - @b _GLFW_WAYLAND to use the Wayland API (experimental and incomplete)
+ - @b _GLFW_MIR to use the Mir API (experimental and incomplete)
+ - @b _GLFW_OSMESA to use the OSMesa API (headless and non-interactive)
 
 If you are building GLFW as a shared library / dynamic library / DLL then you
-must also define `_GLFW_BUILD_DLL`.  Otherwise, you must not define it.
+must also define @b _GLFW_BUILD_DLL.  Otherwise, you must not define it.
 
 If you are linking the Vulkan loader statically into your application then you
-must also define `_GLFW_VULKAN_STATIC`.  Otherwise, GLFW will attempt to use the
+must also define @b _GLFW_VULKAN_STATIC.  Otherwise, GLFW will attempt to use the
 external version.
 
 For the EGL context creation API, the following options are available:
 
- - `_GLFW_USE_EGLPLATFORM_H` to use `EGL/eglplatform.h` for native handle
+ - @b _GLFW_USE_EGLPLATFORM_H to use `EGL/eglplatform.h` for native handle
    definitions (fallback)
 
 If you are using the X11 window creation API, support for the following X11
 extensions can be enabled:
 
- - `_GLFW_HAS_XF86VM` to use Xxf86vm as a fallback when RandR gamma is broken
+ - @b _GLFW_HAS_XF86VM to use Xxf86vm as a fallback when RandR gamma is broken
  (recommended)
 
 If you are using the Cocoa window creation API, the following options are
 available:
 
- - `_GLFW_USE_CHDIR` to `chdir` to the `Resources` subdirectory of the
+ - @b _GLFW_USE_CHDIR to `chdir` to the `Resources` subdirectory of the
    application bundle during @ref glfwInit (recommended)
- - `_GLFW_USE_MENUBAR` to create and populate the menu bar when the first window
+ - @b _GLFW_USE_MENUBAR to create and populate the menu bar when the first window
    is created (recommended)
- - `_GLFW_USE_RETINA` to have windows use the full resolution of Retina displays
+ - @b _GLFW_USE_RETINA to have windows use the full resolution of Retina displays
    (recommended)
 
 @note None of the @ref build_macros may be defined during the compilation of
diff --git a/docs/context.dox b/docs/context.dox
index 3f972828..22e6f513 100644
--- a/docs/context.dox
+++ b/docs/context.dox
@@ -30,8 +30,8 @@ the `glfwinfo` test program.
 
 @note Vulkan does not have a context and the Vulkan instance is created via the
 Vulkan API itself.  If you will be using Vulkan to render to a window, disable
-context creation by setting the [GLFW_CLIENT_API](@ref window_hints_ctx) hint to
-`GLFW_NO_API`.  For more information, see the @ref vulkan_guide.
+context creation by setting the [GLFW_CLIENT_API](@ref GLFW_CLIENT_API_hint)
+hint to `GLFW_NO_API`.  For more information, see the @ref vulkan_guide.
 
 
 @subsection context_hints Context creation hints
@@ -68,7 +68,7 @@ GLFW comes with a simple object sharing test program called `sharing`.
 
 GLFW doesn't support creating contexts without an associated window.  However,
 contexts with hidden windows can be created with the
-[GLFW_VISIBLE](@ref window_hints_wnd) window hint.
+[GLFW_VISIBLE](@ref GLFW_VISIBLE_hint) window hint.
 
 @code
 glfwWindowHint(GLFW_VISIBLE, GLFW_FALSE);
@@ -93,8 +93,8 @@ disabled with a [compile-time option](@ref compile_options_osx).
 @subsection context_less Windows without contexts
 
 You can disable context creation by setting the
-[GLFW_CLIENT_API](@ref window_hints_ctx) hint to `GLFW_NO_API`.  Windows without
-contexts must not be passed to @ref glfwMakeContextCurrent or @ref
+[GLFW_CLIENT_API](@ref GLFW_CLIENT_API_hint) hint to `GLFW_NO_API`.  Windows
+without contexts must not be passed to @ref glfwMakeContextCurrent or @ref
 glfwSwapBuffers.
 
 
@@ -266,8 +266,8 @@ supports.  These have names like `PFNGLGETDEBUGMESSAGELOGARBPROC` (for
 `glGetDebugMessageLogARB`), i.e. the name is made uppercase and `PFN` (pointer
 to function) and `PROC` (procedure) are added to the ends.
 
-To include the extension header, define [GLFW_INCLUDE_GLEXT](@ref build_macros)
-before including the GLFW header.
+To include the extension header, define @ref GLFW_INCLUDE_GLEXT before including
+the GLFW header.
 
 @code
 #define GLFW_INCLUDE_GLEXT
diff --git a/docs/monitor.dox b/docs/monitor.dox
index 0aa0b050..c05f601c 100644
--- a/docs/monitor.dox
+++ b/docs/monitor.dox
@@ -213,4 +213,9 @@ glfwSetGammaRamp with the resulting ramp.
 glfwSetGamma(monitor, 1.0);
 @endcode
 
+@note The software controlled gamma ramp is applied _in addition_ to the
+hardware gamma correction, which today is usually an approximation of sRGB
+gamma.  This means that setting a perfectly linear ramp, or gamma 1.0, will
+produce the default (usually sRGB-like) behavior.
+
 */
diff --git a/docs/moving.dox b/docs/moving.dox
index 7baab6f1..b9a44f01 100644
--- a/docs/moving.dox
+++ b/docs/moving.dox
@@ -434,7 +434,7 @@ 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 not use GLU__, but if you need it for 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.
+defining @ref GLFW_INCLUDE_GLU before the inclusion of the GLFW header.
 
 @par Old syntax
 @code
diff --git a/docs/news.dox b/docs/news.dox
index b0de0daa..ed4555bb 100644
--- a/docs/news.dox
+++ b/docs/news.dox
@@ -19,7 +19,7 @@ GLFW now supports querying the platform dependent scancode of any key with
 @subsection news_33_moltenvk Support for Vulkan on macOS via MoltenVK
 
 GLFW now supports the `VK_MVK_macos_surface` window surface creation extension
-provided by MoltenVK.
+provided by [MoltenVK](https://moltengl.com/moltenvk/).
 
 
 @subsection news_33_osmesa OSMesa backend for headless software rendering
@@ -37,7 +37,7 @@ GLFW now supports basic integration with Vulkan with @ref glfwVulkanSupported,
 @ref glfwGetRequiredInstanceExtensions, @ref glfwGetInstanceProcAddress, @ref
 glfwGetPhysicalDevicePresentationSupport and @ref glfwCreateWindowSurface.
 Vulkan header inclusion can be selected with
-[GLFW_INCLUDE_VULKAN](@ref build_macros).
+@ref GLFW_INCLUDE_VULKAN.
 
 
 @subsection news_32_setwindowmonitor Window mode switching
@@ -50,7 +50,7 @@ the monitor and desired resolution and refresh rate of full screen windows with
 @subsection news_32_maximize Window maxmimization support
 
 GLFW now supports window maximization with @ref glfwMaximizeWindow and the
-[GLFW_MAXIMIZED](@ref window_attribs_wnd) window hint and attribute.
+@ref GLFW_MAXIMIZED window hint and attribute.
 
 
 @subsection news_32_focus Window input focus control
@@ -95,21 +95,21 @@ with @ref glfwSetJoystickCallback.
 
 @subsection news_32_noapi Context-less windows
 
-GLFW now supports creating windows without a OpenGL or OpenGL ES context with
-[GLFW_NO_API](@ref window_hints_ctx).
+GLFW now supports creating windows without a OpenGL or OpenGL ES context by
+setting the [GLFW_CLIENT_API](@ref GLFW_CLIENT_API_hint) hint to `GLFW_NO_API`.
 
 
 @subsection news_32_contextapi Run-time context creation API selection
 
-GLFW now supports selecting the context creation API at run-time with the
-[GLFW_CONTEXT_CREATION_API](@ref window_hints_ctx) window hint value.
+GLFW now supports selecting and querying the context creation API at run-time
+with the @ref GLFW_CONTEXT_CREATION_API hint and attribute.
 
 
 @subsection news_32_noerror Error-free context creation
 
-GLFW now supports creating OpenGL and OpenGL ES contexts that do not emit errors
-with the [GLFW_CONTEXT_NO_ERROR](@ref window_hints_ctx) window hint, provided
-the machine supports the `GL_KHR_no_error` extension.
+GLFW now supports creating and querying OpenGL and OpenGL ES contexts that do
+not emit errors with the @ref GLFW_CONTEXT_NO_ERROR hint, provided the machine
+supports the `GL_KHR_no_error` extension.
 
 
 @subsection news_32_cmake CMake config-file package support
@@ -163,21 +163,21 @@ client area of a window, with @ref glfwGetWindowFrameSize.
 @subsection news_31_autoiconify Simultaneous multi-monitor rendering
 
 GLFW now supports disabling auto-iconification of full screen windows with
-the [GLFW_AUTO_ICONIFY](@ref window_hints_wnd) window hint.  This is intended
-for people building multi-monitor installations, where you need windows to stay
-in full screen despite losing input focus.
+the [GLFW_AUTO_ICONIFY](@ref GLFW_AUTO_ICONIFY_hint) window hint.  This is
+intended for people building multi-monitor installations, where you need windows
+to stay in full screen despite losing input focus.
 
 
 @subsection news_31_floating Floating windows
 
 GLFW now supports floating windows, also called topmost or always on top, for
-easier debugging with the [GLFW_FLOATING](@ref window_hints_wnd) window hint.
+easier debugging with the @ref GLFW_FLOATING window hint and attribute.
 
 
 @subsection news_31_focused Initially unfocused windows
 
 GLFW now supports preventing a windowed mode window from gaining input focus on
-creation, with the [GLFW_FOCUSED](@ref window_hints_wnd) window hint.
+creation, with the [GLFW_FOCUSED](@ref GLFW_FOCUSED_hint) window hint.
 
 
 @subsection news_31_direct Direct access for window attributes and cursor position
@@ -198,24 +198,24 @@ being input, for example if the Control key is held down.
 
 @subsection news_31_single Single buffered framebuffers
 
-GLFW now supports the creation of single buffered windows, with the
-[GLFW_DOUBLEBUFFER](@ref window_hints_fb) window hint.
+GLFW now supports the creation of single buffered windows, with the @ref
+GLFW_DOUBLEBUFFER hint.
 
 
 @subsection news_31_glext Macro for including extension header
 
 GLFW now includes the extension header appropriate for the chosen OpenGL or
-OpenGL ES header when [GLFW_INCLUDE_GLEXT](@ref build_macros) is defined.  GLFW
-does not provide these headers.  They must be provided by your development
-environment or your OpenGL or OpenGL ES SDK.
+OpenGL ES header when @ref GLFW_INCLUDE_GLEXT is defined.  GLFW does not provide
+these headers.  They must be provided by your development environment or your
+OpenGL or OpenGL ES SDK.
 
 
 @subsection news_31_release Context release behaviors
 
-GLFW now supports controlling whether the pipeline is flushed when a context is
-made non-current, with the
-[GLFW_CONTEXT_RELEASE_BEHAVIOR](@ref window_hints_ctx) window hint, provided the
-machine supports the `GL_KHR_context_flush_control` extension.
+GLFW now supports controlling and querying whether the pipeline is flushed when
+a context is made non-current, with the @ref GLFW_CONTEXT_RELEASE_BEHAVIOR hint
+and attribute, provided the machine supports the `GL_KHR_context_flush_control`
+extension.
 
 
 @subsection news_31_wayland (Experimental) Wayland support
@@ -290,11 +290,11 @@ glfwSetGamma, which generates a ramp from a gamma value and then sets it.
 @subsection news_30_gles OpenGL ES support
 
 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
-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.
+[GLFW_CLIENT_API](@ref GLFW_CLIENT_API_hint) hint to `GLFW_OPENGL_ES_API`, where
+creation of such 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.
 
 
 @subsection news_30_egl (Experimental) EGL support
@@ -365,16 +365,17 @@ to @ref glfwCreateWindow.
 @subsection news_30_hidden Hidden windows
 
 Windows can now be hidden with @ref glfwHideWindow, shown using @ref
-glfwShowWindow and created initially hidden with the `GLFW_VISIBLE` window hint.
-This allows for off-screen rendering in a way compatible with most drivers, as
-well as moving a window to a specific position before showing it.
+glfwShowWindow and created initially hidden with the @ref GLFW_VISIBLE window
+hint and attribute.  This allows for off-screen rendering in a way compatible
+with most drivers, as well as moving a window to a specific position before
+showing it.
 
 
 @subsection news_30_undecorated Undecorated windows
 
 Windowed mode windows can now be created without decorations, e.g. things like
-a frame, a title bar, with the `GLFW_DECORATED` window hint.  This allows for
-the creation of things like splash screens.
+a frame, a title bar, with the @ref GLFW_DECORATED window hint and attribute.
+This allows for the creation of things like splash screens.
 
 
 @subsection news_30_keymods Modifier key bit masks
diff --git a/docs/vulkan.dox b/docs/vulkan.dox
index 32b96463..4ecdafde 100644
--- a/docs/vulkan.dox
+++ b/docs/vulkan.dox
@@ -38,22 +38,21 @@ Unix-like systems).  This means that GLFW does not need to be linked against the
 loader.  However, it also means that if you are using the static library form of
 the Vulkan loader GLFW will either fail to find it or (worse) use the wrong one.
 
-The [GLFW_VULKAN_STATIC](@ref compile_options_shared) CMake option makes GLFW
-link directly against the static form.  Not linking against the Vulkan loader
-will then be a compile-time error.
+The @ref GLFW_VULKAN_STATIC CMake option makes GLFW link directly against the
+static form.  Not linking against the Vulkan loader will then be a compile-time
+error.
 
 @macos MoltenVK only provides the static library form of the Vulkan loader, but
-GLFW is able to find it without
-[GLFW_VULKAN_STATIC](@ref compile_options_shared) as long as it is linked into
-any of the binaries already loaded into the process.  As it is a static library,
-you must also link against its dependencies: the `Cocoa`, `Metal` and
+GLFW is able to find it without @ref GLFW_VULKAN_STATIC as long as it is linked
+into any of the binaries already loaded into the process.  As it is a static
+library, you must also link against its dependencies: the `Cocoa`, `Metal` and
 `QuartzCore` frameworks and the `libc++` library.
 
 
 @section vulkan_include Including the Vulkan and GLFW header files
 
-To include the Vulkan header, define [GLFW_INCLUDE_VULKAN](@ref build_macros)
-before including the GLFW header.
+To include the Vulkan header, define @ref GLFW_INCLUDE_VULKAN before including
+the GLFW header.
 
 @code
 #define GLFW_INCLUDE_VULKAN
@@ -203,7 +202,7 @@ an existing Vulkan surface.
 
 Unless you will be using OpenGL or OpenGL ES with the same window as Vulkan,
 there is no need to create a context.  You can disable context creation with the
-[GLFW_CLIENT_API](@ref window_hints_ctx) hint.
+[GLFW_CLIENT_API](@ref GLFW_CLIENT_API_hint) hint.
 
 @code
 glfwWindowHint(GLFW_CLIENT_API, GLFW_NO_API);
diff --git a/docs/window.dox b/docs/window.dox
index 026298e2..8f7f85ac 100644
--- a/docs/window.dox
+++ b/docs/window.dox
@@ -71,10 +71,10 @@ 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
+GLFWvidmode.redBits     | @ref GLFW_RED_BITS hint
+GLFWvidmode.greenBits   | @ref GLFW_GREEN_BITS hint
+GLFWvidmode.blueBits    | @ref GLFW_BLUE_BITS hint
+GLFWvidmode.refreshRate | @ref GLFW_REFRESH_RATE hint
 
 Once you have a full screen window, you can change its resolution, refresh rate
 and monitor with @ref glfwSetWindowMonitor.  If you just need change its
@@ -85,9 +85,9 @@ unaffected.
 
 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 behavior can be disabled with the `GLFW_AUTO_ICONIFY` window
-hint, for example if you wish to simultaneously cover multiple windows with full
-screen windows.
+the desktop.  This behavior can be disabled with the
+[GLFW_AUTO_ICONIFY](@ref GLFW_AUTO_ICONIFY_hint) window hint, for example if you
+wish to simultaneously cover multiple windows with full screen windows.
 
 
 @subsubsection window_windowed_full_screen "Windowed full screen" windows
@@ -158,102 +158,128 @@ that are not hard constraints are matched as closely as possible, but the
 resulting context and framebuffer may differ from what these hints requested.
 
 The following hints are always hard constraints:
-- `GLFW_STEREO`
-- `GLFW_DOUBLEBUFFER`
-- `GLFW_CLIENT_API`
-- `GLFW_CONTEXT_CREATION_API`
+- @ref GLFW_STEREO
+- @ref GLFW_DOUBLEBUFFER
+- [GLFW_CLIENT_API](@ref GLFW_CLIENT_API_hint)
+- [GLFW_CONTEXT_CREATION_API](@ref GLFW_CONTEXT_CREATION_API_hint)
 
 The following additional hints are hard constraints when requesting an OpenGL
 context, but are ignored when requesting an OpenGL ES context:
-- `GLFW_OPENGL_FORWARD_COMPAT`
-- `GLFW_OPENGL_PROFILE`
+- [GLFW_OPENGL_FORWARD_COMPAT](@ref GLFW_OPENGL_FORWARD_COMPAT_hint)
+- [GLFW_OPENGL_PROFILE](@ref GLFW_OPENGL_PROFILE_hint)
 
 
 @subsubsection window_hints_wnd Window related hints
 
-`GLFW_RESIZABLE` specifies whether the windowed mode window will be resizable
+@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.
 
-`GLFW_VISIBLE` specifies whether the windowed mode window will be initially
+@anchor GLFW_VISIBLE_hint
+__GLFW_VISIBLE__ specifies whether the windowed mode window will be initially
 visible.  This hint is ignored for full screen windows.
 
-`GLFW_DECORATED` specifies whether the windowed mode window will have window
+@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.
 
-`GLFW_FOCUSED` specifies whether the windowed mode window will be given input
+@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.
 
-`GLFW_AUTO_ICONIFY` specifies whether the full screen window will
+@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.
 
-`GLFW_FLOATING` specifies whether the windowed mode window will be floating
+@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.
 
-`GLFW_MAXIMIZED` specifies whether the windowed mode window will be maximized
+@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.
 
 
 @subsubsection window_hints_fb Framebuffer related hints
 
-`GLFW_RED_BITS`, `GLFW_GREEN_BITS`, `GLFW_BLUE_BITS`, `GLFW_ALPHA_BITS`,
-`GLFW_DEPTH_BITS` and `GLFW_STENCIL_BITS` specify the desired bit depths of the
-various components of the default framebuffer.  `GLFW_DONT_CARE` means the
-application has no preference.
+@anchor GLFW_RED_BITS
+@anchor GLFW_GREEN_BITS
+@anchor GLFW_BLUE_BITS
+@anchor GLFW_ALPHA_BITS
+@anchor GLFW_DEPTH_BITS
+@anchor GLFW_STENCIL_BITS
+__GLFW_RED_BITS__, __GLFW_GREEN_BITS__, __GLFW_BLUE_BITS__, __GLFW_ALPHA_BITS__,
+__GLFW_DEPTH_BITS__ and __GLFW_STENCIL_BITS__ specify the desired bit depths of
+the various components of the default framebuffer.  A value of `GLFW_DONT_CARE`
+means the application has no preference.
 
-`GLFW_ACCUM_RED_BITS`, `GLFW_ACCUM_GREEN_BITS`, `GLFW_ACCUM_BLUE_BITS` and
-`GLFW_ACCUM_ALPHA_BITS` specify the desired bit depths of the various components
-of the accumulation buffer.  `GLFW_DONT_CARE` means the application has no
-preference.
+@anchor GLFW_ACCUM_RED_BITS
+@anchor GLFW_ACCUM_GREEN_BITS
+@anchor GLFW_ACCUM_BLUE_BITS
+@anchor GLFW_ACCUM_ALPHA_BITS
+__GLFW_ACCUM_RED_BITS__, __GLFW_ACCUM_GREEN_BITS__, __GLFW_ACCUM_BLUE_BITS__ and
+__GLFW_ACCUM_ALPHA_BITS__ specify the desired bit depths of the various
+components of the accumulation buffer.  A value of `GLFW_DONT_CARE` means the
+application has no preference.
 
 @par
 Accumulation buffers are a legacy OpenGL feature and should not be used in new
 code.
 
-`GLFW_AUX_BUFFERS` specifies the desired number of auxiliary buffers.
-`GLFW_DONT_CARE` means the application has no preference.
+@anchor GLFW_AUX_BUFFERS
+__GLFW_AUX_BUFFERS__ specifies the desired number of auxiliary buffers.  A value
+of `GLFW_DONT_CARE` means the application has no preference.
 
 @par
 Auxiliary buffers are a legacy OpenGL feature and should not be used in new
 code.
 
-`GLFW_STEREO` specifies whether to use stereoscopic rendering.  This is a hard
-constraint.
+@anchor GLFW_STEREO
+__GLFW_STEREO__ specifies whether to use OpenGL stereoscopic rendering.  This is
+a hard constraint.
 
-`GLFW_SAMPLES` specifies the desired number of samples to use for multisampling.
-Zero disables multisampling.  `GLFW_DONT_CARE` means the application has no
-preference.
+@anchor GLFW_SAMPLES
+__GLFW_SAMPLES__ specifies the desired number of samples to use for
+multisampling.  Zero disables multisampling.  A value of `GLFW_DONT_CARE` means
+the application has no preference.
 
-`GLFW_SRGB_CAPABLE` specifies whether the framebuffer should be sRGB capable.
+@anchor GLFW_SRGB_CAPABLE
+__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.
 
-`GLFW_DOUBLEBUFFER` specifies whether the framebuffer should be double buffered.
-You nearly always want to use double buffering.  This is a hard constraint.
+@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.
 
 
 @subsubsection window_hints_mtr Monitor related hints
 
-`GLFW_REFRESH_RATE` specifies the desired refresh rate for full screen windows.
-If set to `GLFW_DONT_CARE`, the highest available refresh rate will be used.
-This hint is ignored for windowed mode windows.
+@anchor GLFW_REFRESH_RATE
+__GLFW_REFRESH_RATE__ specifies the desired refresh rate for full screen
+windows.  A value of `GLFW_DONT_CARE` means the highest available refresh rate
+will be used.  This hint is ignored for windowed mode windows.
 
 
 @subsubsection window_hints_ctx Context related hints
 
-`GLFW_CLIENT_API` specifies which client API to create the context for.
+@anchor GLFW_CLIENT_API_hint
+__GLFW_CLIENT_API__ specifies which client API to create the context for.
 Possible values are `GLFW_OPENGL_API`, `GLFW_OPENGL_ES_API` and `GLFW_NO_API`.
 This is a hard constraint.
 
-`GLFW_CONTEXT_CREATION_API` specifies which context creation API to use to
+@anchor GLFW_CONTEXT_CREATION_API_hint
+__GLFW_CONTEXT_CREATION_API__ specifies which context creation API to use to
 create the context.  Possible values are `GLFW_NATIVE_CONTEXT_API` and
 `GLFW_EGL_CONTEXT_API`.  This is a hard constraint.  If no client API is
 requested, this hint is ignored.
@@ -275,16 +301,18 @@ the selected API.
 in a single process will cause the application to segfault.  Stick to one API or
 the other on Linux for now.
 
-`GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` specify the client
-API version that the created context must be compatible with.  The exact
+@anchor GLFW_CONTEXT_VERSION_MAJOR_hint
+@anchor GLFW_CONTEXT_VERSION_MINOR_hint
+__GLFW_CONTEXT_VERSION_MAJOR__ and __GLFW_CONTEXT_VERSION_MINOR__ specify the
+client API version that the created context must be compatible with.  The exact
 behavior of these hints depend on the requested client API.
 
 @par
-__OpenGL:__ `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` are
-not hard constraints, but creation will fail if the OpenGL version of the
-created context is less than the one requested.  It is therefore perfectly safe
-to use the default of version 1.0 for legacy code and you will still get
-backwards-compatible contexts of version 3.0 and above when available.
+__OpenGL:__ These hints are not hard constraints, but creation will fail if the
+OpenGL version of the created context is less than the one requested.  It is
+therefore perfectly safe to use the default of version 1.0 for legacy code and
+you will still get backwards-compatible contexts of version 3.0 and above when
+available.
 
 @par
 While there is no way to ask the driver for a context of the highest supported
@@ -292,21 +320,21 @@ version, GLFW will attempt to provide this when you ask for a version 1.0
 context, which is the default for these hints.
 
 @par
-__OpenGL ES:__ `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` are
-not hard constraints, but creation will fail if the OpenGL ES version of the
-created context is less than the one requested.  Additionally, OpenGL ES 1.x
-cannot be returned if 2.0 or later was requested, and vice versa.  This is
-because OpenGL ES 3.x is backward compatible with 2.0, but OpenGL ES 2.0 is not
-backward compatible with 1.x.
+__OpenGL ES:__ These hints are not hard constraints, but creation will fail if
+the OpenGL ES version of the created context is less than the one requested.
+Additionally, OpenGL ES 1.x cannot be returned if 2.0 or later was requested,
+and vice versa.  This is because OpenGL ES 3.x is backward compatible with 2.0,
+but OpenGL ES 2.0 is not backward compatible with 1.x.
 
 @note @macos The OS only supports forward-compatible core profile contexts for
 OpenGL versions 3.2 and later.  Before creating an OpenGL context of version
-3.2 or later you must set the `GLFW_OPENGL_FORWARD_COMPAT` and
-`GLFW_OPENGL_PROFILE` hints accordingly.  OpenGL 3.0 and 3.1 contexts are not
-supported at all on macOS.
+3.2 or later you must set the
+[GLFW_OPENGL_FORWARD_COMPAT](@ref GLFW_OPENGL_FORWARD_COMPAT_hint) and
+[GLFW_OPENGL_PROFILE](@ref GLFW_OPENGL_PROFILE_hint) hints accordingly.  OpenGL
+3.0 and 3.1 contexts are not supported at all on macOS.
 
-
-`GLFW_OPENGL_FORWARD_COMPAT` specifies whether the OpenGL context should be
+@anchor GLFW_OPENGL_FORWARD_COMPAT_hint
+__GLFW_OPENGL_FORWARD_COMPAT__ specifies whether the OpenGL context should be
 forward-compatible, i.e. one where all functionality deprecated in the requested
 version of OpenGL is removed.  This must only be used if the requested OpenGL
 version is 3.0 or above.  If OpenGL ES is requested, this hint is ignored.
@@ -315,27 +343,31 @@ version is 3.0 or above.  If OpenGL ES is requested, this hint is ignored.
 Forward-compatibility is described in detail in the
 [OpenGL Reference Manual](https://www.opengl.org/registry/).
 
-`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.
+@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.
 
-`GLFW_OPENGL_PROFILE` specifies which OpenGL profile to create the context for.
-Possible values are one of `GLFW_OPENGL_CORE_PROFILE` or
+@anchor GLFW_OPENGL_PROFILE_hint
+__GLFW_OPENGL_PROFILE__ specifies which OpenGL profile to create the context
+for.  Possible values are one of `GLFW_OPENGL_CORE_PROFILE` or
 `GLFW_OPENGL_COMPAT_PROFILE`, or `GLFW_OPENGL_ANY_PROFILE` to not request
 a specific profile.  If requesting an OpenGL version below 3.2,
-`GLFW_OPENGL_ANY_PROFILE` must be used.  If OpenGL ES is requested,
-this hint is ignored.
+`GLFW_OPENGL_ANY_PROFILE` must be used.  If OpenGL ES is requested, this hint
+is ignored.
 
 @par
 OpenGL profiles are described in detail in the
 [OpenGL Reference Manual](https://www.opengl.org/registry/).
 
-`GLFW_CONTEXT_ROBUSTNESS` specifies the robustness strategy to be used by the
+@anchor GLFW_CONTEXT_ROBUSTNESS_hint
+__GLFW_CONTEXT_ROBUSTNESS__ specifies the robustness strategy to be used by the
 context.  This can be one of `GLFW_NO_RESET_NOTIFICATION` or
 `GLFW_LOSE_CONTEXT_ON_RESET`, or `GLFW_NO_ROBUSTNESS` to not request
 a robustness strategy.
 
-`GLFW_CONTEXT_RELEASE_BEHAVIOR` specifies the release behavior to be
+@anchor GLFW_CONTEXT_RELEASE_BEHAVIOR_hint
+__GLFW_CONTEXT_RELEASE_BEHAVIOR__ specifies the release behavior to be
 used by the context.  Possible values are one of `GLFW_ANY_RELEASE_BEHAVIOR`,
 `GLFW_RELEASE_BEHAVIOR_FLUSH` or `GLFW_RELEASE_BEHAVIOR_NONE`.  If the
 behavior is `GLFW_ANY_RELEASE_BEHAVIOR`, the default behavior of the context
@@ -349,7 +381,8 @@ Context release behaviors are described in detail by the
 [GL_KHR_context_flush_control](https://www.opengl.org/registry/specs/KHR/context_flush_control.txt)
 extension.
 
-`GLFW_CONTEXT_NO_ERROR` specifies whether errors should be generated by the
+@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.
 
@@ -369,40 +402,40 @@ being listed.
 
 @subsubsection window_hints_values Supported and default values
 
-Window hint                     | Default value               | Supported values
-------------------------------- | --------------------------- | ----------------
-`GLFW_RESIZABLE`                | `GLFW_TRUE`                 | `GLFW_TRUE` or `GLFW_FALSE`
-`GLFW_VISIBLE`                  | `GLFW_TRUE`                 | `GLFW_TRUE` or `GLFW_FALSE`
-`GLFW_DECORATED`                | `GLFW_TRUE`                 | `GLFW_TRUE` or `GLFW_FALSE`
-`GLFW_FOCUSED`                  | `GLFW_TRUE`                 | `GLFW_TRUE` or `GLFW_FALSE`
-`GLFW_AUTO_ICONIFY`             | `GLFW_TRUE`                 | `GLFW_TRUE` or `GLFW_FALSE`
-`GLFW_FLOATING`                 | `GLFW_FALSE`                | `GLFW_TRUE` or `GLFW_FALSE`
-`GLFW_MAXIMIZED`                | `GLFW_FALSE`                | `GLFW_TRUE` or `GLFW_FALSE`
-`GLFW_RED_BITS`                 | 8                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
-`GLFW_GREEN_BITS`               | 8                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
-`GLFW_BLUE_BITS`                | 8                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
-`GLFW_ALPHA_BITS`               | 8                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
-`GLFW_DEPTH_BITS`               | 24                          | 0 to `INT_MAX` or `GLFW_DONT_CARE`
-`GLFW_STENCIL_BITS`             | 8                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
-`GLFW_ACCUM_RED_BITS`           | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
-`GLFW_ACCUM_GREEN_BITS`         | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
-`GLFW_ACCUM_BLUE_BITS`          | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
-`GLFW_ACCUM_ALPHA_BITS`         | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
-`GLFW_AUX_BUFFERS`              | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
-`GLFW_SAMPLES`                  | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
-`GLFW_REFRESH_RATE`             | `GLFW_DONT_CARE`            | 0 to `INT_MAX` or `GLFW_DONT_CARE`
-`GLFW_STEREO`                   | `GLFW_FALSE`                | `GLFW_TRUE` or `GLFW_FALSE`
-`GLFW_SRGB_CAPABLE`             | `GLFW_FALSE`                | `GLFW_TRUE` or `GLFW_FALSE`
-`GLFW_DOUBLEBUFFER`             | `GLFW_TRUE`                 | `GLFW_TRUE` or `GLFW_FALSE`
-`GLFW_CLIENT_API`               | `GLFW_OPENGL_API`           | `GLFW_OPENGL_API`, `GLFW_OPENGL_ES_API` or `GLFW_NO_API`
-`GLFW_CONTEXT_CREATION_API`     | `GLFW_NATIVE_CONTEXT_API`   | `GLFW_NATIVE_CONTEXT_API` or `GLFW_EGL_CONTEXT_API`
-`GLFW_CONTEXT_VERSION_MAJOR`    | 1                           | Any valid major version number of the chosen client API
-`GLFW_CONTEXT_VERSION_MINOR`    | 0                           | Any valid minor version number of the chosen client API
-`GLFW_CONTEXT_ROBUSTNESS`       | `GLFW_NO_ROBUSTNESS`        | `GLFW_NO_ROBUSTNESS`, `GLFW_NO_RESET_NOTIFICATION` or `GLFW_LOSE_CONTEXT_ON_RESET`
-`GLFW_CONTEXT_RELEASE_BEHAVIOR` | `GLFW_ANY_RELEASE_BEHAVIOR` | `GLFW_ANY_RELEASE_BEHAVIOR`, `GLFW_RELEASE_BEHAVIOR_FLUSH` or `GLFW_RELEASE_BEHAVIOR_NONE`
-`GLFW_OPENGL_FORWARD_COMPAT`    | `GLFW_FALSE`                | `GLFW_TRUE` or `GLFW_FALSE`
-`GLFW_OPENGL_DEBUG_CONTEXT`     | `GLFW_FALSE`                | `GLFW_TRUE` or `GLFW_FALSE`
-`GLFW_OPENGL_PROFILE`           | `GLFW_OPENGL_ANY_PROFILE`   | `GLFW_OPENGL_ANY_PROFILE`, `GLFW_OPENGL_COMPAT_PROFILE` or `GLFW_OPENGL_CORE_PROFILE`
+Window hint                   | Default value               | Supported values
+----------------------------- | --------------------------- | ----------------
+GLFW_RESIZABLE                | `GLFW_TRUE`                 | `GLFW_TRUE` or `GLFW_FALSE`
+GLFW_VISIBLE                  | `GLFW_TRUE`                 | `GLFW_TRUE` or `GLFW_FALSE`
+GLFW_DECORATED                | `GLFW_TRUE`                 | `GLFW_TRUE` or `GLFW_FALSE`
+GLFW_FOCUSED                  | `GLFW_TRUE`                 | `GLFW_TRUE` or `GLFW_FALSE`
+GLFW_AUTO_ICONIFY             | `GLFW_TRUE`                 | `GLFW_TRUE` or `GLFW_FALSE`
+GLFW_FLOATING                 | `GLFW_FALSE`                | `GLFW_TRUE` or `GLFW_FALSE`
+GLFW_MAXIMIZED                | `GLFW_FALSE`                | `GLFW_TRUE` or `GLFW_FALSE`
+GLFW_RED_BITS                 | 8                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
+GLFW_GREEN_BITS               | 8                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
+GLFW_BLUE_BITS                | 8                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
+GLFW_ALPHA_BITS               | 8                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
+GLFW_DEPTH_BITS               | 24                          | 0 to `INT_MAX` or `GLFW_DONT_CARE`
+GLFW_STENCIL_BITS             | 8                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
+GLFW_ACCUM_RED_BITS           | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
+GLFW_ACCUM_GREEN_BITS         | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
+GLFW_ACCUM_BLUE_BITS          | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
+GLFW_ACCUM_ALPHA_BITS         | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
+GLFW_AUX_BUFFERS              | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
+GLFW_SAMPLES                  | 0                           | 0 to `INT_MAX` or `GLFW_DONT_CARE`
+GLFW_REFRESH_RATE             | `GLFW_DONT_CARE`            | 0 to `INT_MAX` or `GLFW_DONT_CARE`
+GLFW_STEREO                   | `GLFW_FALSE`                | `GLFW_TRUE` or `GLFW_FALSE`
+GLFW_SRGB_CAPABLE             | `GLFW_FALSE`                | `GLFW_TRUE` or `GLFW_FALSE`
+GLFW_DOUBLEBUFFER             | `GLFW_TRUE`                 | `GLFW_TRUE` or `GLFW_FALSE`
+GLFW_CLIENT_API               | `GLFW_OPENGL_API`           | `GLFW_OPENGL_API`, `GLFW_OPENGL_ES_API` or `GLFW_NO_API`
+GLFW_CONTEXT_CREATION_API     | `GLFW_NATIVE_CONTEXT_API`   | `GLFW_NATIVE_CONTEXT_API` or `GLFW_EGL_CONTEXT_API`
+GLFW_CONTEXT_VERSION_MAJOR    | 1                           | Any valid major version number of the chosen client API
+GLFW_CONTEXT_VERSION_MINOR    | 0                           | Any valid minor version number of the chosen client API
+GLFW_CONTEXT_ROBUSTNESS       | `GLFW_NO_ROBUSTNESS`        | `GLFW_NO_ROBUSTNESS`, `GLFW_NO_RESET_NOTIFICATION` or `GLFW_LOSE_CONTEXT_ON_RESET`
+GLFW_CONTEXT_RELEASE_BEHAVIOR | `GLFW_ANY_RELEASE_BEHAVIOR` | `GLFW_ANY_RELEASE_BEHAVIOR`, `GLFW_RELEASE_BEHAVIOR_FLUSH` or `GLFW_RELEASE_BEHAVIOR_NONE`
+GLFW_OPENGL_FORWARD_COMPAT    | `GLFW_FALSE`                | `GLFW_TRUE` or `GLFW_FALSE`
+GLFW_OPENGL_DEBUG_CONTEXT     | `GLFW_FALSE`                | `GLFW_TRUE` or `GLFW_FALSE`
+GLFW_OPENGL_PROFILE           | `GLFW_OPENGL_ANY_PROFILE`   | `GLFW_OPENGL_ANY_PROFILE`, `GLFW_OPENGL_COMPAT_PROFILE` or `GLFW_OPENGL_CORE_PROFILE`
 
 
 @section window_events Window event processing
@@ -825,6 +858,14 @@ You can also get the current maximization state with @ref glfwGetWindowAttrib.
 int maximized = glfwGetWindowAttrib(window, GLFW_MAXIMIZED);
 @endcode
 
+By default, newly created windows are not maximized.  You can change this
+behavior by setting the [GLFW_MAXIMIZED](@ref GLFW_MAXIMIZED_hint) window hint
+before creating the window.
+
+@code
+glfwWindowHint(GLFW_MAXIMIZED, GLFW_TRUE);
+@endcode
+
 
 @subsection window_hide Window visibility
 
@@ -844,11 +885,6 @@ Hidden windows can be shown with @ref glfwShowWindow.
 glfwShowWindow(window);
 @endcode
 
-Windowed mode windows can be created initially hidden with the `GLFW_VISIBLE`
-[window hint](@ref window_hints_wnd).  Windows created hidden are completely
-invisible to the user until shown.  This can be useful if you need to set up
-your window further before showing it, for example moving it to a specific
-location.
 
 You can also get the current visibility state with @ref glfwGetWindowAttrib.
 
@@ -856,6 +892,18 @@ You can also get the current visibility state with @ref glfwGetWindowAttrib.
 int visible = glfwGetWindowAttrib(window, GLFW_VISIBLE);
 @endcode
 
+By default, newly created windows are visible.  You can change this behavior by
+setting the [GLFW_VISIBLE](@ref GLFW_VISIBLE_hint) window hint before creating
+the window.
+
+@code
+glfwWindowHint(GLFW_VISIBLE, GLFW_FALSE);
+@endcode
+
+Windows created hidden are completely invisible to the user until shown.  This
+can be useful if you need to set up your window further before showing it, for
+example moving it to a specific location.
+
 
 @subsection window_focus Window input focus
 
@@ -895,6 +943,14 @@ You can also get the current input focus state with @ref glfwGetWindowAttrib.
 int focused = glfwGetWindowAttrib(window, GLFW_FOCUSED);
 @endcode
 
+By default, newly created windows are given input focus.  You can change this
+behavior by setting the [GLFW_FOCUSED](@ref GLFW_FOCUSED_hint) window hint
+before creating the window.
+
+@code
+glfwWindowHint(GLFW_FOCUSED, GLFW_FALSE);
+@endcode
+
 
 @subsection window_refresh Window damage and refresh
 
@@ -939,62 +995,76 @@ if (glfwGetWindowAttrib(window, GLFW_FOCUSED))
 
 @subsubsection window_attribs_wnd Window related attributes
 
-`GLFW_FOCUSED` indicates whether the specified window has input focus.  Initial
-input focus is controlled by the [window hint](@ref window_hints_wnd) with the
-same name.   
+@anchor GLFW_FOCUSED_attrib
+__GLFW_FOCUSED__ indicates whether the specified window has input focus.  See
+@ref window_focus for details.
 
-`GLFW_ICONIFIED` indicates whether the specified window is iconified, whether by
-the user or with @ref glfwIconifyWindow.
+@anchor GLFW_ICONIFIED_attrib
+__GLFW_ICONIFIED__ indicates whether the specified window is iconified.
+See @ref window_iconify for details.
 
-`GLFW_MAXIMIZED` indicates whether the specified window is maximized, whether by
-the user or with @ref glfwMaximizeWindow.
+@anchor GLFW_MAXIMIZED_attrib
+__GLFW_MAXIMIZED__ indicates whether the specified window is maximized.  See
+@ref window_maximize for details.
 
-`GLFW_VISIBLE` indicates whether the specified window is visible.  Window
-visibility can be controlled with @ref glfwShowWindow and @ref glfwHideWindow
-and initial visibility is controlled by the [window hint](@ref window_hints_wnd)
-with the same name.  
+@anchor GLFW_VISIBLE_attrib
+__GLFW_VISIBLE__ indicates whether the specified window is visible.  See @ref
+window_hide for details.
 
-`GLFW_RESIZABLE` indicates whether the specified window is resizable _by the
-user_.  This is set on creation with the [window hint](@ref window_hints_wnd)
-  with the same name.
+@anchor GLFW_RESIZABLE_attrib
+__GLFW_RESIZABLE__ indicates whether the specified window is resizable _by the
+user_.  This is set before creation with the
+[GLFW_RESIZABLE](@ref GLFW_RESIZABLE_hint) window hint.
 
-`GLFW_DECORATED` indicates whether the specified window has decorations such as
-a border, a close widget, etc.  This is set on creation with the
-[window hint](@ref window_hints_wnd) with the same name. 
+@anchor GLFW_DECORATED_attrib
+__GLFW_DECORATED__ indicates whether the specified window has decorations such as
+a border, a close widget, etc.  This is set before creation with the
+[GLFW_DECORATED](@ref GLFW_DECORATED_hint) window hint.
 
-`GLFW_FLOATING` indicates whether the specified window is floating, also called
-topmost or always-on-top.  This is controlled by the
-[window hint](@ref window_hints_wnd) with the same name. 
+@anchor GLFW_FLOATING_attrib
+__GLFW_FLOATING__ indicates whether the specified window is floating, also
+called topmost or always-on-top.  This is controlled by the
+[GLFW_FLOATING](@ref GLFW_FLOATING_hint) window hint.
 
 
 @subsubsection window_attribs_ctx Context related attributes
 
-`GLFW_CLIENT_API` indicates the client API provided by the window's context;
+@anchor GLFW_CLIENT_API_attrib
+__GLFW_CLIENT_API__ indicates the client API provided by the window's context;
 either `GLFW_OPENGL_API`, `GLFW_OPENGL_ES_API` or `GLFW_NO_API`.
 
-`GLFW_CONTEXT_CREATION_API` indicates the context creation API used to create
+@anchor GLFW_CONTEXT_CREATION_API_attrib
+__GLFW_CONTEXT_CREATION_API__ indicates the context creation API used to create
 the window's context; either `GLFW_NATIVE_CONTEXT_API` or
 `GLFW_EGL_CONTEXT_API`.
 
-`GLFW_CONTEXT_VERSION_MAJOR`, `GLFW_CONTEXT_VERSION_MINOR` and
-`GLFW_CONTEXT_REVISION` indicate the client API version of the window's context.
+@anchor GLFW_CONTEXT_VERSION_MAJOR_attrib
+@anchor GLFW_CONTEXT_VERSION_MINOR_attrib
+@anchor GLFW_CONTEXT_REVISION_attrib
+__GLFW_CONTEXT_VERSION_MAJOR__, __GLFW_CONTEXT_VERSION_MINOR__ and
+__GLFW_CONTEXT_REVISION__ indicate the client API version of the window's
+context.
 
-`GLFW_OPENGL_FORWARD_COMPAT` is `GLFW_TRUE` if the window's context is an OpenGL
-forward-compatible one, or `GLFW_FALSE` otherwise.
+@anchor GLFW_OPENGL_FORWARD_COMPAT_attrib
+__GLFW_OPENGL_FORWARD_COMPAT__ is `GLFW_TRUE` if the window's context is an
+OpenGL forward-compatible one, or `GLFW_FALSE` otherwise.
 
-`GLFW_OPENGL_DEBUG_CONTEXT` is `GLFW_TRUE` if the window's context is an OpenGL
-debug context, or `GLFW_FALSE` otherwise.
+@anchor GLFW_OPENGL_DEBUG_CONTEXT_attrib
+__GLFW_OPENGL_DEBUG_CONTEXT__ is `GLFW_TRUE` if the window's context is an
+OpenGL debug context, or `GLFW_FALSE` otherwise.
 
-`GLFW_OPENGL_PROFILE` indicates the OpenGL profile used by the context.  This is
-`GLFW_OPENGL_CORE_PROFILE` or `GLFW_OPENGL_COMPAT_PROFILE` if the context uses
-a known profile, or `GLFW_OPENGL_ANY_PROFILE` if the OpenGL profile is unknown
-or the context is an OpenGL ES context.  Note that the returned profile may not
-match the profile bits of the context flags, as GLFW will try other means of
-detecting the profile when no bits are set.
+@anchor GLFW_OPENGL_PROFILE_attrib
+__GLFW_OPENGL_PROFILE__ indicates the OpenGL profile used by the context.  This
+is `GLFW_OPENGL_CORE_PROFILE` or `GLFW_OPENGL_COMPAT_PROFILE` if the context
+uses a known profile, or `GLFW_OPENGL_ANY_PROFILE` if the OpenGL profile is
+unknown or the context is an OpenGL ES context.  Note that the returned profile
+may not match the profile bits of the context flags, as GLFW will try other
+means of detecting the profile when no bits are set.
 
-`GLFW_CONTEXT_ROBUSTNESS` indicates the robustness strategy used by the context.
-This is `GLFW_LOSE_CONTEXT_ON_RESET` or `GLFW_NO_RESET_NOTIFICATION` if the
-window's context supports robustness, or `GLFW_NO_ROBUSTNESS` otherwise.
+@anchor GLFW_CONTEXT_ROBUSTNESS_attrib
+__GLFW_CONTEXT_ROBUSTNESS__ indicates the robustness strategy used by the
+context.  This is `GLFW_LOSE_CONTEXT_ON_RESET` or `GLFW_NO_RESET_NOTIFICATION`
+if the window's context supports robustness, or `GLFW_NO_ROBUSTNESS` otherwise.
 
 
 @subsubsection window_attribs_fb Framebuffer related attributes
diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h
index 15ace888..959d0c02 100644
--- a/include/GLFW/glfw3.h
+++ b/include/GLFW/glfw3.h
@@ -535,8 +535,7 @@ 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](@ref window_hints_fb) with @ref
- *  glfwGetWindowAttrib.
+ *  requesting @ref GLFW_RED_BITS with @ref glfwGetWindowAttrib.
  *
  *  @analysis Application programmer error.  Fix the offending call.
  */
@@ -633,31 +632,136 @@ extern "C" {
 #define GLFW_NO_WINDOW_CONTEXT      0x0001000A
 /*! @} */
 
+/*! @addtogroup window
+ *  @{ */
+/*! @brief Input focus window hint and attribute
+ *
+ *  Input focus [window hint](@ref GLFW_FOCUSED_hint) or
+ *  [window attribute](@ref GLFW_FOCUSED_attrib).
+ */
 #define GLFW_FOCUSED                0x00020001
+/*! @brief Window iconification window attribute
+ *
+ *  Window iconification [window attribute](@ref GLFW_ICONIFIED_attrib).
+ */
 #define GLFW_ICONIFIED              0x00020002
+/*! @brief Window resize-ability window hint and attribute
+ *
+ *  Window resize-ability [window hint](@ref GLFW_RESIZABLE_hint) or
+ *  [window attribute](@ref GLFW_RESIZABLE_attrib).
+ */
 #define GLFW_RESIZABLE              0x00020003
+/*! @brief Window visibility window hint and attribute
+ *
+ *  Window visibility [window hint](@ref GLFW_VISIBLE_hint) or
+ *  [window attribute](@ref GLFW_VISIBLE_attrib).
+ */
 #define GLFW_VISIBLE                0x00020004
+/*! @brief Window decoration window hint and attribute
+ *
+ *  Window decoration [window hint](@ref GLFW_DECORATED_hint) or
+ *  [window attribute](@ref GLFW_DECORATED_attrib).
+ */
 #define GLFW_DECORATED              0x00020005
+/*! @brief Window auto-iconification window hint
+ *
+ *  Window auto-iconification [window hint](@ref GLFW_AUTO_ICONIFY_hint).
+ */
 #define GLFW_AUTO_ICONIFY           0x00020006
+/*! @brief Window decoration window hint and attribute
+ *
+ *  Window decoration [window hint](@ref GLFW_FLOATING_hint) or
+ *  [window attribute](@ref GLFW_FLOATING_attrib).
+ */
 #define GLFW_FLOATING               0x00020007
+/*! @brief Window maximization window hint and attribute
+ *
+ *  Window maximization [window hint](@ref GLFW_MAXIMIZED_hint) or
+ *  [window attribute](@ref GLFW_MAXIMIZED_attrib).
+ */
 #define GLFW_MAXIMIZED              0x00020008
 
+/*! @brief Framebuffer bit depth hint.
+ *
+ *  Framebuffer bit depth [hint](@ref GLFW_RED_BITS).
+ */
 #define GLFW_RED_BITS               0x00021001
+/*! @brief Framebuffer bit depth hint.
+ *
+ *  Framebuffer bit depth [hint](@ref GLFW_GREEN_BITS).
+ */
 #define GLFW_GREEN_BITS             0x00021002
+/*! @brief Framebuffer bit depth hint.
+ *
+ *  Framebuffer bit depth [hint](@ref GLFW_BLUE_BITS).
+ */
 #define GLFW_BLUE_BITS              0x00021003
+/*! @brief Framebuffer bit depth hint.
+ *
+ *  Framebuffer bit depth [hint](@ref GLFW_ALPHA_BITS).
+ */
 #define GLFW_ALPHA_BITS             0x00021004
+/*! @brief Framebuffer bit depth hint.
+ *
+ *  Framebuffer bit depth [hint](@ref GLFW_DEPTH_BITS).
+ */
 #define GLFW_DEPTH_BITS             0x00021005
+/*! @brief Framebuffer bit depth hint.
+ *
+ *  Framebuffer bit depth [hint](@ref GLFW_STENCIL_BITS).
+ */
 #define GLFW_STENCIL_BITS           0x00021006
+/*! @brief Framebuffer bit depth hint.
+ *
+ *  Framebuffer bit depth [hint](@ref GLFW_ACCUM_RED_BITS).
+ */
 #define GLFW_ACCUM_RED_BITS         0x00021007
+/*! @brief Framebuffer bit depth hint.
+ *
+ *  Framebuffer bit depth [hint](@ref GLFW_ACCUM_GREEN_BITS).
+ */
 #define GLFW_ACCUM_GREEN_BITS       0x00021008
+/*! @brief Framebuffer bit depth hint.
+ *
+ *  Framebuffer bit depth [hint](@ref GLFW_ACCUM_BLUE_BITS).
+ */
 #define GLFW_ACCUM_BLUE_BITS        0x00021009
+/*! @brief Framebuffer bit depth hint.
+ *
+ *  Framebuffer bit depth [hint](@ref GLFW_ACCUM_ALPHA_BITS).
+ */
 #define GLFW_ACCUM_ALPHA_BITS       0x0002100A
+/*! @brief Framebuffer auxiliary buffer hint.
+ *
+ *  Framebuffer auxiliary buffer [hint](@ref GLFW_AUX_BUFFERS).
+ */
 #define GLFW_AUX_BUFFERS            0x0002100B
+/*! @brief OpenGL stereoscopic rendering hint.
+ *
+ *  OpenGL stereoscopic rendering [hint](@ref GLFW_STEREO).
+ */
 #define GLFW_STEREO                 0x0002100C
+/*! @brief Framebuffer MSAA samples hint.
+ *
+ *  Framebuffer MSAA samples [hint](@ref GLFW_SAMPLES).
+ */
 #define GLFW_SAMPLES                0x0002100D
+/*! @brief Framebuffer sRGB hint.
+ *
+ *  Framebuffer sRGB [hint](@ref GLFW_SRGB_CAPABLE).
+ */
 #define GLFW_SRGB_CAPABLE           0x0002100E
+/*! @brief Monitor refresh rate hint.
+ *
+ *  Monitor refresh rate [hint](@ref GLFW_REFRESH_RATE).
+ */
 #define GLFW_REFRESH_RATE           0x0002100F
+/*! @brief Framebuffer double buffering hint.
+ *
+ *  Framebuffer double buffering [hint](@ref GLFW_DOUBLEBUFFER).
+ */
 #define GLFW_DOUBLEBUFFER           0x00021010
+/*! @} */
 
 #define GLFW_CLIENT_API             0x00022001
 #define GLFW_CONTEXT_VERSION_MAJOR  0x00022002
@@ -1625,6 +1729,14 @@ GLFWAPI const GLFWvidmode* glfwGetVideoMode(GLFWmonitor* monitor);
  *  and then calls @ref glfwSetGammaRamp with it.  The value must be a finite
  *  number greater than zero.
  *
+ *  The software controlled gamma ramp is applied _in addition_ to the hardware
+ *  gamma correction, which today is usually an approximation of sRGB gamma.
+ *  This means that setting a perfectly linear ramp, or gamma 1.0, will produce
+ *  the default (usually sRGB-like) behavior.
+ *
+ *  For gamma correct rendering with OpenGL or OpenGL ES, see the @ref
+ *  GLFW_SRGB_CAPABLE hint.
+ *
  *  @param[in] monitor The monitor whose gamma ramp to set.
  *  @param[in] gamma The desired exponent.
  *
@@ -1679,6 +1791,14 @@ GLFWAPI const GLFWgammaramp* glfwGetGammaRamp(GLFWmonitor* monitor);
  *  original gamma ramp for that monitor is saved by GLFW the first time this
  *  function is called and is restored by @ref glfwTerminate.
  *
+ *  The software controlled gamma ramp is applied _in addition_ to the hardware
+ *  gamma correction, which today is usually an approximation of sRGB gamma.
+ *  This means that setting a perfectly linear ramp, or gamma 1.0, will produce
+ *  the default (usually sRGB-like) behavior.
+ *
+ *  For gamma correct rendering with OpenGL or OpenGL ES, see the @ref
+ *  GLFW_SRGB_CAPABLE hint.
+ *
  *  @param[in] monitor The monitor whose gamma ramp to set.
  *  @param[in] ramp The gamma ramp to use.
  *
@@ -1789,7 +1909,7 @@ GLFWAPI void glfwWindowHint(int hint, int value);
  *
  *  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](@ref window_hints_wnd) window
+ *  initially invisible using the [GLFW_VISIBLE](@ref GLFW_VISIBLE_hint) window
  *  hint, set its [position](@ref window_pos) and then [show](@ref window_hide)
  *  it.
  *
@@ -1834,9 +1954,9 @@ GLFWAPI void glfwWindowHint(int hint, int value);
  *  @remark @macos The OS only supports forward-compatible core profile contexts
  *  for OpenGL versions 3.2 and later.  Before creating an OpenGL context of
  *  version 3.2 or later you must set the
- *  [GLFW_OPENGL_FORWARD_COMPAT](@ref window_hints_ctx) and
- *  [GLFW_OPENGL_PROFILE](@ref window_hints_ctx) accordingly.  OpenGL 3.0 and
- *  3.1 contexts are not supported at all on macOS.
+ *  [GLFW_OPENGL_FORWARD_COMPAT](@ref GLFW_OPENGL_FORWARD_COMPAT_hint) and
+ *  [GLFW_OPENGL_PROFILE](@ref GLFW_OPENGL_PROFILE_hint) hints accordingly.
+ *  OpenGL 3.0 and 3.1 contexts are not supported at all on macOS.
  *
  *  @remark @macos 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.
@@ -1868,9 +1988,9 @@ GLFWAPI void glfwWindowHint(int hint, int value);
  *  creation.
  *
  *  @remark @wayland The window frame is currently unimplemented, as if
- *  `GLFW_DECORATED` was always set to `GLFW_FALSE`.  A compositor can still
- *  emit close, resize or maximize events, using for example a keybind
- *  mechanism.
+ *  [GLFW_DECORATED](@ref GLFW_DECORATED_hint) was always set to `GLFW_FALSE`.
+ *  A compositor can still emit close, resize or maximize events, using for
+ *  example a keybind mechanism.
  *
  *  @remark @wayland A full screen window will not attempt to change the mode,
  *  no matter what the requested size or refresh rate.
@@ -2314,8 +2434,8 @@ GLFWAPI void glfwGetFramebufferSize(GLFWwindow* window, int* width, int* height)
  *  GLFW_PLATFORM_ERROR.
  *
  *  @remark @wayland The window frame is currently unimplemented, as if
- *  `GLFW_DECORATED` was always set to `GLFW_FALSE`, so the returned values
- *  will always be zero.
+ *  [GLFW_DECORATED](@ref GLFW_DECORATED_hint) was always set to `GLFW_FALSE`,
+ *  so the returned values will always be zero.
  *
  *  @thread_safety This function must only be called from the main thread.
  *
@@ -2459,8 +2579,8 @@ GLFWAPI void glfwHideWindow(GLFWwindow* window);
  *  The window should already be visible and not iconified.
  *
  *  By default, both windowed and full screen mode windows are focused when
- *  initially created.  Set the [GLFW_FOCUSED](@ref window_hints_wnd) to disable
- *  this behavior.
+ *  initially created.  Set the [GLFW_FOCUSED](@ref GLFW_FOCUSED_hint) to
+ *  disable this behavior.
  *
  *  __Do not use this function__ to steal focus from other applications unless
  *  you are certain that is what the user wants.  Focus stealing can be
@@ -3982,7 +4102,8 @@ GLFWAPI uint64_t glfwGetTimerFrequency(void);
  *  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](@ref window_hints_ctx) window hint.
+ *  [GLFW_CONTEXT_RELEASE_BEHAVIOR](@ref GLFW_CONTEXT_RELEASE_BEHAVIOR_hint)
+ *  hint.
  *
  *  The specified window must have an OpenGL or OpenGL ES context.  Specifying
  *  a window without a context will generate a @ref GLFW_NO_WINDOW_CONTEXT
diff --git a/include/GLFW/glfw3native.h b/include/GLFW/glfw3native.h
index 8a1e1472..a3de4cad 100644
--- a/include/GLFW/glfw3native.h
+++ b/include/GLFW/glfw3native.h
@@ -455,6 +455,7 @@ GLFWAPI EGLSurface glfwGetEGLSurface(GLFWwindow* window);
 #if defined(GLFW_EXPOSE_NATIVE_OSMESA)
 /*! @brief Retrieves the color buffer associated with the specified window.
  *
+ *  @param[in] window The window whose color buffer to retrieve.
  *  @param[out] width Where to store the width of the color buffer, or `NULL`.
  *  @param[out] height Where to store the height of the color buffer, or `NULL`.
  *  @param[out] format Where to store the OSMesa pixel format of the color
@@ -475,6 +476,7 @@ GLFWAPI int glfwGetOSMesaColorBuffer(GLFWwindow* window, int* width, int* height
 
 /*! @brief Retrieves the depth buffer associated with the specified window.
  *
+ *  @param[in] window The window whose depth buffer to retrieve.
  *  @param[out] width Where to store the width of the depth buffer, or `NULL`.
  *  @param[out] height Where to store the height of the depth buffer, or `NULL`.
  *  @param[out] bytesPerValue Where to store the number of bytes per depth