From 318e8acfae8e6a15cf4abf3e5d98c5bbffaec73f Mon Sep 17 00:00:00 2001 From: Camilla Berglund Date: Sat, 24 Oct 2015 20:48:46 +0200 Subject: [PATCH] Header file documentation work --- docs/Doxyfile.in | 16 +++++++++------- docs/quick.dox | 35 +++++++++++++++++------------------ include/GLFW/glfw3.h | 8 ++++++++ include/GLFW/glfw3native.h | 9 +++++++++ 4 files changed, 43 insertions(+), 25 deletions(-) diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index 8410a850..ed304d3a 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -1573,13 +1573,15 @@ INCLUDE_FILE_PATTERNS = # undefined via #undef or recursively expanded use the := operator # instead of the = operator. -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 \ +PREDEFINED = GLFWAPI= \ + GLFW_EXPOSE_NATIVE_WIN32 \ + GLFW_EXPOSE_NATIVE_WGL \ + GLFW_EXPOSE_NATIVE_X11 \ + GLFW_EXPOSE_NATIVE_WAYLAND \ + GLFW_EXPOSE_NATIVE_MIR \ + 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 diff --git a/docs/quick.dox b/docs/quick.dox index 87d60071..754da33f 100644 --- a/docs/quick.dox +++ b/docs/quick.dox @@ -27,29 +27,28 @@ to include the GLFW 3 header file. This defines all the constants, types and function prototypes of the GLFW API. It also includes the OpenGL header from your development environment and -defines all the constants and types necessary for it to work on your platform. - -For example, under Windows you are normally required to include `windows.h` -before including `GL/gl.h`. This would pollute your program's namespace with -the whole Win32 API. - -Instead, the GLFW header duplicates only the very few necessary parts of it. It -does this only when needed, so if `windows.h` _is_ included, the GLFW header -does not try to redefine those symbols. +defines all the constants and types necessary for it to work on your platform +without including any platform-specific headers. In other words: -- Do _not_ include the OpenGL headers yourself, as GLFW does this for you +- Do _not_ include the OpenGL header yourself, as GLFW does this for you in + a platform-independent way - Do _not_ include `windows.h` or other platform-specific headers unless - you plan on using those APIs directly -- If you _do_ need to include such headers, do it _before_ including the - GLFW one and it will detect this + you plan on using those APIs yourself +- If you _do_ need to include such headers, include them _before_ the GLFW + header and it will detect this -If you are using an [extension loader library](@ref context_glext_auto) to -access modern OpenGL then include the header for that library _before_ the GLFW -header. This lets it replace the OpenGL header included by GLFW without -conflicts. The following example uses [glad](https://github.com/Dav1dde/glad), -but the same rule applies to all. +On some platforms supported by GLFW the OpenGL header and link library only +expose older versions of OpenGL. The most extreme case is Windows, which only +exposes OpenGL 1.2. The easiest way to work around this is to use an +[extension loader library](@ref context_glext_auto). + +If you are using such a library then you should include its header _before_ the +GLFW header. This lets it replace the OpenGL header included by GLFW without +conflicts. This example uses +[glad](https://github.com/Dav1dde/glad), but the same rule applies to all such +libraries. @code #include diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h index 965dbe7a..641e8714 100644 --- a/include/GLFW/glfw3.h +++ b/include/GLFW/glfw3.h @@ -38,6 +38,14 @@ extern "C" { * Doxygen documentation *************************************************************************/ +/*! @file glfw3.h + * @brief The header of the GLFW 3 API. + * + * This is the header file of the GLFW 3 API. It defines all its types and + * declares all its functions. + * + * For more information about how to use this file, see @ref build_include. + */ /*! @defgroup context Context handling * * This is the reference documentation for context related functions. For more diff --git a/include/GLFW/glfw3native.h b/include/GLFW/glfw3native.h index 94615fb4..799effaa 100644 --- a/include/GLFW/glfw3native.h +++ b/include/GLFW/glfw3native.h @@ -38,6 +38,12 @@ extern "C" { * Doxygen documentation *************************************************************************/ +/*! @file glfw3native.h + * @brief The header of the native access functions. + * + * This is the header file of the native access functions. See @ref native for + * more information. + */ /*! @defgroup native Native access * * **By using the native access functions you assert that you know what you're @@ -48,6 +54,9 @@ extern "C" { * window system API macro and exactly one context creation API macro. Failure * to do this will cause a compile-time error. * + * The chosen backends must match those the library was compiled for. Failure + * to do this will cause a link-time error. + * * The available window API macros are: * * `GLFW_EXPOSE_NATIVE_WIN32` * * `GLFW_EXPOSE_NATIVE_COCOA`