Documentation work

[ci skip]

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