Documentation work.

include/GLFW/glfw3.h

@@ -951,8 +951,8 @@ GLFWAPI const char* glfwGetVersionString(void);
  *
  *  @param[in] cbfun The new callback, or `NULL` to remove the currently set
  *  callback.
- *
- *  @return The previously set callback, or `NULL` if an error occurred.
+ *  @return The previously set callback, or `NULL` if no callback was set or an
+ *  error occurred.
  *
  *  @remarks This function may be called before @ref glfwInit.
  *
@@ -974,8 +974,8 @@ GLFWAPI GLFWerrorfun glfwSetErrorCallback(GLFWerrorfun cbfun);
  *  This function returns an array of handles for all currently connected
  *  monitors.
  *
- *  @param[out] count The size of the returned array, or zero if an error
- *  occurred.
+ *  @param[out] count Where to store the size of the returned array.  This is
+ *  set to zero if an error occurred.
  *  @return An array of monitor handles, or `NULL` if an error occurred.
  *
  *  @note The returned array is allocated and freed by GLFW.  You should not
@@ -1010,8 +1010,8 @@ GLFWAPI GLFWmonitor* glfwGetPrimaryMonitor(void);
  *  corner of the specified monitor.
  *
  *  @param[in] monitor The monitor to query.
- *  @param[out] xpos The monitor x-coordinate.
- *  @param[out] ypos The monitor y-coordinate.
+ *  @param[out] xpos Where to store the monitor x-coordinate, or `NULL`.
+ *  @param[out] ypos Where to store the monitor y-coordinate, or `NULL`.
  *
  *  @ingroup monitor
  */
@@ -1023,8 +1023,10 @@ GLFWAPI void glfwGetMonitorPos(GLFWmonitor* monitor, int* xpos, int* ypos);
  *  specified monitor.
  *
  *  @param[in] monitor The monitor to query.
- *  @param[out] width The width, in mm, of the monitor's display
- *  @param[out] height The height, in mm, of the monitor's display.
+ *  @param[out] width Where to store the width, in mm, of the monitor's display
+ *  area, or `NULL`.
+ *  @param[out] height Where to store the height, in mm, of the monitor's
+ *  display area, or `NULL`.
  *
  *  @note Some operating systems do not provide accurate information, either
  *  because the monitor's EDID data is incorrect, or because the driver does not
@@ -1058,7 +1060,8 @@ GLFWAPI const char* glfwGetMonitorName(GLFWmonitor* monitor);
  *
  *  @param[in] cbfun The new callback, or `NULL` to remove the currently set
  *  callback.
- *  @return The previously set callback, or `NULL` if an error occurred.
+ *  @return The previously set callback, or `NULL` if no callback was set or an
+ *  error occurred.
  *
  *  @bug This callback is not yet called on monitor configuration changes.
  *
@@ -1074,8 +1077,8 @@ GLFWAPI GLFWmonitorfun glfwSetMonitorCallback(GLFWmonitorfun cbfun);
  *  product of width and height).
  *
  *  @param[in] monitor The monitor to query.
- *  @param[out] count The number of video modes in the returned array, or zero
- *  if an error occurred.
+ *  @param[out] count Where to store the number of video modes in the returned
+ *  array.  This is set to zero if an error occurred.
  *  @return An array of video modes, or `NULL` if an error occurred.
  *
  *  @note The returned array is allocated and freed by GLFW.  You should not
@@ -1125,7 +1128,7 @@ GLFWAPI void glfwSetGamma(GLFWmonitor* monitor, float gamma);
  *  This function retrieves the current gamma ramp of the specified monitor.
  *
  *  @param[in] monitor The monitor to query.
- *  @return The current gamma ramp.
+ *  @return The current gamma ramp, or `NULL` if an error occurred.
  *
  *  @note The value arrays of the returned ramp are allocated and freed by GLFW.
  *  You should not free them yourself.
@@ -1199,6 +1202,12 @@ GLFWAPI void glfwWindowHint(int target, int hint);
  *  attributes of the created window and context, use queries like @ref
  *  glfwGetWindowAttrib and @ref glfwGetWindowSize.
  *
+ *  To create the window at a specific position, make it initially invisible
+ *  using the `GLFW_VISIBLE` window hint, set its position and then show it.
+ *
+ *  If a fullscreen window is active, the screensaver is prohibited from
+ *  starting.
+ *
  *  @param[in] width The desired width, in screen coordinates, of the window.
  *  This must be greater than zero.
  *  @param[in] height The desired height, in screen coordinates, of the window.
@@ -1210,13 +1219,6 @@ GLFWAPI void glfwWindowHint(int target, int hint);
  *  to not share resources.
  *  @return The handle of the created window, or `NULL` if an error occurred.
  *
- *  @remarks To create the window at a specific position, make it initially
- *  invisible using the `GLFW_VISIBLE` window hint, set its position and then
- *  show it.
- *
- *  @remarks If a fullscreen window is active, the screensaver is prohibited
- *  from starting.
- *
  *  @remarks **Windows:** If the executable has an icon resource named
  *  `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.
@@ -1302,10 +1304,10 @@ GLFWAPI void glfwSetWindowTitle(GLFWwindow* window, const char* title);
  *  upper-left corner of the client area of the specified window.
  *
  *  @param[in] window The window to query.
- *  @param[out] xpos The x-coordinate of the upper-left corner of the client area.
- *  @param[out] ypos The y-coordinate of the upper-left corner of the client area.
- *
- *  @remarks Either or both coordinate arguments may be `NULL`.
+ *  @param[out] xpos Where to store the x-coordinate of the upper-left corner of
+ *  the client area, or `NULL`.
+ *  @param[out] ypos Where to store the y-coordinate of the upper-left corner of
+ *  the client area, or `NULL`.
  *
  *  @sa glfwSetWindowPos
  *
@@ -1318,16 +1320,16 @@ GLFWAPI void glfwGetWindowPos(GLFWwindow* window, int* xpos, int* ypos);
  *  This function sets the position, in screen coordinates, of the upper-left
  *  corner of the client area of the window.
  *
- *  If it is a full screen window, this function does nothing.
+ *  If the specified window is a full screen window, this function does nothing.
+ *
+ *  If you wish to set an initial window position you should create a hidden
+ *  window (using @ref glfwWindowHint and `GLFW_VISIBLE`), set its position and
+ *  then show it.
  *
  *  @param[in] window The window to query.
  *  @param[in] xpos The x-coordinate of the upper-left corner of the client area.
  *  @param[in] ypos The y-coordinate of the upper-left corner of the client area.
  *
- *  @remarks  If you wish to set an initial window position you should create
- *  a hidden window (using @ref glfwWindowHint and `GLFW_VISIBLE`), set its
- *  position and then show it.
- *
  *  @note It is very rarely a good idea to move an already visible window, as it
  *  will confuse and annoy the user.
  *
@@ -1351,8 +1353,10 @@ GLFWAPI void glfwSetWindowPos(GLFWwindow* window, int xpos, int ypos);
  *  of the specified window.
  *
  *  @param[in] window The window whose size to retrieve.
- *  @param[out] width The width of the client area.
- *  @param[out] height The height of the client area.
+ *  @param[out] width Where to store the width, in screen coordinates, of the
+ *  client area, or `NULL`.
+ *  @param[out] height Where to store the height, in screen coordinates, of the
+ *  client area, or `NULL`.
  *
  *  @sa glfwSetWindowSize
  *
@@ -1390,8 +1394,10 @@ GLFWAPI void glfwSetWindowSize(GLFWwindow* window, int width, int height);
  *  specified window.
  *
  *  @param[in] window The window whose framebuffer to query.
- *  @param[out] width The width of the framebuffer.
- *  @param[out] height The height of the framebuffer.
+ *  @param[out] width Where to store the width, in pixels, of the framebuffer,
+ *  or `NULL`.
+ *  @param[out] height Where to store the height, in pixels, of the framebuffer,
+ *  or `NULL`.
  *
  *  @sa glfwSetFramebufferSizeCallback
  *
@@ -1528,8 +1534,8 @@ GLFWAPI void* glfwGetWindowUserPointer(GLFWwindow* window);
  *  @param[in] window The window whose callback to set.
  *  @param[in] cbfun The new callback, or `NULL` to remove the currently set
  *  callback.
- *
- *  @return The previously set callback, or `NULL` if an error occurred.
+ *  @return The previously set callback, or `NULL` if no callback was set or an
+ *  error occurred.
  *
  *  @ingroup window
  */
@@ -1544,8 +1550,8 @@ GLFWAPI GLFWwindowposfun glfwSetWindowPosCallback(GLFWwindow* window, GLFWwindow
  *  @param[in] window The window whose callback to set.
  *  @param[in] cbfun The new callback, or `NULL` to remove the currently set
  *  callback.
- *
- *  @return The previously set callback, or `NULL` if an error occurred.
+ *  @return The previously set callback, or `NULL` if no callback was set or an
+ *  error occurred.
  *
  *  @ingroup window
  */
@@ -1560,14 +1566,13 @@ GLFWAPI GLFWwindowsizefun glfwSetWindowSizeCallback(GLFWwindow* window, GLFWwind
  *  The close flag is set before this callback is called, but you can modify it
  *  at any time with @ref glfwSetWindowShouldClose.
  *
+ *  The close callback is not triggered by @ref glfwDestroyWindow.
+ *
  *  @param[in] window The window whose callback to set.
  *  @param[in] cbfun The new callback, or `NULL` to remove the currently set
  *  callback.
- *
- *  @remarks Calling @ref glfwDestroyWindow does not cause this callback to be
- *  called.
- *
- *  @return The previously set callback, or `NULL` if an error occurred.
+ *  @return The previously set callback, or `NULL` if no callback was set or an
+ *  error occurred.
  *
  *  @remarks **Mac OS X:** Selecting Quit from the application menu will
  *  trigger the close callback for all windows.
@@ -1589,7 +1594,8 @@ GLFWAPI GLFWwindowclosefun glfwSetWindowCloseCallback(GLFWwindow* window, GLFWwi
  *  @param[in] window The window whose callback to set.
  *  @param[in] cbfun The new callback, or `NULL` to remove the currently set
  *  callback.
- *  @return The previously set callback, or `NULL` if an error occurred.
+ *  @return The previously set callback, or `NULL` if no callback was set or an
+ *  error occurred.
  *
  *  @note On compositing window systems such as Aero, Compiz or Aqua, where the
  *  window contents are saved off-screen, this callback may be called only very
@@ -1612,8 +1618,8 @@ GLFWAPI GLFWwindowrefreshfun glfwSetWindowRefreshCallback(GLFWwindow* window, GL
  *  @param[in] window The window whose callback to set.
  *  @param[in] cbfun The new callback, or `NULL` to remove the currently set
  *  callback.
- *
- *  @return The previously set callback, or `NULL` if an error occurred.
+ *  @return The previously set callback, or `NULL` if no callback was set or an
+ *  error occurred.
  *
  *  @ingroup window
  */
@@ -1627,8 +1633,8 @@ GLFWAPI GLFWwindowfocusfun glfwSetWindowFocusCallback(GLFWwindow* window, GLFWwi
  *  @param[in] window The window whose callback to set.
  *  @param[in] cbfun The new callback, or `NULL` to remove the currently set
  *  callback.
- *
- *  @return The previously set callback, or `NULL` if an error occurred.
+ *  @return The previously set callback, or `NULL` if no callback was set or an
+ *  error occurred.
  *
  *  @ingroup window
  */
@@ -1642,8 +1648,8 @@ GLFWAPI GLFWwindowiconifyfun glfwSetWindowIconifyCallback(GLFWwindow* window, GL
  *  @param[in] window The window whose callback to set.
  *  @param[in] cbfun The new callback, or `NULL` to remove the currently set
  *  callback.
- *
- *  @return The previously set callback, or `NULL` if an error occurred.
+ *  @return The previously set callback, or `NULL` if no callback was set or an
+ *  error occurred.
  *
  *  @ingroup window
  */
@@ -1655,12 +1661,12 @@ GLFWAPI GLFWframebuffersizefun glfwSetFramebufferSizeCallback(GLFWwindow* window
  *  and then returns immediately.  Processing events will cause the window and
  *  input callbacks associated with those events to be called.
  *
+ *  This function is not required for joystick input to work.
+ *
  *  @par New in GLFW 3
  *  This function is no longer called by @ref glfwSwapBuffers.  You need to call
  *  it or @ref glfwWaitEvents yourself.
  *
- *  @remarks This function is not required for joystick input to work.
- *
  *  @note This function may only be called from the main thread.
  *
  *  @note This function may not be called from a callback.
@@ -1686,7 +1692,7 @@ GLFWAPI void glfwPollEvents(void);
  *  without a callback having been called even if you are monitoring all
  *  callbacks.
  *
- *  @remarks This function is not required for joystick input to work.
+ *  This function is not required for joystick input to work.
  *
  *  @note This function may only be called from the main thread.
  *
@@ -1802,10 +1808,10 @@ GLFWAPI int glfwGetMouseButton(GLFWwindow* window, int button);
  *  coordinates, but fails for negative ones.
  *
  *  @param[in] window The desired window.
- *  @param[out] xpos The cursor x-coordinate, relative to the left edge of the
- *  client area, or `NULL`.
- *  @param[out] ypos The cursor y-coordinate, relative to the to top edge of the
- *  client area, or `NULL`.
+ *  @param[out] xpos Where to store the cursor x-coordinate, relative to the
+ *  left edge of the client area, or `NULL`.
+ *  @param[out] ypos Where to store the cursor y-coordinate, relative to the to
+ *  top edge of the client area, or `NULL`.
  *
  *  @sa glfwSetCursorPos
  *
@@ -1842,8 +1848,8 @@ GLFWAPI void glfwSetCursorPos(GLFWwindow* window, double xpos, double ypos);
  *
  *  The key functions deal with physical keys, with layout independent
  *  [key tokens](@ref keys) named after their values in the standard US keyboard
- *  layout.  If you want to input text, use the [character callback](@ref
- *  glfwSetCharCallback) instead.
+ *  layout.  If you want to input text, use the
+ *  [character callback](@ref glfwSetCharCallback) instead.
  *
  *  When a window loses focus, it will generate synthetic key release events
  *  for all pressed keys.  You can tell these events from user-generated events
@@ -1854,8 +1860,8 @@ GLFWAPI void glfwSetCursorPos(GLFWwindow* window, double xpos, double ypos);
  *  @param[in] window The window whose callback to set.
  *  @param[in] cbfun The new key callback, or `NULL` to remove the currently
  *  set callback.
- *
- *  @return The previously set callback, or `NULL` if an error occurred.
+ *  @return The previously set callback, or `NULL` if no callback was set or an
+ *  error occurred.
  *
  *  @ingroup input
  */
@@ -1873,8 +1879,8 @@ GLFWAPI GLFWkeyfun glfwSetKeyCallback(GLFWwindow* window, GLFWkeyfun cbfun);
  *  @param[in] window The window whose callback to set.
  *  @param[in] cbfun The new callback, or `NULL` to remove the currently set
  *  callback.
- *
- *  @return The previously set callback, or `NULL` if an error occurred.
+ *  @return The previously set callback, or `NULL` if no callback was set or an
+ *  error occurred.
  *
  *  @ingroup input
  */
@@ -1894,8 +1900,8 @@ GLFWAPI GLFWcharfun glfwSetCharCallback(GLFWwindow* window, GLFWcharfun cbfun);
  *  @param[in] window The window whose callback to set.
  *  @param[in] cbfun The new callback, or `NULL` to remove the currently set
  *  callback.
- *
- *  @return The previously set callback, or `NULL` if an error occurred.
+ *  @return The previously set callback, or `NULL` if no callback was set or an
+ *  error occurred.
  *
  *  @ingroup input
  */
@@ -1910,8 +1916,8 @@ GLFWAPI GLFWmousebuttonfun glfwSetMouseButtonCallback(GLFWwindow* window, GLFWmo
  *  @param[in] window The window whose callback to set.
  *  @param[in] cbfun The new callback, or `NULL` to remove the currently set
  *  callback.
- *
- *  @return The previously set callback, or `NULL` if an error occurred.
+ *  @return The previously set callback, or `NULL` if no callback was set or an
+ *  error occurred.
  *
  *  @ingroup input
  */
@@ -1926,8 +1932,8 @@ GLFWAPI GLFWcursorposfun glfwSetCursorPosCallback(GLFWwindow* window, GLFWcursor
  *  @param[in] window The window whose callback to set.
  *  @param[in] cbfun The new callback, or `NULL` to remove the currently set
  *  callback.
- *
- *  @return The previously set callback, or `NULL` if an error occurred.
+ *  @return The previously set callback, or `NULL` if no callback was set or an
+ *  error occurred.
  *
  *  @ingroup input
  */
@@ -1939,14 +1945,14 @@ GLFWAPI GLFWcursorenterfun glfwSetCursorEnterCallback(GLFWwindow* window, GLFWcu
  *  called when a scrolling device is used, such as a mouse wheel or scrolling
  *  area of a touchpad.
  *
+ *  The scroll callback receives all scrolling input, like that from a mouse
+ *  wheel or a touchpad scrolling area.
+ *
  *  @param[in] window The window whose callback to set.
  *  @param[in] cbfun The new scroll callback, or `NULL` to remove the currently
  *  set callback.
- *
- *  @remarks This receives all scrolling input, like that from a mouse wheel or
- *  a touchpad scrolling area.
- *
- *  @return The previously set callback, or `NULL` if an error occurred.
+ *  @return The previously set callback, or `NULL` if no callback was set or an
+ *  error occurred.
  *
  *  @ingroup input
  */
@@ -1964,9 +1970,13 @@ GLFWAPI GLFWscrollfun glfwSetScrollCallback(GLFWwindow* window, GLFWscrollfun cb
 GLFWAPI int glfwJoystickPresent(int joy);
 
 /*! @brief Returns the values of all axes of the specified joystick.
+ *
+ *  This function returns the values of all axes of the specified joystick.
+ *
  *  @param[in] joy The joystick to query.
- *  @param[out] count The size of the returned array.
- *  @return An array of axis values, or @c NULL if the joystick is not present.
+ *  @param[out] count Where to store the size of the returned array.  This is
+ *  set to zero if an error occurred.
+ *  @return An array of axis values, or `NULL` if the joystick is not present.
  *
  *  @note The returned array is allocated and freed by GLFW.  You should not
  *  free it yourself.
@@ -1979,9 +1989,13 @@ GLFWAPI int glfwJoystickPresent(int joy);
 GLFWAPI const float* glfwGetJoystickAxes(int joy, int* count);
 
 /*! @brief Returns the values of all buttons of the specified joystick.
+ *
+ *  This function returns the values of all buttons of the specified joystick.
+ *
  *  @param[in] joy The joystick to query.
- *  @param[out] count The size of the returned array.
- *  @return An array of axis values, or @c NULL if the joystick is not present.
+ *  @param[out] count Where to store the size of the returned array.  This is
+ *  set to zero if an error occurred.
+ *  @return An array of axis values, or `NULL` if the joystick is not present.
  *
  *  @note The returned array is allocated and freed by GLFW.  You should not
  *  free it yourself.
@@ -2145,18 +2159,18 @@ GLFWAPI void glfwSwapBuffers(GLFWwindow* window);
  *  returning from @ref glfwSwapBuffers.  This is sometimes called 'vertical
  *  synchronization', 'vertical retrace synchronization' or 'vsync'.
  *
- *  @param[in] interval The minimum number of screen updates to wait for
- *  until the buffers are swapped by @ref glfwSwapBuffers.
- *
- *  @remarks This function may be called from secondary threads.
- *
- *  @remarks Contexts that support either of the `WGL_EXT_swap_control_tear` and
+ *  Contexts that support either of the `WGL_EXT_swap_control_tear` and
  *  `GLX_EXT_swap_control_tear` extensions also accept negative swap intervals,
  *  which allow the driver to swap even if a frame arrives a little bit late.
  *  You can check for the presence of these extensions using @ref
  *  glfwExtensionSupported.  For more information about swap tearing, see the
  *  extension specifications.
  *
+ *  @param[in] interval The minimum number of screen updates to wait for
+ *  until the buffers are swapped by @ref glfwSwapBuffers.
+ *
+ *  @remarks This function may be called from secondary threads.
+ *
  *  @note Some GPU drivers do not honor the requested swap interval, either
  *  because of user settings that override the request or due to bugs in the
  *  driver.