From 6f8084f061d97c132ba69ca069483c208f37015f Mon Sep 17 00:00:00 2001 From: Camilla Berglund Date: Thu, 14 Feb 2013 13:14:17 +0100 Subject: [PATCH] Documentation work. Enabled Doxygen tree view, added CMake options for native and internal modules, improved internal and native documentation. --- CMakeLists.txt | 11 ++++ docs/Doxyfile.in | 19 ++++-- include/GL/glfw3.h | 12 +++- include/GL/glfw3native.h | 28 ++++++-- src/internal.h | 139 +++++++++++++++++---------------------- 5 files changed, 117 insertions(+), 92 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 3f394d56..80915fad 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -14,6 +14,17 @@ option(GLFW_BUILD_EXAMPLES "Build the GLFW example programs" ON) option(GLFW_BUILD_TESTS "Build the GLFW test programs" ON) option(BUILD_SHARED_LIBS "Build shared libraries" OFF) +option(GLFW_DOCUMENT_NATIVE "Include documentation of native access functions" OFF) +option(GLFW_DOCUMENT_INTERNALS "Include documentation of internal functions" OFF) + +set(GLFW_DOC_HEADERS "${GLFW_SOURCE_DIR}/include/GL/glfw3.h") +if (GLFW_DOCUMENT_NATIVE) + set(GLFW_DOC_HEADERS "${GLFW_DOC_HEADERS} ${GLFW_SOURCE_DIR}/include/GL/glfw3native.h") +endif() +if (GLFW_DOCUMENT_INTERNALS) + set(GLFW_DOC_HEADERS "${GLFW_DOC_HEADERS} ${GLFW_SOURCE_DIR}/src/internal.h") +endif() + if (APPLE) option(GLFW_USE_CHDIR "Make glfwInit chdir to Contents/Resources" ON) option(GLFW_USE_MENUBAR "Populate the menu bar on first window creation" ON) diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index fe54ebc7..79eed0cc 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -655,7 +655,7 @@ WARN_LOGFILE = @GLFW_BINARY_DIR@/docs/warnings.txt # directories like "/usr/src/myproject". Separate the files or directories # with spaces. -INPUT = @GLFW_SOURCE_DIR@/include/GL/glfw3.h +INPUT = @GLFW_DOC_HEADERS@ # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is @@ -1115,7 +1115,7 @@ ECLIPSE_DOC_ID = org.doxygen.Project # navigation tree you can set this option to NO if you already set # GENERATE_TREEVIEW to YES. -DISABLE_INDEX = NO +DISABLE_INDEX = YES # The GENERATE_TREEVIEW tag is used to specify whether a tree-like index # structure should be generated to display hierarchical information. @@ -1127,7 +1127,7 @@ DISABLE_INDEX = NO # Since the tree basically has the same information as the tab index you # could consider to set DISABLE_INDEX to NO when enabling this option. -GENERATE_TREEVIEW = NO +GENERATE_TREEVIEW = YES # The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values # (range [0,1..20]) that doxygen will group on one line in the generated HTML @@ -1140,7 +1140,7 @@ ENUM_VALUES_PER_LINE = 4 # used to set the initial width (in pixels) of the frame in which the tree # is shown. -TREEVIEW_WIDTH = 250 +TREEVIEW_WIDTH = 300 # When the EXT_LINKS_IN_WINDOW option is set to YES doxygen will open # links to external symbols imported via tag files in a separate window. @@ -1486,7 +1486,7 @@ EXPAND_ONLY_PREDEF = YES # If the SEARCH_INCLUDES tag is set to YES (the default) the includes files # pointed to by INCLUDE_PATH will be searched when a #include is found. -SEARCH_INCLUDES = YES +SEARCH_INCLUDES = NO # The INCLUDE_PATH tag can be used to specify one or more directories that # contain include files that are not input files but should be processed by @@ -1509,7 +1509,14 @@ INCLUDE_FILE_PATTERNS = # undefined via #undef or recursively expanded use the := operator # instead of the = operator. -PREDEFINED = GLFWAPI= +PREDEFINED = GLFWAPI= \ + GLFW_EXPOSE_NATIVE_WIN32 \ + GLFW_EXPOSE_NATIVE_WGL \ + GLFW_EXPOSE_NATIVE_X11 \ + GLFW_EXPOSE_NATIVE_GLX \ + GLFW_EXPOSE_NATIVE_COCOA \ + GLFW_EXPOSE_NATIVE_NSGL \ + GLFW_EXPOSE_NATIVE_EGL # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then # this tag can be used to specify a list of macro names that should be expanded. diff --git a/include/GL/glfw3.h b/include/GL/glfw3.h index 0d6cbfc5..31619e65 100644 --- a/include/GL/glfw3.h +++ b/include/GL/glfw3.h @@ -783,10 +783,12 @@ GLFWAPI void glfwTerminate(void); */ GLFWAPI void glfwGetVersion(int* major, int* minor, int* rev); -/*! @brief Returns the version string of the GLFW library. +/*! @brief Returns a string describing the compile-time configuration. * - * The version string contains information about what compile-time options were - * enabled when the library was built. + * The format of the string is as follows: + * @arg The name of the window system API + * @arg The name of the context creation API + * @arg Any additional options or APIs * * @return The GLFW version string. * @ingroup init @@ -1062,6 +1064,10 @@ GLFWAPI void glfwWindowHint(int target, int hint); * can use the newly created context, you need to make it current using @ref * glfwMakeContextCurrent. * + * @remarks To create the window at a specific position, make it initially + * invisible using the @c GLFW_VISIBLE window hint, set its position and then + * show it. + * * @remarks For fullscreen windows the initial cursor mode is @c * GLFW_CURSOR_CAPTURED and the screensaver is prohibited from starting. For * regular windows the initial cursor mode is @c GLFW_CURSOR_NORMAL and the diff --git a/include/GL/glfw3native.h b/include/GL/glfw3native.h index fc20884e..6a2c1d15 100644 --- a/include/GL/glfw3native.h +++ b/include/GL/glfw3native.h @@ -39,11 +39,31 @@ extern "C" { * Doxygen documentation *************************************************************************/ -/*! @defgroup native Native API +/*! @defgroup native Native access * - * By using the native API, you assert that you know what you are doing and how - * to fix problems caused by using it. If you don't, you shouldn't be using - * it. + * By using the native API, you assert that you know what you are + * doing and how to fix problems caused by using it. If you don't, you + * shouldn't be using it. + * + * Before the inclusion of @ref glfw3native.h, you must define exactly one + * window API macro and exactly one context API macro. Failure to do this + * will cause a compile-time error. + * + * The available window API macros are: + * @arg @c GLFW_EXPOSE_NATIVE_WIN32 + * @arg @c GLFW_EXPOSE_NATIVE_COCOA + * @arg @c GLFW_EXPOSE_NATIVE_X11 + * + * The available context API macros are: + * @arg @c GLFW_EXPOSE_NATIVE_WGL + * @arg @c GLFW_EXPOSE_NATIVE_NSGL + * @arg @c GLFW_EXPOSE_NATIVE_GLX + * @arg @c GLFW_EXPOSE_NATIVE_EGL + * + * These macros select which of the native access functions are declared and + * which platform-specific headers to include. It is then up your (by + * definition platform-specific) code to handle which of these should be + * defined. */ diff --git a/src/internal.h b/src/internal.h index 1c91fe2c..88bf9c52 100644 --- a/src/internal.h +++ b/src/internal.h @@ -79,22 +79,22 @@ typedef struct _GLFWmonitor _GLFWmonitor; // Doxygen group definitions //======================================================================== -/*! @defgroup platform Platform API - * @brief The API implemented by the platform-specific code. +/*! @defgroup platform Platform interface + * @brief The interface implemented by the platform-specific code. * * The platform API is the interface exposed by the platform-specific code for * each platform and is called by the shared code of the public API It mirrors * the public API except it uses objects instead of handles. */ -/*! @defgroup event Event API - * @brief The API used by the platform-specific code to report events. +/*! @defgroup event Event interface + * @brief The interface used by the platform-specific code to report events. * * The event API is used by the platform-specific code to notify the shared * code of events that can be translated into state changes and/or callback * calls. */ /*! @defgroup utility Utility functions - * @brief Various utility functions. + * @brief Various utility functions for internal use. * * These functions are shared code and may be used by any part of GLFW * Each platform may add its own utility functions, but those may only be @@ -325,32 +325,19 @@ int _glfwPlatformInit(void); */ void _glfwPlatformTerminate(void); -/*! @brief Returns a string describing the compile-time configuration of the - * platform-specific part of the library. - * @return The version string. +/*! @copydoc glfwGetVersionString * @ingroup platform * - * The format of the string is as follows: - * @arg The name of the window system API used - * @arg The name of the context creation API used - * @arg Any additional options or APIs - * * @note The returned string must be available for the duration of the program. * * @note The returned string must not change for the duration of the program. */ const char* _glfwPlatformGetVersionString(void); -/*! @brief Sets the position of the system cursor. - * @param[in] window The window whose client area the specified posiiton is - * relative to. - * @param[in] x The new x-coordinate of the cursor, relative to the left edge - * of the client area of the window. - * @param[in] y The new y-coordinate of the cursor, relative to the top edge - * of the client area of the window. +/*! @copydoc glfwSetCursorPos * @ingroup platform */ -void _glfwPlatformSetCursorPos(_GLFWwindow* window, int x, int y); +void _glfwPlatformSetCursorPos(_GLFWwindow* window, int xpos, int ypos); /*! @brief Sets up the specified cursor mode for the specified window. * @param[in] window The window whose cursor mode to change. @@ -359,7 +346,8 @@ void _glfwPlatformSetCursorPos(_GLFWwindow* window, int x, int y); */ void _glfwPlatformSetCursorMode(_GLFWwindow* window, int mode); -/*! @ingroup platform +/*! @copydoc glfwGetMonitors + * @ingroup platform */ _GLFWmonitor** _glfwPlatformGetMonitors(int* count); @@ -367,7 +355,8 @@ _GLFWmonitor** _glfwPlatformGetMonitors(int* count); */ void _glfwPlatformDestroyMonitor(_GLFWmonitor* monitor); -/*! @ingroup platform +/*! @copydoc glfwGetVideoModes + * @ingroup platform */ GLFWvidmode* _glfwPlatformGetVideoModes(_GLFWmonitor* monitor, int* count); @@ -375,33 +364,22 @@ GLFWvidmode* _glfwPlatformGetVideoModes(_GLFWmonitor* monitor, int* count); */ void _glfwPlatformGetVideoMode(_GLFWmonitor* monitor, GLFWvidmode* mode); -/*! @brief Retrieves the current gamma ramp for the specified monitor. - * @param[in] monitor The monitor to query. - * @param[out] ramp The current system gamma ramp. +/*! @copydoc glfwGetGammaRamp * @ingroup platform */ void _glfwPlatformGetGammaRamp(_GLFWmonitor* monitor, GLFWgammaramp* ramp); -/*! @brief Sets the gamma ramp for the specified monitor. - * @param[in] monitor The monitor whose gamma ramp to set. - * @param[in] ramp The desired system gamma ramp. +/*! @copydoc glfwSetGammaRamp * @ingroup platform */ void _glfwPlatformSetGammaRamp(_GLFWmonitor* monitor, const GLFWgammaramp* ramp); -/*! @brief Sets the system clipboard to the specified string. - * @param[in] window The window who will own the system clipboard contents, on - * systems where this is necessary. - * @param[in] string The UTF-8 encoded string to use. +/*! @copydoc glfwSetClipboardString * @ingroup platform */ void _glfwPlatformSetClipboardString(_GLFWwindow* window, const char* string); -/*! @brief Returns the string in the system clipboard. - * @param[in] window The window who will request the system clipboard contents, - * on systems where this is necessary. - * @return The UTF-8 encoded contents, or @c NULL if the system clipboard did - * not contain a string. +/*! @copydoc glfwGetClipboardString * @ingroup platform * * @note The returned string must be valid until the next call to @ref @@ -409,34 +387,32 @@ void _glfwPlatformSetClipboardString(_GLFWwindow* window, const char* string); */ const char* _glfwPlatformGetClipboardString(_GLFWwindow* window); -/*! @brief Returns the value of the specified joystick property. - * @param[in] joy The joystick to use. - * @param[in] param The property whose value to return. - * @return The value of the specified property, or zero if an error occurred. +/*! @copydoc glfwGetJoystickParam * @ingroup platform */ int _glfwPlatformGetJoystickParam(int joy, int param); -/*! @ingroup platform +/*! @copydoc glfwGetJoystickAxes + * @ingroup platform */ int _glfwPlatformGetJoystickAxes(int joy, float* axes, int numaxes); -/*! @ingroup platform +/*! @copydoc glfwGetJoystickButtons + * @ingroup platform */ int _glfwPlatformGetJoystickButtons(int joy, unsigned char* buttons, int numbuttons); -/*! @ingroup platform +/*! @copydoc glfwGetJoystickName + * @ingroup platform */ const char* _glfwPlatformGetJoystickName(int joy); -/*! @brief Returns the current value of the timer. - * @return The value, in seconds, of the timer. +/*! @copydoc glfwGetTime * @ingroup platform */ double _glfwPlatformGetTime(void); -/*! @brief Sets the value of the timer. - * @param[in] time The new value, in seconds, of the timer. +/*! @copydoc glfwSetTime * @ingroup platform */ void _glfwPlatformSetTime(double time); @@ -451,63 +427,78 @@ int _glfwPlatformCreateWindow(_GLFWwindow* window, */ void _glfwPlatformDestroyWindow(_GLFWwindow* window); -/*! @ingroup platform +/*! @copydoc glfwSetWindowTitle + * @ingroup platform */ void _glfwPlatformSetWindowTitle(_GLFWwindow* window, const char* title); -/*! @ingroup platform +/*! @copydoc glfwGetWindowPos + * @ingroup platform */ void _glfwPlatformGetWindowPos(_GLFWwindow* window, int* xpos, int* ypos); -/*! @ingroup platform +/*! @copydoc glfwSetWindowPos + * @ingroup platform */ void _glfwPlatformSetWindowPos(_GLFWwindow* window, int xpos, int ypos); -/*! @ingroup platform +/*! @copydoc glfwGetWindowSize + * @ingroup platform */ void _glfwPlatformGetWindowSize(_GLFWwindow* window, int* width, int* height); -/*! @ingroup platform +/*! @copydoc glfwSetWindowSize + * @ingroup platform */ void _glfwPlatformSetWindowSize(_GLFWwindow* window, int width, int height); -/*! @ingroup platform +/*! @copydoc glfwIconifyWindow + * @ingroup platform */ void _glfwPlatformIconifyWindow(_GLFWwindow* window); -/*! @ingroup platform +/*! @copydoc glfwRestoreWindow + * @ingroup platform */ void _glfwPlatformRestoreWindow(_GLFWwindow* window); -/*! @ingroup platform +/*! @copydoc glfwShowWindow + * @ingroup platform */ void _glfwPlatformShowWindow(_GLFWwindow* window); -/*! @ingroup platform +/*! @copydoc glfwHideWindow + * @ingroup platform */ void _glfwPlatformHideWindow(_GLFWwindow* window); -/*! @ingroup platform +/*! @copydoc glfwPollEvents + * @ingroup platform */ void _glfwPlatformPollEvents(void); -/*! @ingroup platform +/*! @copydoc glfwWaitEvents + * @ingroup platform */ void _glfwPlatformWaitEvents(void); -/*! @ingroup platform +/*! @copydoc glfwMakeContextCurrent + * @ingroup platform */ void _glfwPlatformMakeContextCurrent(_GLFWwindow* window); -/*! @ingroup platform +/*! @copydoc glfwGetCurrentContext + * @ingroup platform */ _GLFWwindow* _glfwPlatformGetCurrentContext(void); -/*! @ingroup platform +/*! @copydoc glfwSwapBuffers + * @ingroup platform */ void _glfwPlatformSwapBuffers(_GLFWwindow* window); -/*! @ingroup platform +/*! @copydoc glfwSwapInterval + * @ingroup platform */ void _glfwPlatformSwapInterval(int interval); @@ -515,17 +506,7 @@ void _glfwPlatformSwapInterval(int interval); */ int _glfwPlatformExtensionSupported(const char* extension); -/*! @ingroup platform - */ -GLFWglproc _glfwPlatformGetProcAddress(const char* procname); - -/*! @ingroup platform - */ -int _glfwPlatformExtensionSupported(const char* extension); - -/*! @brief Returns the address of the specified client API function. - * @param[in] procname The name of the desired function. - * @return The address of the function, or @c NULL if it is not available. +/*! @copydoc glfwGetProcAddress * @ingroup platform */ GLFWglproc _glfwPlatformGetProcAddress(const char* procname); @@ -545,11 +526,11 @@ void _glfwInputWindowFocus(_GLFWwindow* window, GLboolean focused); /*! @brief Notifies shared code of a window movement event. * @param[in] window The window that received the event. - * @param[in] x The new x-coordinate of the client area of the window. - * @param[in] x The new y-coordinate of the client area of the window. + * @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. * @ingroup event */ -void _glfwInputWindowPos(_GLFWwindow* window, int x, int y); +void _glfwInputWindowPos(_GLFWwindow* window, int xpos, int ypos); /*! @brief Notifies shared code of a window resize event. * @param[in] window The window that received the event. @@ -669,7 +650,7 @@ void _glfwSplitBPP(int bpp, int* red, int* green, int* blue); /*! @brief Searches an extension string for the specified extension. * @param[in] string The extension string to search. - * @param[in] extension The extension to search for. + * @param[in] extensions The extension to search for. * @return @c GL_TRUE if the extension was found, or @c GL_FALSE otherwise. * @ingroup utility */