Documentation work

[ci skip]
This commit is contained in:
Camilla Löwy 2017-08-04 01:00:36 +02:00
parent f95c9d1bf3
commit 5bc1c38159
2 changed files with 31 additions and 20 deletions

View File

@ -112,7 +112,7 @@ Set this with @ref glfwInitHintString.
@subsubsection init_hints_values Supported and default values @subsubsection init_hints_values Supported and default values
Init hint | Default value | Supported values Initialization hint | Default value | Supported values
------------------------------- | ------------- | ---------------- ------------------------------- | ------------- | ----------------
@ref GLFW_JOYSTICK_HAT_BUTTONS | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE` @ref GLFW_JOYSTICK_HAT_BUTTONS | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE`
@ref GLFW_COCOA_CHDIR_RESOURCES | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE` @ref GLFW_COCOA_CHDIR_RESOURCES | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE`
@ -388,8 +388,9 @@ Undocumented behavior, i.e. behavior that is not described in the documentation,
may change at any time until it is documented. may change at any time until it is documented.
If the reference documentation and the implementation differ, the reference If the reference documentation and the implementation differ, the reference
documentation is correct and the implementation will be fixed in the next documentation will almost always take precedence and the implementation will be
release. fixed in the next release. The reference documentation will also take
precedence over anything stated in a guide.
@subsection event_order Event order @subsection event_order Event order

View File

@ -4203,6 +4203,10 @@ GLFWAPI GLFWdropfun glfwSetDropCallback(GLFWwindow* window, GLFWdropfun cbfun);
* *
* This function returns whether the specified joystick is present. * This function returns whether the specified joystick is present.
* *
* There is no need to call this function before other functions that accept
* a joystick ID, as they all check for presence before performing any other
* work.
*
* @param[in] jid The [joystick](@ref joysticks) to query. * @param[in] jid The [joystick](@ref joysticks) to query.
* @return `GLFW_TRUE` if the joystick is present, or `GLFW_FALSE` otherwise. * @return `GLFW_TRUE` if the joystick is present, or `GLFW_FALSE` otherwise.
* *
@ -4225,8 +4229,8 @@ GLFWAPI int glfwJoystickPresent(int jid);
* Each element in the array is a value between -1.0 and 1.0. * Each element in the array is a value between -1.0 and 1.0.
* *
* If the specified joystick is not present this function will return `NULL` * If the specified joystick is not present this function will return `NULL`
* but will not generate an error. Call @ref glfwJoystickPresent to check * but will not generate an error. This can be used instead of first calling
* device presence. * @ref glfwJoystickPresent.
* *
* @param[in] jid The [joystick](@ref joysticks) to query. * @param[in] jid The [joystick](@ref joysticks) to query.
* @param[out] count Where to store the number of axis values in the returned * @param[out] count Where to store the number of axis values in the returned
@ -4265,8 +4269,8 @@ GLFWAPI const float* glfwGetJoystickAxes(int jid, int* count);
* GLFW_JOYSTICK_HAT_BUTTONS init hint before initialization. * GLFW_JOYSTICK_HAT_BUTTONS init hint before initialization.
* *
* If the specified joystick is not present this function will return `NULL` * If the specified joystick is not present this function will return `NULL`
* but will not generate an error. Call @ref glfwJoystickPresent to check * but will not generate an error. This can be used instead of first calling
* device presence. * @ref glfwJoystickPresent.
* *
* @param[in] jid The [joystick](@ref joysticks) to query. * @param[in] jid The [joystick](@ref joysticks) to query.
* @param[out] count Where to store the number of button states in the returned * @param[out] count Where to store the number of button states in the returned
@ -4322,8 +4326,8 @@ GLFWAPI const unsigned char* glfwGetJoystickButtons(int jid, int* count);
* @endcode * @endcode
* *
* If the specified joystick is not present this function will return `NULL` * If the specified joystick is not present this function will return `NULL`
* but will not generate an error. Call @ref glfwJoystickPresent to check * but will not generate an error. This can be used instead of first calling
* device presence. * @ref glfwJoystickPresent.
* *
* @param[in] jid The [joystick](@ref joysticks) to query. * @param[in] jid The [joystick](@ref joysticks) to query.
* @param[out] count Where to store the number of hat states in the returned * @param[out] count Where to store the number of hat states in the returned
@ -4357,8 +4361,8 @@ GLFWAPI const unsigned char* glfwGetJoystickHats(int jid, int* count);
* yourself. * yourself.
* *
* If the specified joystick is not present this function will return `NULL` * If the specified joystick is not present this function will return `NULL`
* but will not generate an error. Call @ref glfwJoystickPresent to check * but will not generate an error. This can be used instead of first calling
* device presence. * @ref glfwJoystickPresent.
* *
* @param[in] jid The [joystick](@ref joysticks) to query. * @param[in] jid The [joystick](@ref joysticks) to query.
* @return The UTF-8 encoded name of the joystick, or `NULL` if the joystick * @return The UTF-8 encoded name of the joystick, or `NULL` if the joystick
@ -4387,9 +4391,13 @@ GLFWAPI const char* glfwGetJoystickName(int jid);
* hexadecimal string, of the specified joystick. The returned string is * hexadecimal string, of the specified joystick. The returned string is
* allocated and freed by GLFW. You should not free it yourself. * allocated and freed by GLFW. You should not free it yourself.
* *
* The GUID is what connects a joystick to a gamepad mapping. A connected
* joystick will always have a GUID even if there is no gamepad mapping
* assigned to it.
*
* If the specified joystick is not present this function will return `NULL` * If the specified joystick is not present this function will return `NULL`
* but will not generate an error. Call @ref glfwJoystickPresent to check * but will not generate an error. This can be used instead of first calling
* device presence. * @ref glfwJoystickPresent.
* *
* The GUID uses the format introduced in SDL 2.0.5. This GUID tries to * The GUID uses the format introduced in SDL 2.0.5. This GUID tries to
* uniquely identify the make and model of a joystick but does not identify * uniquely identify the make and model of a joystick but does not identify
@ -4425,7 +4433,8 @@ GLFWAPI const char* glfwGetJoystickGUID(int jid);
* *
* If the specified joystick is present but does not have a gamepad mapping * If the specified joystick is present but does not have a gamepad mapping
* this function will return `GLFW_FALSE` but will not generate an error. Call * this function will return `GLFW_FALSE` but will not generate an error. Call
* @ref glfwJoystickPresent to only check device presence. * @ref glfwJoystickPresent to check if a joystick is present regardless of
* whether it has a mapping.
* *
* @param[in] jid The [joystick](@ref joysticks) to query. * @param[in] jid The [joystick](@ref joysticks) to query.
* @return `GLFW_TRUE` if a joystick is both present and has a gamepad mapping, * @return `GLFW_TRUE` if a joystick is both present and has a gamepad mapping,
@ -4514,8 +4523,9 @@ GLFWAPI int glfwUpdateGamepadMappings(const char* string);
* gamepad mapping assigned to the specified joystick. * gamepad mapping assigned to the specified joystick.
* *
* If the specified joystick is not present or does not have a gamepad mapping * If the specified joystick is not present or does not have a gamepad mapping
* this function will return `NULL` but will not generate an error. Call @ref * this function will return `NULL` but will not generate an error. Call
* glfwJoystickIsGamepad to check whether it is present and has a gamepad mapping. * @ref glfwJoystickPresent to check whether it is present regardless of
* whether it has a mapping.
* *
* @param[in] jid The [joystick](@ref joysticks) to query. * @param[in] jid The [joystick](@ref joysticks) to query.
* @return The UTF-8 encoded name of the gamepad, or `NULL` if the * @return The UTF-8 encoded name of the gamepad, or `NULL` if the
@ -4542,10 +4552,10 @@ GLFWAPI const char* glfwGetGamepadName(int jid);
* This function retrives the state of the specified joystick remapped to * This function retrives the state of the specified joystick remapped to
* an Xbox-like gamepad. * an Xbox-like gamepad.
* *
* If the specified joystick is not present this function will return * If the specified joystick is not present or does not have a gamepad mapping
* `GLFW_FALSE` but will not generate an error. Call @ref * this function will return `GLFW_FALSE` but will not generate an error. Call
* glfwJoystickIsGamepad to check whether it is present and has a gamepad * @ref glfwJoystickPresent to check whether it is present regardless of
* mapping. * whether it has a mapping.
* *
* The Guide button may not be available for input as it is often hooked by the * The Guide button may not be available for input as it is often hooked by the
* system or the Steam client. * system or the Steam client.