From 21eabd3938e1936f215c89e83c898bc653eadf16 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Camilla=20L=C3=B6wy?= Date: Mon, 6 Feb 2017 17:31:25 +0100 Subject: [PATCH] Documentation work --- docs/CMakeLists.txt | 4 +++- include/GLFW/glfw3.h | 12 ++++++++++++ include/GLFW/glfw3native.h | 1 + src/internal.h | 38 ++++++++++++++++++++++++++------------ 4 files changed, 42 insertions(+), 13 deletions(-) diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index c030ac73..b3034dfb 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -17,7 +17,9 @@ set(glfw_DOCS_SOURCES "${GLFW_SOURCE_DIR}/docs/compat.dox") if (GLFW_DOCUMENT_INTERNALS) - list(APPEND glfw_DOCS_SOURCES "${GLFW_SOURCE_DIR}/src/internal.h") + list(APPEND glfw_DOCS_SOURCES + "${GLFW_SOURCE_DIR}/docs/internal.dox" + "${GLFW_SOURCE_DIR}/src/internal.h") endif() foreach(arg ${glfw_DOCS_SOURCES}) diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h index b0db24b7..280138b7 100644 --- a/include/GLFW/glfw3.h +++ b/include/GLFW/glfw3.h @@ -47,32 +47,38 @@ extern "C" { * For more information about how to use this file, see @ref build_include. */ /*! @defgroup context Context reference + * @brief Functions and types related to OpenGL and OpenGL ES contexts. * * This is the reference documentation for OpenGL and OpenGL ES context related * functions. For more task-oriented information, see the @ref context_guide. */ /*! @defgroup vulkan Vulkan reference + * @brief Functions and types related to Vulkan. * * This is the reference documentation for Vulkan related functions and types. * For more task-oriented information, see the @ref vulkan_guide. */ /*! @defgroup init Initialization, version and error reference + * @brief Functions and types related to initialization and error handling. * * This is the reference documentation for initialization and termination of * the library, version management and error handling. For more task-oriented * information, see the @ref intro_guide. */ /*! @defgroup input Input reference + * @brief Functions and types related to input handling. * * This is the reference documentation for input related functions and types. * For more task-oriented information, see the @ref input_guide. */ /*! @defgroup monitor Monitor reference + * @brief Functions and types related to monitors. * * This is the reference documentation for monitor related functions and types. * For more task-oriented information, see the @ref monitor_guide. */ /*! @defgroup window Window reference + * @brief Functions and types related to windows. * * This is the reference documentation for window related functions and types, * including creation, deletion and event polling. For more task-oriented @@ -292,6 +298,7 @@ extern "C" { /*! @} */ /*! @defgroup keys Keyboard keys + * @brief Keyboard key IDs. * * See [key input](@ref input_key) for how these are used. * @@ -446,6 +453,7 @@ extern "C" { /*! @} */ /*! @defgroup mods Modifier key flags + * @brief Modifier key flags. * * See [key input](@ref input_key) for how these are used. * @@ -468,6 +476,7 @@ extern "C" { /*! @} */ /*! @defgroup buttons Mouse buttons + * @brief Mouse button IDs. * * See [mouse button input](@ref input_mouse_button) for how these are used. * @@ -488,6 +497,7 @@ extern "C" { /*! @} */ /*! @defgroup joysticks Joysticks + * @brief Joystick IDs. * * See [joystick input](@ref joystick) for how these are used. * @@ -513,6 +523,7 @@ extern "C" { /*! @} */ /*! @defgroup errors Error codes + * @brief Error codes. * * See [error handling](@ref error_handling) for how these are used. * @@ -871,6 +882,7 @@ extern "C" { #define GLFW_EGL_CONTEXT_API 0x00036002 /*! @defgroup shapes Standard cursor shapes + * @brief Standard system cursor shapes. * * See [standard cursor creation](@ref cursor_standard) for how these are used. * diff --git a/include/GLFW/glfw3native.h b/include/GLFW/glfw3native.h index a3de4cad..477d0ed1 100644 --- a/include/GLFW/glfw3native.h +++ b/include/GLFW/glfw3native.h @@ -45,6 +45,7 @@ extern "C" { * more information. */ /*! @defgroup native Native access + * @brief Functions related to accessing native handles. * * **By using the native access functions you assert that you know what you're * doing and how to fix problems caused by using them. If you don't, you diff --git a/src/internal.h b/src/internal.h index e71ac171..d9b7e863 100644 --- a/src/internal.h +++ b/src/internal.h @@ -838,7 +838,7 @@ VkResult _glfwPlatformCreateWindowSurface(VkInstance instance, _GLFWwindow* wind // Event API functions //======================================================================== -/*! @brief Notifies shared code of a window focus event. +/*! @brief Notifies shared code that a window has lost or received input focus. * @param[in] window The window that received the event. * @param[in] focused `GLFW_TRUE` if the window received focus, or `GLFW_FALSE` * if it lost focus. @@ -846,7 +846,7 @@ VkResult _glfwPlatformCreateWindowSurface(VkInstance instance, _GLFWwindow* wind */ void _glfwInputWindowFocus(_GLFWwindow* window, GLFWbool focused); -/*! @brief Notifies shared code of a window movement event. +/*! @brief Notifies shared code that a window has moved. * @param[in] window The window that received the event. * @param[in] xpos The new x-coordinate of the client area of the window. * @param[in] ypos The new y-coordinate of the client area of the window. @@ -854,7 +854,7 @@ void _glfwInputWindowFocus(_GLFWwindow* window, GLFWbool focused); */ void _glfwInputWindowPos(_GLFWwindow* window, int xpos, int ypos); -/*! @brief Notifies shared code of a window resize event. +/*! @brief Notifies shared code that a window has been resized. * @param[in] window The window that received the event. * @param[in] width The new width of the client area of the window. * @param[in] height The new height of the client area of the window. @@ -862,7 +862,7 @@ void _glfwInputWindowPos(_GLFWwindow* window, int xpos, int ypos); */ void _glfwInputWindowSize(_GLFWwindow* window, int width, int height); -/*! @brief Notifies shared code of a framebuffer resize event. +/*! @brief Notifies shared code that a window framebuffer has been resized. * @param[in] window The window that received the event. * @param[in] width The new width, in pixels, of the framebuffer. * @param[in] height The new height, in pixels, of the framebuffer. @@ -870,7 +870,7 @@ void _glfwInputWindowSize(_GLFWwindow* window, int width, int height); */ void _glfwInputFramebufferSize(_GLFWwindow* window, int width, int height); -/*! @brief Notifies shared code of a window iconification event. +/*! @brief Notifies shared code that a window has been iconified or restored. * @param[in] window The window that received the event. * @param[in] iconified `GLFW_TRUE` if the window was iconified, or * `GLFW_FALSE` if it was restored. @@ -878,7 +878,7 @@ void _glfwInputFramebufferSize(_GLFWwindow* window, int width, int height); */ void _glfwInputWindowIconify(_GLFWwindow* window, GLFWbool iconified); -/*! @brief Notifies shared code of a window maximization event. +/*! @brief Notifies shared code that a window has been maximized or restored. * @param[in] window The window that received the event. * @param[in] maximized `GLFW_TRUE` if the window was maximized, or * `GLFW_FALSE` if it was restored. @@ -886,17 +886,22 @@ void _glfwInputWindowIconify(_GLFWwindow* window, GLFWbool iconified); */ void _glfwInputWindowMaximize(_GLFWwindow* window, GLFWbool maximized); -/*! @brief Notifies shared code of a window damage event. +/*! @brief Notifies shared code that a window's contents needs updating. * @param[in] window The window that received the event. */ void _glfwInputWindowDamage(_GLFWwindow* window); -/*! @brief Notifies shared code of a window close request event +/*! @brief Notifies shared code that the user wishes to close a window. * @param[in] window The window that received the event. * @ingroup event */ void _glfwInputWindowCloseRequest(_GLFWwindow* window); +/*! @brief Notifies shared code that a window has changed its desired monitor. + * @param[in] window The window that received the event. + * @param[in] monitor The new desired monitor, or `NULL`. + * @ingroup event + */ void _glfwInputWindowMonitorChange(_GLFWwindow* window, _GLFWmonitor* monitor); /*! @brief Notifies shared code of a physical key event. @@ -931,6 +936,7 @@ void _glfwInputScroll(_GLFWwindow* window, double xoffset, double yoffset); * @param[in] window The window that received the event. * @param[in] button The button that was pressed or released. * @param[in] action @ref GLFW_PRESS or @ref GLFW_RELEASE. + * @param[in] mods The modifiers pressed when the event was generated. * @ingroup event */ void _glfwInputMouseClick(_GLFWwindow* window, int button, int action, int mods); @@ -953,11 +959,19 @@ void _glfwInputCursorPos(_GLFWwindow* window, double xpos, double ypos); */ void _glfwInputCursorEnter(_GLFWwindow* window, GLFWbool entered); -/*! @ingroup event +/*! @brief Notifies shared code of a monitor connection or disconnection. + * @param[in] monitor The monitor that was connected or disconnected. + * @param[in] action One of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`. + * @param[in] placement `_GLFW_INSERT_FIRST` or `_GLFW_INSERT_LAST`. + * @ingroup event */ void _glfwInputMonitor(_GLFWmonitor* monitor, int action, int placement); -/*! @ingroup event +/*! @brief Notifies shared code that a full screen window has acquired or + * released a monitor. + * @param[in] monitor The monitor that was acquired or released. + * @param[in] window The window that acquired the monitor, or `NULL`. + * @ingroup event */ void _glfwInputMonitorWindow(_GLFWmonitor* monitor, _GLFWwindow* window); @@ -973,7 +987,7 @@ void _glfwInputError(int error, const char* format, ...) __attribute__((format(p void _glfwInputError(int error, const char* format, ...); #endif -/*! @brief Notifies dropped object over window. +/*! @brief Notifies shared code of files or directories dropped on a window. * @param[in] window The window that received the event. * @param[in] count The number of dropped objects. * @param[in] names The names of the dropped objects. @@ -981,7 +995,7 @@ void _glfwInputError(int error, const char* format, ...); */ void _glfwInputDrop(_GLFWwindow* window, int count, const char** names); -/*! @brief Notifies shared code of a joystick connection/disconnection event. +/*! @brief Notifies shared code of a joystick connection or disconnection. * @param[in] jid The joystick that was connected or disconnected. * @param[in] event One of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`. * @ingroup event