Documentation work

[ci skip]

docs/intro.dox

@@ -84,7 +84,7 @@ buttons, for compatibility with earlier versions of GLFW that did not have @ref
 glfwGetJoystickHats.
 
 
-@subsubsection init_hints_osx macOS specific hints
+@subsubsection init_hints_osx macOS specific init hints
 
 @anchor GLFW_COCOA_CHDIR_RESOURCES
 __GLFW_COCOA_CHDIR_RESOURCES__ specifies whether to set the current directory to
@@ -143,8 +143,8 @@ if (code != GLFW_NO_ERROR)
     handle_error(code);
 @endcode
 
-If no error has occurred since the last call, @ref GLFW_NO_ERROR is returned.
+If no error has occurred since the last call, @ref GLFW_NO_ERROR (zero) is
-The error is cleared before the function returns.
+returned.  The error is cleared before the function returns.
 
 The error code indicates the general category of the error.  Some error codes,
 such as @ref GLFW_NOT_INITIALIZED has only a single meaning, whereas others like

docs/main.dox

@@ -8,7 +8,7 @@ GLFW is a free, Open Source, multi-platform library for OpenGL, OpenGL ES and
 Vulkan application development.  It provides a simple, platform-independent API
 for creating windows, contexts and surfaces, reading input, handling events, etc.
 
-See @ref news_33 for release highlights or the
+See @ref news_33 for highlights or the
 [version history](http://www.glfw.org/changelog.html) for details.
 
 @ref quick_guide is a guide for users new to GLFW.  It takes you through how to

docs/news.dox

@@ -1,8 +1,8 @@
 /*!
 
-@page news New features
+@page news Release notes
 
-@section news_33 New features in 3.3
+@section news_33 Release notes for 3.3
 
 
 @subsection news_33_geterror Error query
@@ -15,20 +15,26 @@ human-readable description with @ref glfwGetError.
 
 @subsection news_33_attention User attention request
 
-GLFW now supports requesting user attention with @ref
+GLFW now supports requesting user attention to a specific window (on macOS to
-glfwRequestWindowAttention.
+the application as a whole) with @ref glfwRequestWindowAttention.
+
+@see @ref window_attention
 
 
 @subsection news_33_maximize Window maximization callback
 
-GLFW now supports window maximization notifications with @ref
+GLFW now supports notifying the application that the window has been maximized
-glfwSetWindowMaximizeCallback.
+@ref glfwSetWindowMaximizeCallback.
+
+@see @ref window_maximize
 
 
 @subsection news_33_keyscancode Platform-specific key scancode query
 
-GLFW now supports querying the platform dependent scancode of any key with
+GLFW now supports querying the platform dependent scancode of any physical key
-@ref glfwGetKeyScancode.
+with @ref glfwGetKeyScancode.
+
+@see @ref input_key
 
 
 @subsection news_33_setwindowattrib Support for updating window attributes
@@ -39,33 +45,46 @@ GLFW now supports changing the [GLFW_DECORATED](@ref GLFW_DECORATED_attrib),
 [GLFW_AUTO_ICONIFY](@ref GLFW_AUTO_ICONIFY_attrib) attributes for existing
 windows with @ref glfwSetWindowAttrib.
 
-
+@see @ref window_attribs
-@subsection news_33_joyhats Support for joystick hats
-
-GLFW now supports querying the hats of a joystick with @ref glfwGetJoystickHats
-and controlling whether hats are also exposed as buttons with the @ref
-GLFW_JOYSTICK_HAT_BUTTONS init hint.
 
 
 @subsection news_33_inithint Support for initialization hints
 
 GLFW now supports setting library initialization hints with @ref glfwInitHint.
-Currently the macOS specific @ref
+These must be set before initialization to take effect.
-GLFW_COCOA_CHDIR_RESOURCES and @ref GLFW_COCOA_MENUBAR init hints are supported,
+
-replacing the corresponding compile-time options.
+@see @ref init_hints
+
+
+@subsection news_33_platformhints Support for platform specific hints
+
+GLFW now supports platform specific init and window hints to control system
+features that are only available on a single platform.
+
+@see @ref init_hints_osx
+@see @ref window_hints_osx
+
+
+@subsection news_33_joyhats Support for joystick hats
+
+GLFW now supports querying the hats (or POVs or D-pads) of a joystick with @ref
+glfwGetJoystickHats.  Hats are by default also exposed as buttons, but this can
+be disabled with the @ref GLFW_JOYSTICK_HAT_BUTTONS init hint.
+
+@see @ref joystick_hat
 
 
 @subsection news_33_centercursor Cursor centering window hint
 
 GLFW now supports controlling whether the cursor is centered over newly created
 full screen windows with the [GLFW_CENTER_CURSOR](@ref GLFW_CENTER_CURSOR_hint)
-window hint.
+window hint.  It is enabled by default.
 
 
 @subsection news_33_rawmotion Support for raw mouse motion
 
-GLFW now supports raw mouse motion in disabled cursor mode on platforms where
+GLFW now uses raw (unscaled and unaccelerated) mouse motion in disabled cursor
-this is available.
+mode on platforms where this is available, specifically Windows and X11.
 
 
 @subsection news_33_moltenvk Support for Vulkan on macOS via MoltenVK
@@ -73,6 +92,8 @@ this is available.
 GLFW now supports the `VK_MVK_macos_surface` window surface creation extension
 provided by [MoltenVK](https://moltengl.com/moltenvk/).
 
+@see @ref vulkan_guide
+
 
 @subsection news_33_osmesa OSMesa backend for headless software rendering
 
@@ -81,12 +102,12 @@ GLFW now supports creating offscreen OpenGL contexts using
 [GLFW_CONTEXT_CREATION_API](@ref GLFW_CONTEXT_CREATION_API_hint) to
 `GLFW_OSMESA_CONTEXT_API`.
 
-There is also a new headless backend that uses OSMesa as its native context
+There is also a new null backend that uses OSMesa as its native context
 creation API, intended for automated testing.  This backend does not provide
 input.
 
 
-@section news_32 New features in 3.2
+@section news_32 Release notes for 3.2
 
 
 @subsection news_32_vulkan Support for Vulkan
@@ -177,7 +198,7 @@ GLFW now supports being used as a
 easy linking with the library and its dependencies.
 
 
-@section news_31 New features in 3.1
+@section news_31 Release notes for 3.1
 
 These are the release highlights.  For a full list of changes see the
 [version history](http://www.glfw.org/changelog.html).
@@ -288,7 +309,7 @@ GLFW now has an _experimental_ Mir display server backend that can be selected
 on Linux with a CMake option.
 
 
-@section news_30 New features in 3.0
+@section news_30 Release notes for 3.0
 
 These are the release highlights.  For a full list of changes see the
 [version history](http://www.glfw.org/changelog.html).

docs/window.dox

@@ -427,7 +427,7 @@ The no error mode for OpenGL and OpenGL ES is described in detail by the
 extension.
 
 
-@subsubsection window_hints_osx macOS specific hints
+@subsubsection window_hints_osx macOS specific window hints
 
 @anchor GLFW_COCOA_RETINA_FRAMEBUFFER_hint
 __GLFW_COCOA_RETINA_FRAMEBUFFER__ specifies whether to use full resolution

include/GLFW/glfw3.h

@@ -1648,11 +1648,12 @@ GLFWAPI const char* glfwGetVersionString(void);
  *  This function returns and clears the [error code](@ref error) of the last
  *  error that occurred on the calling thread, and optionally a UTF-8 encoded
  *  human-readable description of it.  If no error has occurred since the last
- *  call, it returns @ref GLFW_NO_ERROR and the description pointer is set to
+ *  call, it returns @ref GLFW_NO_ERROR (zero) and the description pointer is
- *  `NULL`.
+ *  set to `NULL`.
  *
  *  @param[in] description Where to store the error description pointer, or `NULL`.
- *  @return The last error code for the calling thread, or @ref GLFW_NO_ERROR.
+ *  @return The last error code for the calling thread, or @ref GLFW_NO_ERROR
+ *  (zero).
  *
  *  @errors None.
  *