Documentation updates.

include/GL/glfw3.h

@@ -954,7 +954,7 @@ GLFWAPI void glfwGetDesktopMode(GLFWvidmode* mode);
 
 /*! @brief Sets the system gamma ramp to one generated from the specified
  *  exponent.
- *  @param[in] The desired exponent.
+ *  @param[in] gamma The desired exponent.
  *  @ingroup gamma
  */
 GLFWAPI void glfwSetGamma(float gamma);
@@ -1048,7 +1048,8 @@ GLFWAPI void glfwDefaultWindowHints(void);
  *  used by the OpenGL context.
  *
  *  The @ref GLFW_RESIZABLE hint specifies whether the window will be resizable
- *  by the user.  This hint is ignored for fullscreen windows.
+ *  by the user.  The window will still be resizable using the @ref
+ *  glfwSetWindowSize function.  This hint is ignored for fullscreen windows.
  *
  *  The @ref GLFW_VISIBLE hint specifies whether the window will be initially
  *  visible.  This hint is ignored for fullscreen windows.
@@ -1059,7 +1060,9 @@ GLFWAPI void glfwDefaultWindowHints(void);
  *  Some window hints are hard constraints.  These must match the available
  *  capabilities @em exactly for window and context creation to succeed.  Hints
  *  that are not hard constraints are matched as closely as possible, but the
- *  resulting window and context may differ from what these hints requested.
+ *  resulting window and context may differ from what these hints requested.  To
+ *  find out the actual properties of the created window and context, use the
+ *  @ref glfwGetWindowParam function.
  *
  *  The following window hints are hard constraints:
  *  @arg @ref GLFW_STEREO
@@ -1297,6 +1300,8 @@ GLFWAPI void glfwSetWindowPosCallback(GLFWwindow window, GLFWwindowposfun cbfun)
  *  @param[in] cbfun The new callback, or @c NULL to remove the currently set
  *  callback.
  *  @ingroup window
+ *
+ *  This callback is called when the window is resized.
  */
 GLFWAPI void glfwSetWindowSizeCallback(GLFWwindow window, GLFWwindowsizefun cbfun);
 
@@ -1305,6 +1310,14 @@ GLFWAPI void glfwSetWindowSizeCallback(GLFWwindow window, GLFWwindowsizefun cbfu
  *  @param[in] cbfun The new callback, or @c NULL to remove the currently set
  *  callback.
  *  @ingroup window
+ *
+ *  This callback is called when the user attempts to close the window, i.e.
+ *  clicks the window's close widget or, on Mac OS X, selects @b Quit from the
+ *  application menu.  Calling @ref glfwDestroyWindow does not cause this
+ *  callback to be called.
+ *
+ *  The return value of the close callback becomes the new value of the @ref
+ *  GLFW_CLOSE_REQUESTED window parameter.
  */
 GLFWAPI void glfwSetWindowCloseCallback(GLFWwindow window, GLFWwindowclosefun cbfun);
 
@@ -1313,6 +1326,13 @@ GLFWAPI void glfwSetWindowCloseCallback(GLFWwindow window, GLFWwindowclosefun cb
  *  @param[in] cbfun The new callback, or @c NULL to remove the currently set
  *  callback.
  *  @ingroup window
+ *
+ *  This callback is called when the client area of the window needs to be
+ *  redrawn, for example if the window has been exposed after having been
+ *  covered by another window.
+ *
+ *  @note On compositing window systems such as Mac OS X, where the window
+ *  contents are saved off-screen, this callback may never be called.
  */
 GLFWAPI void glfwSetWindowRefreshCallback(GLFWwindow window, GLFWwindowrefreshfun cbfun);
 
@@ -1321,6 +1341,8 @@ GLFWAPI void glfwSetWindowRefreshCallback(GLFWwindow window, GLFWwindowrefreshfu
  *  @param[in] cbfun The new callback, or @c NULL to remove the currently set
  *  callback.
  *  @ingroup window
+ *
+ *  This callback is called when the window gains or loses focus.
  */
 GLFWAPI void glfwSetWindowFocusCallback(GLFWwindow window, GLFWwindowfocusfun cbfun);
 
@@ -1329,6 +1351,8 @@ GLFWAPI void glfwSetWindowFocusCallback(GLFWwindow window, GLFWwindowfocusfun cb
  *  @param[in] cbfun The new callback, or @c NULL to remove the currently set
  *  callback.
  *  @ingroup window
+ *
+ *  This callback is called when the window is iconified or restored.
  */
 GLFWAPI void glfwSetWindowIconifyCallback(GLFWwindow window, GLFWwindowiconifyfun cbfun);
 
@@ -1427,7 +1451,7 @@ GLFWAPI void glfwGetScrollOffset(GLFWwindow window, double* xoffset, double* yof
  *  set callback.
  *  @ingroup input
  *
- *  @note The key callback deals with physical keys, with @link keys tokens
+ *  @remarks The key callback deals with physical keys, with @link keys tokens
  *  @endlink named after their use on the standard US keyboard layout.  If you
  *  want to input text, use the Unicode character callback instead.
  */
@@ -1438,8 +1462,8 @@ GLFWAPI void glfwSetKeyCallback(GLFWwindow window, GLFWkeyfun cbfun);
  *  the currently set callback.
  *  @ingroup input
  *
- *  @note The Unicode character callback is for text input.  If you want to know
- *  whether a specific key was pressed or released, use the key callback.
+ *  @remarks The Unicode character callback is for text input.  If you want to
+ *  know whether a specific key was pressed or released, use the key callback.
  */
 GLFWAPI void glfwSetCharCallback(GLFWwindow window, GLFWcharfun cbfun);
 
@@ -1454,6 +1478,9 @@ GLFWAPI void glfwSetMouseButtonCallback(GLFWwindow window, GLFWmousebuttonfun cb
  *  @param[in] cbfun The new cursor position callback, or @c NULL to remove the
  *  currently set callback.
  *  @ingroup input
+ *
+ *  @remarks The position is relative to the upper-left corner of the client
+ *  area of the window.
  */
 GLFWAPI void glfwSetCursorPosCallback(GLFWwindow window, GLFWcursorposfun cbfun);
 
@@ -1506,6 +1533,8 @@ GLFWAPI int glfwGetJoystickButtons(int joy, unsigned char* buttons, int numbutto
  *  @param[in] string A UTF-8 encoded string.
  *  @ingroup clipboard
  *
+ *  @note This function may only be called from the main thread.
+ *
  *  @sa glfwGetClipboardString
  */
 GLFWAPI void glfwSetClipboardString(GLFWwindow window, const char* string);
@@ -1516,6 +1545,8 @@ GLFWAPI void glfwSetClipboardString(GLFWwindow window, const char* string);
  *  if that format was unavailable.
  *  @ingroup clipboard
  *
+ *  @note This function may only be called from the main thread.
+ *
  *  @note The returned string is valid only until the next call to @ref
  *  glfwGetClipboardString or @ref glfwSetClipboardString.
  *