From 071a049f071b64713c2fd6cd709982e6815a4f24 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Camilla=20L=C3=B6wy?= <elmindreda@glfw.org>
Date: Tue, 28 Feb 2017 22:29:10 +0100
Subject: [PATCH] Documentation work

[ci skip]
---
 include/GLFW/glfw3.h | 22 +++++++++++++++-------
 src/internal.h       | 15 ++++++++++-----
 2 files changed, 25 insertions(+), 12 deletions(-)

diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h
index 3fd04cdb..99732a54 100644
--- a/include/GLFW/glfw3.h
+++ b/include/GLFW/glfw3.h
@@ -3335,15 +3335,19 @@ GLFWAPI void glfwSetInputMode(GLFWwindow* window, int mode, int value);
 
 /*! @brief Returns the localized name of the specified printable key.
  *
- *  This function returns the localized name of the specified printable key.
- *  This is intended for displaying key bindings to the user.
+ *  This function returns the name of the specified printable key.  This is
+ *  typically the character that key would produce without any modifier keys,
+ *  intended for displaying key bindings to the user.
  *
- *  If the key is `GLFW_KEY_UNKNOWN`, the scancode is used instead, otherwise
- *  the scancode is ignored.  If a non-printable key or (if the key is
- *  `GLFW_KEY_UNKNOWN`) a scancode that maps to a non-printable key is
- *  specified, this function returns `NULL`.          
+ *  __Do not use this function__ for [text input](@ref input_char).  You will
+ *  break text input for many languages even if it happens to work for yours.
  *
- *  This behavior allows you to pass in the arguments passed to the
+ *  If the key is `GLFW_KEY_UNKNOWN`, the scancode is used to identify the key,
+ *  otherwise the scancode is ignored.  If you specify a non-printable key, or
+ *  `GLFW_KEY_UNKNOWN` and a scancode that maps to a non-printable key, this
+ *  function returns `NULL` but does not emit an error.
+ *
+ *  This behavior allows you to always pass in the arguments in the
  *  [key callback](@ref input_key) without modification.
  *
  *  The printable keys are:
@@ -3369,6 +3373,10 @@ GLFWAPI void glfwSetInputMode(GLFWwindow* window, int mode, int value);
  *  - `GLFW_KEY_KP_ADD`
  *  - `GLFW_KEY_KP_EQUAL`
  *
+ *  Names for printable keys depend on keyboard layout, while names for
+ *  non-printable keys are the same across layouts but depend on the application
+ *  language and should be localized along with other user interface text.
+ *
  *  @param[in] key The key to query, or `GLFW_KEY_UNKNOWN`.
  *  @param[in] scancode The scancode of the key to query.
  *  @return The localized name of the key, or `NULL`.
diff --git a/src/internal.h b/src/internal.h
index 3688cbbd..e026e721 100644
--- a/src/internal.h
+++ b/src/internal.h
@@ -814,7 +814,8 @@ void _glfwInputJoystickButton(int jid, int button, char value);
 // Utility functions
 //========================================================================
 
-/*! @ingroup utility
+/*! @brief Chooses the video mode most closely matching the desired one.
+ *  @ingroup utility
  */
 const GLFWvidmode* _glfwChooseVideoMode(_GLFWmonitor* monitor,
                                         const GLFWvidmode* desired);
@@ -869,11 +870,13 @@ GLFWbool _glfwRefreshContextAttribs(const _GLFWctxconfig* ctxconfig);
  */
 GLFWbool _glfwIsValidContextConfig(const _GLFWctxconfig* ctxconfig);
 
-/*! @ingroup utility
+/*! @brief Allocates red, green and blue value arrays of the specified size.
+ *  @ingroup utility
  */
 void _glfwAllocGammaArrays(GLFWgammaramp* ramp, unsigned int size);
 
-/*! @ingroup utility
+/*! @brief Frees the red, green and blue value arrays and clears the struct.
+ *  @ingroup utility
  */
 void _glfwFreeGammaArrays(GLFWgammaramp* ramp);
 
@@ -892,11 +895,13 @@ _GLFWmonitor* _glfwAllocMonitor(const char* name, int widthMM, int heightMM);
   */
 void _glfwFreeMonitor(_GLFWmonitor* monitor);
 
-/*! @ingroup utility
+/*! @brief Returns an available joystick object with arrays and name allocated.
+ *  @ingroup utility
   */
 _GLFWjoystick* _glfwAllocJoystick(const char* name, int axisCount, int buttonCount);
 
-/*! @ingroup utility
+/*! @brief Frees arrays and name and flags the joystick object as unused.
+ *  @ingroup utility
   */
 void _glfwFreeJoystick(_GLFWjoystick* js);