From 1ba83ede448058c1da58966a87ff730e6a6182fe Mon Sep 17 00:00:00 2001
From: Doug Binks <doug@enkisoftware.com>
Date: Tue, 23 Mar 2021 14:40:54 +0000
Subject: [PATCH] User contexts: added context documentation and updated
 references

---
 docs/context.dox     | 42 ++++++++++++++++++++++++++++++++++++++++++
 docs/news.dox        |  6 +++---
 include/GLFW/glfw3.h | 12 ++++++++----
 3 files changed, 53 insertions(+), 7 deletions(-)

diff --git a/docs/context.dox b/docs/context.dox
index dd952122..eefe3a67 100644
--- a/docs/context.dox
+++ b/docs/context.dox
@@ -92,6 +92,28 @@ You can disable context creation by setting the
 without contexts must not be passed to @ref glfwMakeContextCurrent or @ref
 glfwSwapBuffers.
 
+@subsection context_user User contexts for multi context windows
+
+GLFW supports multiple OpenGL or OpenGL ES contexts per window. Providing
+a window with an existing OpenGL or OpenGL ES context has been created further
+user contexts can be created using @ref glfwCreateUserContext with the same
+API sharing the window context objects.
+
+@code
+GLFWusercontext* usercontext = glfwCreateUserContext(window);
+
+/* make the user context current */
+glfwMakeUserContextCurrent(usercontext);
+
+/* make the window context current */
+glfwMakeContextCurrent(window);
+
+/* destroy the user context */
+glfwDestroyUserContext(usercontext);
+
+@endcode
+
+User contexts See also the test program `usercontext`.
 
 @section context_current Current context
 
@@ -122,6 +144,26 @@ error.
  - @ref glfwExtensionSupported
  - @ref glfwGetProcAddress
 
+@subsection context_current_user Current user context
+
+When using [user contexts](@ref context_user) the user context can be
+made current using @ref glfwMakeUserContextCurrent.
+
+@code
+glfwMakeUserContextCurrent(usercontext);
+@endcode
+
+This makes the any window context non-current on the calling thread, such that
+a call to @ref glfwGetCurrentContext will return `NULL`.
+
+The current user context is returned by @ref glfwGetCurrentUserContext.
+
+@code
+GLFWusercontext* usercontext = glfwGetCurrentUserContext();
+@endcode
+
+This will return the current user context or `NULL` if either the main window context
+or no context is current.
 
 @section context_swap Buffer swapping
 
diff --git a/docs/news.dox b/docs/news.dox
index 064230fc..a5e02535 100644
--- a/docs/news.dox
+++ b/docs/news.dox
@@ -9,14 +9,14 @@
 
 @subsection features_34 New features in version 3.4
 
-@subsubsection user_context_34 Multiple window contexts
+@subsubsection context_user_34 Multiple window contexts
 
 GLFW now provides the ability to create multiple OpenGL and OpenGL ES
-contexts for a given window. Called user contexts, a [GLFWusercontext](@ref usercontext)
+contexts for a given window. Called user contexts, a [GLFWusercontext](@ref context_user)
 can be created using @ref glfwCreateUserContext,
 destroyed using @ref glfwDestroyUserContext, and managed with
 @ref glfwMakeUserContextCurrent and @ref glfwGetCurrentUserContext.
-For more information see the [user context](@ref usercontext) documentation.
+For more information see the [user context](@ref context_user) documentation.
 
 @subsubsection standard_cursors_34 More standard cursors
 
diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h
index 6540cf38..e3723380 100644
--- a/include/GLFW/glfw3.h
+++ b/include/GLFW/glfw3.h
@@ -1315,7 +1315,7 @@ typedef struct GLFWwindow GLFWwindow;
  *
  *  Opaque user OpenGL OpenGL ES context object.
  *
- *  @see @ref usercontext
+ *  @see @ref context_user
  *
  *  @since Added in version 3.4.
  *
@@ -5635,7 +5635,7 @@ GLFWAPI uint64_t glfwGetTimerFrequency(void);
  *
  *  @sa @ref context_current
  *  @sa @ref glfwGetCurrentContext
- *  @sa @ref usercontext_current
+ *  @sa @ref context_current_user
  *  @sa @ref glfwMakeUserContextCurrent
  *  @sa @ref glfwGetCurrentUserContext
  *
@@ -5854,6 +5854,7 @@ GLFWAPI GLFWglproc glfwGetProcAddress(const char* procname);
  *
  *  @thread_safety This function must only be called from the main thread.
  *
+ *  @sa @ref context_user
  *  @sa @ref usercontext_creation
  *  @sa @ref glfwDestroyUserContext
  *  @sa @ref window_creation
@@ -5887,6 +5888,7 @@ GLFWAPI GLFWusercontext* glfwCreateUserContext(GLFWwindow* window);
  *
  *  @thread_safety This function must only be called from the main thread.
  *
+ *  @sa @ref context_user
  *  @sa @ref usercontext_creation
  *  @sa @ref glfwCreateUserContext
  *  @sa @ref window_creation
@@ -5926,7 +5928,8 @@ GLFWAPI void glfwDestroyUserContext(GLFWusercontext* context);
  *
  *  @thread_safety This function may be called from any thread.
  *
- *  @sa @ref usercontext_current
+ *  @sa @ref context_user
+ *  @sa @ref context_current_user
  *  @sa @ref glfwGetCurrentUserContext
  *  @sa @ref context_current
  *  @sa @ref glfwMakeContextCurrent
@@ -5950,7 +5953,8 @@ GLFWAPI void glfwMakeUserContextCurrent(GLFWusercontext* context);
  *
  *  @thread_safety This function may be called from any thread.
  *
- *  @sa @ref usercontext_current
+ *  @sa @ref context_user
+ *  @sa @ref context_current_user
  *  @sa @ref glfwMakeUserContextCurrent
  *  @sa @ref context_current
  *  @sa @ref glfwMakeContextCurrent