Header file documentation work

This commit is contained in:
Camilla Berglund 2015-10-24 20:48:46 +02:00
parent b312f5e208
commit 318e8acfae
4 changed files with 43 additions and 25 deletions

View File

@ -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

View File

@ -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 <glad/glad.h>

View File

@ -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

View File

@ -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`