Documentation work

README.md

@@ -132,6 +132,7 @@ information on what to include when reporting a bug.
  - Added `glfwInitAllocator` for setting a custom memory allocator (#544,#1628,#1947)
  - Added `GLFWallocator` struct and `GLFWallocatefun`, `GLFWreallocatefun` and
    `GLFWdeallocatefun` types (#544,#1628,#1947)
+ - Added `glfwGetWindowTitle` function for querying window title (#1448,#1909,#2482)
  - Added `glfwInitVulkanLoader` for using a non-default Vulkan loader (#1374,#1890)
  - Added `GLFW_RESIZE_NWSE_CURSOR`, `GLFW_RESIZE_NESW_CURSOR`,
    `GLFW_RESIZE_ALL_CURSOR` and `GLFW_NOT_ALLOWED_CURSOR` cursor shapes (#427)
@@ -167,7 +168,6 @@ information on what to include when reporting a bug.
  - Added support for `XDG_SESSION_TYPE` environment variable
  - Added `GLFW_PKG_CONFIG_REQUIRES_PRIVATE` and `GLFW_PKG_CONFIG_LIBS_PRIVATE` CMake
    variables exposing pkg-config dependencies (#1307)
- - Added `glfwGetWindowTitle` function for GLFWwindow for querying window titles (#1448,#1909)
  - Made joystick subsystem initialize at first use (#1284,#1646)
  - Made `GLFW_DOUBLEBUFFER` a read-only window attribute
  - Updated the minimum required CMake version to 3.1

docs/news.md

@@ -41,11 +41,13 @@ to whatever window is behind it.  This can also be changed after window
 creation with the matching [window attribute](@ref GLFW_MOUSE_PASSTHROUGH_attrib).
 
 
-#### Ability to get a window's title {#features_34_get_window_title}
+#### Ability to get window title {#features_34_window_title}
 
-GLFW now supports retrieving a window's title with the @ref glfwGetWindowTitle
+GLFW now supports querying the title of a window with the @ref glfwGetWindowTitle
 function.
 
+For more information see @ref window_title.
+
 
 #### Wayland libdecor decorations {#wayland_libdecor_34}
 

docs/window.md

@@ -897,7 +897,7 @@ glfwGetWindowPos(window, &xpos, &ypos);
 
 All GLFW windows have a title, although undecorated or full screen windows may
 not display it or only display it in a task bar or similar interface.  You can
-set a UTF-8 encoded window title with @ref glfwSetWindowTitle.
+set a new UTF-8 encoded window title with @ref glfwSetWindowTitle.
 
 ```c
 glfwSetWindowTitle(window, "My Window");
@@ -919,16 +919,12 @@ If you are using C++11 or C11, you can use a UTF-8 string literal.
 glfwSetWindowTitle(window, u8"This is always a UTF-8 string");
 ```
 
-The window title can be retrieved with @ref glfwGetWindowTitle.
+The current window title can be queried with @ref glfwGetWindowTitle.
 
 ```c
 const char* title = glfwGetWindowTitle(window);
 ```
 
-The title returned is an internally managed copy of the title set
-by @ref glfwCreateWindow or @ref glfwSetWindowTitle. It does not
-include any additional text which may be appended by the platform.
-
 ### Window icon {#window_icon}
 
 Decorated windows have icons on some platforms.  You can set this icon by

include/GLFW/glfw3.h

@@ -3305,26 +3305,34 @@ GLFWAPI int glfwWindowShouldClose(GLFWwindow* window);
  */
 GLFWAPI void glfwSetWindowShouldClose(GLFWwindow* window, int value);
 
-/*! @brief Retrieves the title of the specified window.
+/*! @brief Returns the title of the specified window.
  *
- *  This function gets the window title, encoded as UTF-8, of the specified
+ *  This function returns the window title, encoded as UTF-8, of the specified
- *  window.
+ *  window.  This is the title set previously by @ref glfwCreateWindow
+ *  or @ref glfwSetWindowTitle.
  *
  *  @param[in] window The window to query.
- *  @return A copy of the UTF-8 encoded window title, as set by glfwCreateWindow
+ *  @return The UTF-8 encoded window title, or `NULL` if an
- *  or glfwSetWindowTitle, or NULL if there is an error.
+ *  [error](@ref error_handling) occurred.
  *
- *  @errors Possible errors include @ref GLFW_NOT_INITIALIZED
+ *  @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
+ *
+ *  @remark The returned title is currently a copy of the title last set by @ref
+ *  glfwCreateWindow or @ref glfwSetWindowTitle.  It does not include any
+ *  additional text which may be appended by the platform or another program.
  *
  *  @pointer_lifetime The returned string is allocated and freed by GLFW.  You
  *  should not free it yourself.  It is valid until the next call to @ref
- *  glfwSetWindowTitle, or until the library is terminated.
+ *  glfwGetWindowTitle or @ref glfwSetWindowTitle, or until the library is
+ *  terminated.
  *
  *  @thread_safety This function must only be called from the main thread.
  *
  *  @sa @ref window_title
  *  @sa @ref glfwSetWindowTitle
  *
+ *  @since Added in version 3.4.
+ *
  *  @ingroup window
  */
 GLFWAPI const char* glfwGetWindowTitle(GLFWwindow* window);
@@ -3346,6 +3354,7 @@ GLFWAPI const char* glfwGetWindowTitle(GLFWwindow* window);
  *  @thread_safety This function must only be called from the main thread.
  *
  *  @sa @ref window_title
+ *  @sa @ref glfwGetWindowTitle
  *
  *  @since Added in version 1.0.
  *  @glfw3 Added window handle parameter.