From 0df4e06f11a1b1933666f7abb40e4018d9cd2c88 Mon Sep 17 00:00:00 2001
From: Camilla Berglund <elmindreda@elmindreda.org>
Date: Sun, 13 Dec 2015 14:07:27 +0100
Subject: [PATCH] Make more RFC 2119 compliant use of may

---
 docs/compile.dox     |   2 +-
 docs/context.dox     |   2 +-
 docs/intro.dox       |   4 +-
 docs/moving.dox      |   4 +-
 docs/window.dox      |   2 +-
 include/GLFW/glfw3.h | 164 +++++++++++++++++++++----------------------
 src/glx_context.c    |   4 +-
 src/internal.h       |   4 +-
 8 files changed, 93 insertions(+), 93 deletions(-)

diff --git a/docs/compile.dox b/docs/compile.dox
index 30271358..8d801735 100644
--- a/docs/compile.dox
+++ b/docs/compile.dox
@@ -261,7 +261,7 @@ configurations and to create contexts.  The options are:
 Wayland and Mir both require the EGL backend.
 
 If you are building GLFW as a shared library / dynamic library / DLL then you
-must also define `_GLFW_BUILD_DLL`.  Otherwise, you may not define it.
+must also define `_GLFW_BUILD_DLL`.  Otherwise, you must not define it.
 
 If you are using the X11 window creation API, support for the following X11
 extensions can be enabled:
diff --git a/docs/context.dox b/docs/context.dox
index 6cc7d523..71545536 100644
--- a/docs/context.dox
+++ b/docs/context.dox
@@ -87,7 +87,7 @@ disabled with a [compile-time option](@ref compile_options_osx).
 
 You can disable context creation by setting the
 [GLFW_CLIENT_API](@ref window_hints_ctx) hint to `GLFW_NO_API`.  Windows without
-contexts may not be passed to @ref glfwMakeContextCurrent or @ref
+contexts must not be passed to @ref glfwMakeContextCurrent or @ref
 glfwSwapBuffers.
 
 
diff --git a/docs/intro.dox b/docs/intro.dox
index 4c0b60f6..cb3bdbc9 100644
--- a/docs/intro.dox
+++ b/docs/intro.dox
@@ -184,7 +184,7 @@ releases.
 @subsection reentrancy Reentrancy
 
 GLFW event processing and object creation and destruction are not reentrant.
-This means that the following functions may not be called from any callback
+This means that the following functions must not be called from any callback
 function:
 
  - @ref glfwCreateWindow
@@ -202,7 +202,7 @@ functions not on this list will not be made non-reentrant.
 
 @subsection thread_safety Thread safety
 
-Most GLFW functions may only be called from the main thread, but some may be
+Most GLFW functions must only be called from the main thread, but some may be
 called from any thread.  However, no GLFW function may be called from any thread
 but the main thread until GLFW has been successfully initialized, including
 functions that may called before initialization.
diff --git a/docs/moving.dox b/docs/moving.dox
index 4bdf51c9..49709d4b 100644
--- a/docs/moving.dox
+++ b/docs/moving.dox
@@ -53,7 +53,7 @@ TinyCThread.
 However, GLFW 3 has better support for _use from multiple threads_ than GLFW
 2 had.  Contexts can be made current on any thread, although only a single
 thread at a time, and the documentation explicitly states which functions may be
-used from any thread and which may only be used from the main thread.
+used from any thread and which must only be used from the main thread.
 
 @par Removed functions
 `glfwSleep`, `glfwCreateThread`, `glfwDestroyThread`, `glfwWaitThread`,
@@ -416,7 +416,7 @@ these hotkeys to function even when running in full screen mode.
 
 GLFW 3 does not register @ref glfwTerminate with `atexit` at initialization,
 because `exit` calls registered functions from the calling thread and while it
-is permitted to call `exit` from any thread, @ref glfwTerminate may only be
+is permitted to call `exit` from any thread, @ref glfwTerminate must only be
 called from the main thread.
 
 To release all resources allocated by GLFW, you should call @ref glfwTerminate
diff --git a/docs/window.dox b/docs/window.dox
index 1f6d1e59..876927c7 100644
--- a/docs/window.dox
+++ b/docs/window.dox
@@ -252,7 +252,7 @@ compatible with 1.x.
 
 `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 may only be used if the requested OpenGL
+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.
 
 @par
diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h
index 81acecdc..520c95b5 100644
--- a/include/GLFW/glfw3.h
+++ b/include/GLFW/glfw3.h
@@ -173,7 +173,7 @@ extern "C" {
   * version of the GLFW library.  _GLFW_BUILD_DLL is defined by the GLFW
   * configuration header when compiling the DLL version of the library.
   */
- #error "You may not have both GLFW_DLL and _GLFW_BUILD_DLL defined"
+ #error "You must not have both GLFW_DLL and _GLFW_BUILD_DLL defined"
 #endif
 
 /* GLFWAPI is used to declare public API functions for export
@@ -494,7 +494,7 @@ extern "C" {
  *  @{ */
 /*! @brief GLFW has not been initialized.
  *
- *  This occurs if a GLFW function was called that may not be called unless the
+ *  This occurs if a GLFW function was called that must not be called unless the
  *  library is [initialized](@ref intro_init).
  *
  *  @par Analysis
@@ -1138,7 +1138,7 @@ typedef struct GLFWimage
  *  [compile-time option](@ref compile_options_osx).
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref intro_init
  *  @sa glfwTerminate
@@ -1163,14 +1163,14 @@ GLFWAPI int glfwInit(void);
  *
  *  @remarks This function may be called before @ref glfwInit.
  *
- *  @warning No window's context may be current on another thread when this
- *  function is called.
+ *  @warning The contexts of any remaining windows must not be current on any
+ *  other thread when this function is called.
  *
  *  @par Reentrancy
- *  This function may not be called from a callback.
+ *  This function must not be called from a callback.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref intro_init
  *  @sa glfwInit
@@ -1263,7 +1263,7 @@ GLFWAPI const char* glfwGetVersionString(void);
  *  @remarks This function may be called before @ref glfwInit.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref error_handling
  *
@@ -1290,7 +1290,7 @@ GLFWAPI GLFWerrorfun glfwSetErrorCallback(GLFWerrorfun cbfun);
  *  changes or the library is terminated.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref monitor_monitors
  *  @sa @ref monitor_event
@@ -1311,7 +1311,7 @@ GLFWAPI GLFWmonitor** glfwGetMonitors(int* count);
  *  [error](@ref error_handling) occurred.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @remarks The primary monitor is always first in the array returned by @ref
  *  glfwGetMonitors.
@@ -1338,7 +1338,7 @@ GLFWAPI GLFWmonitor* glfwGetPrimaryMonitor(void);
  *  @param[out] ypos Where to store the monitor y-coordinate, or `NULL`.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref monitor_properties
  *
@@ -1371,7 +1371,7 @@ GLFWAPI void glfwGetMonitorPos(GLFWmonitor* monitor, int* xpos, int* ypos);
  *  current resolution and system DPI instead of querying the monitor EDID data.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref monitor_properties
  *
@@ -1397,7 +1397,7 @@ GLFWAPI void glfwGetMonitorPhysicalSize(GLFWmonitor* monitor, int* widthMM, int*
  *  library is terminated.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref monitor_properties
  *
@@ -1419,7 +1419,7 @@ GLFWAPI const char* glfwGetMonitorName(GLFWmonitor* monitor);
  *  library had not been [initialized](@ref intro_init).
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref monitor_event
  *
@@ -1448,7 +1448,7 @@ GLFWAPI GLFWmonitorfun glfwSetMonitorCallback(GLFWmonitorfun cbfun);
  *  function is called again for that monitor or the library is terminated.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref monitor_modes
  *  @sa glfwGetVideoMode
@@ -1478,7 +1478,7 @@ GLFWAPI const GLFWvidmode* glfwGetVideoModes(GLFWmonitor* monitor, int* count);
  *  library is terminated.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref monitor_modes
  *  @sa glfwGetVideoModes
@@ -1499,7 +1499,7 @@ GLFWAPI const GLFWvidmode* glfwGetVideoMode(GLFWmonitor* monitor);
  *  @param[in] gamma The desired exponent.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref monitor_gamma
  *
@@ -1524,7 +1524,7 @@ GLFWAPI void glfwSetGamma(GLFWmonitor* monitor, float gamma);
  *  library is terminated.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref monitor_gamma
  *
@@ -1552,7 +1552,7 @@ GLFWAPI const GLFWgammaramp* glfwGetGammaRamp(GLFWmonitor* monitor);
  *  The specified gamma ramp is copied before this function returns.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref monitor_gamma
  *
@@ -1568,7 +1568,7 @@ GLFWAPI void glfwSetGammaRamp(GLFWmonitor* monitor, const GLFWgammaramp* ramp);
  *  [default values](@ref window_hints_values).
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref window_hints
  *  @sa glfwWindowHint
@@ -1590,7 +1590,7 @@ GLFWAPI void glfwDefaultWindowHints(void);
  *  @param[in] hint The new value of the window hint.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref window_hints
  *  @sa glfwDefaultWindowHints
@@ -1667,8 +1667,8 @@ GLFWAPI void glfwWindowHint(int target, int hint);
  *  `GLFW_ICON,` it will be set as the icon for the window.  If no such icon is
  *  present, the `IDI_WINLOGO` icon will be used instead.
  *
- *  @remarks __Windows:__ The context to share resources with may not be current
- *  on any other thread.
+ *  @remarks __Windows:__ The context to share resources with must not be
+ *  current on any other thread.
  *
  *  @remarks __OS X:__ The GLFW window has no icon, as it is not a document
  *  window, but the dock icon will be the same as the application bundle's icon.
@@ -1702,10 +1702,10 @@ GLFWAPI void glfwWindowHint(int target, int hint);
  *  window creation.
  *
  *  @par Reentrancy
- *  This function may not be called from a callback.
+ *  This function must not be called from a callback.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref window_creation
  *  @sa glfwDestroyWindow
@@ -1730,10 +1730,10 @@ GLFWAPI GLFWwindow* glfwCreateWindow(int width, int height, const char* title, G
  *  thread when this function is called.
  *
  *  @par Reentrancy
- *  This function may not be called from a callback.
+ *  This function must not be called from a callback.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref window_creation
  *  @sa glfwCreateWindow
@@ -1794,7 +1794,7 @@ GLFWAPI void glfwSetWindowShouldClose(GLFWwindow* window, int value);
  *  you process events.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref window_title
  *
@@ -1822,7 +1822,7 @@ GLFWAPI void glfwSetWindowTitle(GLFWwindow* window, const char* title);
  *  the client area, or `NULL`.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref window_pos
  *  @sa glfwSetWindowPos
@@ -1850,7 +1850,7 @@ GLFWAPI void glfwGetWindowPos(GLFWwindow* window, int* xpos, int* ypos);
  *  @param[in] ypos The y-coordinate of the upper-left corner of the client area.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref window_pos
  *  @sa glfwGetWindowPos
@@ -1880,7 +1880,7 @@ GLFWAPI void glfwSetWindowPos(GLFWwindow* window, int xpos, int ypos);
  *  client area, or `NULL`.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref window_size
  *  @sa glfwSetWindowSize
@@ -1917,7 +1917,7 @@ GLFWAPI void glfwGetWindowSize(GLFWwindow* window, int* width, int* height);
  *  results are undefined.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref window_sizelimits
  *  @sa glfwSetWindowAspectRatio
@@ -1954,7 +1954,7 @@ GLFWAPI void glfwSetWindowSizeLimits(GLFWwindow* window, int minwidth, int minhe
  *  results are undefined.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref window_sizelimits
  *  @sa glfwSetWindowSizeLimits
@@ -1983,7 +1983,7 @@ GLFWAPI void glfwSetWindowAspectRatio(GLFWwindow* window, int numer, int denom);
  *  @param[in] height The desired height of the specified window.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref window_size
  *  @sa glfwGetWindowSize
@@ -2013,7 +2013,7 @@ GLFWAPI void glfwSetWindowSize(GLFWwindow* window, int width, int height);
  *  or `NULL`.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref window_fbsize
  *  @sa glfwSetFramebufferSizeCallback
@@ -2049,7 +2049,7 @@ GLFWAPI void glfwGetFramebufferSize(GLFWwindow* window, int* width, int* height)
  *  bottom edge of the window frame, or `NULL`.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref window_size
  *
@@ -2071,7 +2071,7 @@ GLFWAPI void glfwGetWindowFrameSize(GLFWwindow* window, int* left, int* top, int
  *  @param[in] window The window to iconify.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref window_iconify
  *  @sa glfwRestoreWindow
@@ -2096,7 +2096,7 @@ GLFWAPI void glfwIconifyWindow(GLFWwindow* window);
  *  @param[in] window The window to restore.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref window_iconify
  *  @sa glfwIconifyWindow
@@ -2119,7 +2119,7 @@ GLFWAPI void glfwRestoreWindow(GLFWwindow* window);
  *  @param[in] window The window to make visible.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref window_hide
  *  @sa glfwHideWindow
@@ -2139,7 +2139,7 @@ GLFWAPI void glfwShowWindow(GLFWwindow* window);
  *  @param[in] window The window to hide.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref window_hide
  *  @sa glfwShowWindow
@@ -2160,7 +2160,7 @@ GLFWAPI void glfwHideWindow(GLFWwindow* window);
  *  occurred.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref window_monitor
  *
@@ -2190,7 +2190,7 @@ GLFWAPI GLFWmonitor* glfwGetWindowMonitor(GLFWwindow* window);
  *  valid arguments and the library has been [initialized](@ref intro_init).
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref window_attribs
  *
@@ -2254,7 +2254,7 @@ GLFWAPI void* glfwGetWindowUserPointer(GLFWwindow* window);
  *  library had not been [initialized](@ref intro_init).
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref window_pos
  *
@@ -2277,7 +2277,7 @@ GLFWAPI GLFWwindowposfun glfwSetWindowPosCallback(GLFWwindow* window, GLFWwindow
  *  library had not been [initialized](@ref intro_init).
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref window_size
  *
@@ -2311,7 +2311,7 @@ GLFWAPI GLFWwindowsizefun glfwSetWindowSizeCallback(GLFWwindow* window, GLFWwind
  *  trigger the close callback for all windows.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref window_close
  *
@@ -2341,7 +2341,7 @@ GLFWAPI GLFWwindowclosefun glfwSetWindowCloseCallback(GLFWwindow* window, GLFWwi
  *  library had not been [initialized](@ref intro_init).
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref window_refresh
  *
@@ -2371,7 +2371,7 @@ GLFWAPI GLFWwindowrefreshfun glfwSetWindowRefreshCallback(GLFWwindow* window, GL
  *  library had not been [initialized](@ref intro_init).
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref window_focus
  *
@@ -2393,7 +2393,7 @@ GLFWAPI GLFWwindowfocusfun glfwSetWindowFocusCallback(GLFWwindow* window, GLFWwi
  *  library had not been [initialized](@ref intro_init).
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref window_iconify
  *
@@ -2415,7 +2415,7 @@ GLFWAPI GLFWwindowiconifyfun glfwSetWindowIconifyCallback(GLFWwindow* window, GL
  *  library had not been [initialized](@ref intro_init).
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref window_fbsize
  *
@@ -2444,10 +2444,10 @@ GLFWAPI GLFWframebuffersizefun glfwSetFramebufferSizeCallback(GLFWwindow* window
  *  Event processing is not required for joystick input to work.
  *
  *  @par Reentrancy
- *  This function may not be called from a callback.
+ *  This function must not be called from a callback.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref events
  *  @sa glfwWaitEvents
@@ -2487,10 +2487,10 @@ GLFWAPI void glfwPollEvents(void);
  *  Event processing is not required for joystick input to work.
  *
  *  @par Reentrancy
- *  This function may not be called from a callback.
+ *  This function must not be called from a callback.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref events
  *  @sa glfwPollEvents
@@ -2533,7 +2533,7 @@ GLFWAPI void glfwPostEmptyEvent(void);
  *  `GLFW_STICKY_MOUSE_BUTTONS`.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa glfwSetInputMode
  *
@@ -2579,7 +2579,7 @@ GLFWAPI int glfwGetInputMode(GLFWwindow* window, int mode);
  *  @param[in] value The new value of the specified input mode.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa glfwGetInputMode
  *
@@ -2606,7 +2606,7 @@ GLFWAPI void glfwSetInputMode(GLFWwindow* window, int mode, int value);
  *  the library is terminated.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref input_key_name
  *
@@ -2643,7 +2643,7 @@ GLFWAPI const char* glfwGetKeyName(int key, int scancode);
  *  @return One of `GLFW_PRESS` or `GLFW_RELEASE`.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref input_key
  *
@@ -2672,7 +2672,7 @@ GLFWAPI int glfwGetKey(GLFWwindow* window, int key);
  *  @return One of `GLFW_PRESS` or `GLFW_RELEASE`.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref input_mouse_button
  *
@@ -2710,7 +2710,7 @@ GLFWAPI int glfwGetMouseButton(GLFWwindow* window, int button);
  *  top edge of the client area, or `NULL`.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref cursor_pos
  *  @sa glfwSetCursorPos
@@ -2749,7 +2749,7 @@ GLFWAPI void glfwGetCursorPos(GLFWwindow* window, double* xpos, double* ypos);
  *  able to set the cursor position directly after window creation.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref cursor_pos
  *  @sa glfwGetCursorPos
@@ -2785,10 +2785,10 @@ GLFWAPI void glfwSetCursorPos(GLFWwindow* window, double xpos, double ypos);
  *  The specified image data is copied before this function returns.
  *
  *  @par Reentrancy
- *  This function may not be called from a callback.
+ *  This function must not be called from a callback.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref cursor_object
  *  @sa glfwDestroyCursor
@@ -2811,10 +2811,10 @@ GLFWAPI GLFWcursor* glfwCreateCursor(const GLFWimage* image, int xhot, int yhot)
  *  [error](@ref error_handling) occurred.
  *
  *  @par Reentrancy
- *  This function may not be called from a callback.
+ *  This function must not be called from a callback.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref cursor_object
  *  @sa glfwCreateCursor
@@ -2834,10 +2834,10 @@ GLFWAPI GLFWcursor* glfwCreateStandardCursor(int shape);
  *  @param[in] cursor The cursor object to destroy.
  *
  *  @par Reentrancy
- *  This function may not be called from a callback.
+ *  This function must not be called from a callback.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref cursor_object
  *  @sa glfwCreateCursor
@@ -2863,7 +2863,7 @@ GLFWAPI void glfwDestroyCursor(GLFWcursor* cursor);
  *  arrow cursor.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref cursor_object
  *
@@ -2904,7 +2904,7 @@ GLFWAPI void glfwSetCursor(GLFWwindow* window, GLFWcursor* cursor);
  *  library had not been [initialized](@ref intro_init).
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref input_key
  *
@@ -2943,7 +2943,7 @@ GLFWAPI GLFWkeyfun glfwSetKeyCallback(GLFWwindow* window, GLFWkeyfun cbfun);
  *  library had not been [initialized](@ref intro_init).
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref input_char
  *
@@ -2978,7 +2978,7 @@ GLFWAPI GLFWcharfun glfwSetCharCallback(GLFWwindow* window, GLFWcharfun cbfun);
  *  error occurred.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref input_char
  *
@@ -3006,7 +3006,7 @@ GLFWAPI GLFWcharmodsfun glfwSetCharModsCallback(GLFWwindow* window, GLFWcharmods
  *  library had not been [initialized](@ref intro_init).
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref input_mouse_button
  *
@@ -3033,7 +3033,7 @@ GLFWAPI GLFWmousebuttonfun glfwSetMouseButtonCallback(GLFWwindow* window, GLFWmo
  *  library had not been [initialized](@ref intro_init).
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref cursor_pos
  *
@@ -3056,7 +3056,7 @@ GLFWAPI GLFWcursorposfun glfwSetCursorPosCallback(GLFWwindow* window, GLFWcursor
  *  library had not been [initialized](@ref intro_init).
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref cursor_enter
  *
@@ -3082,7 +3082,7 @@ GLFWAPI GLFWcursorenterfun glfwSetCursorEnterCallback(GLFWwindow* window, GLFWcu
  *  library had not been [initialized](@ref intro_init).
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref scrolling
  *
@@ -3109,7 +3109,7 @@ GLFWAPI GLFWscrollfun glfwSetScrollCallback(GLFWwindow* window, GLFWscrollfun cb
  *  library had not been [initialized](@ref intro_init).
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref path_drop
  *
@@ -3127,7 +3127,7 @@ GLFWAPI GLFWdropfun glfwSetDropCallback(GLFWwindow* window, GLFWdropfun cbfun);
  *  @return `GLFW_TRUE` if the joystick is present, or `GLFW_FALSE` otherwise.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref joystick
  *
@@ -3153,7 +3153,7 @@ GLFWAPI int glfwJoystickPresent(int joy);
  *  function is called again for that joystick or the library is terminated.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref joystick_axis
  *
@@ -3179,7 +3179,7 @@ GLFWAPI const float* glfwGetJoystickAxes(int joy, int* count);
  *  function is called again for that joystick or the library is terminated.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref joystick_button
  *
@@ -3208,7 +3208,7 @@ GLFWAPI const unsigned char* glfwGetJoystickButtons(int joy, int* count);
  *  function is called again for that joystick or the library is terminated.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref joystick_name
  *
@@ -3230,7 +3230,7 @@ GLFWAPI const char* glfwGetJoystickName(int joy);
  *  The specified string is copied before this function returns.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref clipboard
  *  @sa glfwGetClipboardString
@@ -3259,7 +3259,7 @@ GLFWAPI void glfwSetClipboardString(GLFWwindow* window, const char* string);
  *  is terminated.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref clipboard
  *  @sa glfwSetClipboardString
@@ -3307,7 +3307,7 @@ GLFWAPI double glfwGetTime(void);
  *  storing nanoseconds in 64 bits.  The limit may be increased in the future.
  *
  *  @par Thread Safety
- *  This function may only be called from the main thread.
+ *  This function must only be called from the main thread.
  *
  *  @sa @ref time
  *
diff --git a/src/glx_context.c b/src/glx_context.c
index 426249d4..92cf7610 100644
--- a/src/glx_context.c
+++ b/src/glx_context.c
@@ -300,8 +300,8 @@ int _glfwInitContextAPI(void)
 //
 void _glfwTerminateContextAPI(void)
 {
-    // NOTE: This function may not call any X11 functions, as it is called after
-    //       XCloseDisplay (see _glfwPlatformTerminate for details)
+    // NOTE: This function must not call any X11 functions, as it is called
+    //       after XCloseDisplay (see _glfwPlatformTerminate for details)
 
     if (_glfw.glx.handle)
     {
diff --git a/src/internal.h b/src/internal.h
index daa573ba..d9ae4d41 100644
--- a/src/internal.h
+++ b/src/internal.h
@@ -41,7 +41,7 @@
     defined(GLFW_INCLUDE_GLEXT)     || \
     defined(GLFW_INCLUDE_GLU)       || \
     defined(GLFW_DLL)
- #error "You may not define any header option macros when compiling GLFW"
+ #error "You must not define any header option macros when compiling GLFW"
 #endif
 
 #define GLFW_INCLUDE_NONE
@@ -124,7 +124,7 @@ typedef int GLFWbool;
  *  @brief Various utility functions for internal use.
  *
  *  These functions are shared code and may be used by any part of GLFW
- *  Each platform may add its own utility functions, but those may only be
+ *  Each platform may add its own utility functions, but those must only be
  *  called by the platform-specific code
  */