Documentation work.

docs/Doxyfile.in

@@ -1,4 +1,4 @@
-# Doxyfile 1.8.1.2
+# Doxyfile 1.8.3.1
 
 # This file describes the settings to be used by the documentation system
 # doxygen (www.doxygen.org) for a project.
@@ -126,7 +126,9 @@ FULL_PATH_NAMES        = NO
 # only done if one of the specified strings matches the left-hand part of
 # the path. The tag can be used to show relative paths in the file list.
 # If left blank the directory from which doxygen is run is used as the
-# path to strip.
+# path to strip. Note that you specify absolute paths here, but also
+# relative paths, which will be relative from the directory where doxygen is
+# started.
 
 STRIP_FROM_PATH        =
 
@@ -229,14 +231,15 @@ OPTIMIZE_FOR_FORTRAN   = NO
 OPTIMIZE_OUTPUT_VHDL   = NO
 
 # Doxygen selects the parser to use depending on the extension of the files it
-# parses. With this tag you can assign which parser to use for a given extension.
-# Doxygen has a built-in mapping, but you can override or extend it using this
-# tag. The format is ext=language, where ext is a file extension, and language
-# is one of the parsers supported by doxygen: IDL, Java, Javascript, CSharp, C,
-# C++, D, PHP, Objective-C, Python, Fortran, VHDL, C, C++. For instance to make
-# doxygen treat .inc files as Fortran files (default is PHP), and .f files as C
-# (default is Fortran), use: inc=Fortran f=C. Note that for custom extensions
-# you also need to set FILE_PATTERNS otherwise the files are not read by doxygen.
+# parses. With this tag you can assign which parser to use for a given
+# extension. Doxygen has a built-in mapping, but you can override or extend it
+# using this tag. The format is ext=language, where ext is a file extension,
+# and language is one of the parsers supported by doxygen: IDL, Java,
+# Javascript, CSharp, C, C++, D, PHP, Objective-C, Python, Fortran, VHDL, C,
+# C++. For instance to make doxygen treat .inc files as Fortran files (default
+# is PHP), and .f files as C (default is Fortran), use: inc=Fortran f=C. Note
+# that for custom extensions you also need to set FILE_PATTERNS otherwise the
+# files are not read by doxygen.
 
 EXTENSION_MAPPING      =
 
@@ -249,6 +252,13 @@ EXTENSION_MAPPING      =
 
 MARKDOWN_SUPPORT       = YES
 
+# When enabled doxygen tries to link words that correspond to documented classes,
+# or namespaces to their corresponding documentation. Such a link can be
+# prevented in individual cases by by putting a % sign in front of the word or
+# globally by setting AUTOLINK_SUPPORT to NO.
+
+AUTOLINK_SUPPORT       = YES
+
 # If you use STL classes (i.e. std::string, std::vector, etc.) but do not want
 # to include (a tag file for) the STL sources as input, then you should
 # set this tag to YES in order to let doxygen match functions declarations and
@@ -269,14 +279,14 @@ CPP_CLI_SUPPORT        = NO
 
 SIP_SUPPORT            = NO
 
-# For Microsoft's IDL there are propget and propput attributes to indicate getter
-# and setter methods for a property. Setting this option to YES (the default)
-# will make doxygen replace the get and set methods by a property in the
-# documentation. This will only work if the methods are indeed getting or
+# For Microsoft's IDL there are propget and propput attributes to indicate
+# getter and setter methods for a property. Setting this option to YES (the
+# default) will make doxygen replace the get and set methods by a property in
+# the documentation. This will only work if the methods are indeed getting or
 # setting a simple type. If this is not the case, or you want to show the
 # methods anyway, you should set this option to NO.
 
-IDL_PROPERTY_SUPPORT   = YES
+IDL_PROPERTY_SUPPORT   = NO
 
 # If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC
 # tag is set to YES, then doxygen will reuse the documentation of the first
@@ -534,7 +544,8 @@ GENERATE_BUGLIST       = YES
 GENERATE_DEPRECATEDLIST= YES
 
 # The ENABLED_SECTIONS tag can be used to enable conditional
-# documentation sections, marked by \if sectionname ... \endif.
+# documentation sections, marked by \if section-label ... \endif
+# and \cond section-label ... \endcond blocks.
 
 ENABLED_SECTIONS       =
 
@@ -592,7 +603,8 @@ LAYOUT_FILE            =
 # requires the bibtex tool to be installed. See also
 # http://en.wikipedia.org/wiki/BibTeX for more info. For LaTeX the style
 # of the bibliography can be controlled using LATEX_BIB_STYLE. To use this
-# feature you need bibtex and perl available in the search path.
+# feature you need bibtex and perl available in the search path. Do not use
+# file names with spaces, bibtex cannot handle them.
 
 CITE_BIB_FILES         =
 
@@ -774,6 +786,13 @@ FILTER_SOURCE_FILES    = NO
 
 FILTER_SOURCE_PATTERNS =
 
+# If the USE_MD_FILE_AS_MAINPAGE tag refers to the name of a markdown file that
+# is part of the input, its contents will be placed on the main page (index.html).
+# This can be useful if you have a project on for instance GitHub and want reuse
+# the introduction page also for the doxygen output.
+
+USE_MDFILE_AS_MAINPAGE =
+
 #---------------------------------------------------------------------------
 # configuration options related to source browsing
 #---------------------------------------------------------------------------
@@ -895,13 +914,23 @@ HTML_FOOTER            =
 
 # The HTML_STYLESHEET tag can be used to specify a user-defined cascading
 # style sheet that is used by each HTML page. It can be used to
-# fine-tune the look of the HTML output. If the tag is left blank doxygen
-# will generate a default style sheet. Note that doxygen will try to copy
-# the style sheet file to the HTML output directory, so don't put your own
-# style sheet in the HTML output directory as well, or it will be erased!
+# fine-tune the look of the HTML output. If left blank doxygen will
+# generate a default style sheet. Note that it is recommended to use
+# HTML_EXTRA_STYLESHEET instead of this one, as it is more robust and this
+# tag will in the future become obsolete.
 
 HTML_STYLESHEET        =
 
+# The HTML_EXTRA_STYLESHEET tag can be used to specify an additional
+# user-defined cascading style sheet that is included after the standard
+# style sheets created by doxygen. Using this option one can overrule
+# certain style aspects. This is preferred over using HTML_STYLESHEET
+# since it does not replace the standard style sheet and is therefor more
+# robust against future updates. Doxygen will copy the style sheet file to
+# the output directory.
+
+HTML_EXTRA_STYLESHEET  = 
+
 # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
 # other source files which should be copied to the HTML output directory. Note
 # that these files will be copied to the base HTML output directory. Use the
@@ -986,9 +1015,9 @@ DOCSET_FEEDNAME        = "Doxygen generated docs"
 
 DOCSET_BUNDLE_ID       = org.doxygen.Project
 
-# When GENERATE_PUBLISHER_ID tag specifies a string that should uniquely identify
-# the documentation publisher. This should be a reverse domain-name style
-# string, e.g. com.mycompany.MyDocSet.documentation.
+# When GENERATE_PUBLISHER_ID tag specifies a string that should uniquely
+# identify the documentation publisher. This should be a reverse domain-name
+# style string, e.g. com.mycompany.MyDocSet.documentation.
 
 DOCSET_PUBLISHER_ID    = org.doxygen.Publisher
 
@@ -1173,6 +1202,13 @@ FORMULA_TRANSPARENT    = YES
 
 USE_MATHJAX            = NO
 
+# When MathJax is enabled you can set the default output format to be used for
+# thA MathJax output. Supported types are HTML-CSS, NativeMML (i.e. MathML) and
+# SVG. The default value is HTML-CSS, which is slower, but has the best
+# compatibility.
+
+MATHJAX_FORMAT         = HTML-CSS
+
 # When MathJax is enabled you need to specify the location relative to the
 # HTML output directory using the MATHJAX_RELPATH option. The destination
 # directory should contain the MathJax.js script. For instance, if the mathjax
@@ -1201,15 +1237,55 @@ MATHJAX_EXTENSIONS     =
 SEARCHENGINE           = YES
 
 # When the SERVER_BASED_SEARCH tag is enabled the search engine will be
-# implemented using a PHP enabled web server instead of at the web client
-# using Javascript. Doxygen will generate the search PHP script and index
-# file to put on the web server. The advantage of the server
-# based approach is that it scales better to large projects and allows
-# full text search. The disadvantages are that it is more difficult to setup
-# and does not have live searching capabilities.
+# implemented using a web server instead of a web client using Javascript.
+# There are two flavours of web server based search depending on the
+# EXTERNAL_SEARCH setting. When disabled, doxygen will generate a PHP script for
+# searching and an index file used by the script. When EXTERNAL_SEARCH is
+# enabled the indexing and searching needs to be provided by external tools.
+# See the manual for details.
 
 SERVER_BASED_SEARCH    = NO
 
+# When EXTERNAL_SEARCH is enabled doxygen will no longer generate the PHP
+# script for searching. Instead the search results are written to an XML file
+# which needs to be processed by an external indexer. Doxygen will invoke an
+# external search engine pointed to by the SEARCHENGINE_URL option to obtain
+# the search results. Doxygen ships with an example indexer (doxyindexer) and
+# search engine (doxysearch.cgi) which are based on the open source search engine
+# library Xapian. See the manual for configuration details.
+
+EXTERNAL_SEARCH        = NO
+
+# The SEARCHENGINE_URL should point to a search engine hosted by a web server
+# which will returned the search results when EXTERNAL_SEARCH is enabled.
+# Doxygen ships with an example search engine (doxysearch) which is based on
+# the open source search engine library Xapian. See the manual for configuration
+# details.
+
+SEARCHENGINE_URL       =
+
+# When SERVER_BASED_SEARCH and EXTERNAL_SEARCH are both enabled the unindexed
+# search data is written to a file for indexing by an external tool. With the
+# SEARCHDATA_FILE tag the name of this file can be specified.
+
+SEARCHDATA_FILE        = searchdata.xml
+
+# When SERVER_BASED_SEARCH AND EXTERNAL_SEARCH are both enabled the
+# EXTERNAL_SEARCH_ID tag can be used as an identifier for the project. This is
+# useful in combination with EXTRA_SEARCH_MAPPINGS to search through multiple
+# projects and redirect the results back to the right project.
+
+EXTERNAL_SEARCH_ID     =
+
+# The EXTRA_SEARCH_MAPPINGS tag can be used to enable searching through doxygen
+# projects other than the one defined by this configuration file, but that are
+# all added to the same external search index. Each project needs to have a
+# unique id set via EXTERNAL_SEARCH_ID. The search mapping then maps the id
+# of to a relative location where the documentation can be found.
+# The format is: EXTRA_SEARCH_MAPPINGS = id1=loc1 id2=loc2 ...
+
+EXTRA_SEARCH_MAPPINGS  =
+
 #---------------------------------------------------------------------------
 # configuration options related to the LaTeX output
 #---------------------------------------------------------------------------
@@ -1487,7 +1563,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        = NO
+SEARCH_INCLUDES        = YES
 
 # 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
@@ -1785,7 +1861,7 @@ DOT_TRANSPARENT        = NO
 # makes dot run faster, but since only newer versions of dot (>1.8.10)
 # support this, this feature is disabled by default.
 
-DOT_MULTI_TARGETS      = YES
+DOT_MULTI_TARGETS      = NO
 
 # If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will
 # generate a legend page explaining the meaning of the various boxes and

docs/hints.dox

@@ -1,40 +0,0 @@
-/*!
-
-@page hints Window hints
-
-These are all window hints.  Some relate to the window itself, others to its
-framebuffer or context.  They are set to their default values each time the
-library is initialized with @ref glfwInit, can be individually set with @ref
-glfwWindowHint and reset all at once to their defaults with @ref
-glfwDefaultWindowHints.
-
-Note that hints need to be set *before* the creation of the window you wish to
-have the specified properties.
-
-| Name                         | Default values           | Supported values        |
-| ---------------------------- | ------------------------ | ----------------------- |
-| `GLFW_RESIZABLE`             | `GL_TRUE`                | `GL_TRUE` or `GL_FALSE` |
-| `GLFW_VISIBLE`               | `GL_TRUE`                | `GL_TRUE` or `GL_FALSE` |
-| `GLFW_RED_BITS`              | 8                        | 0 to `INT_MAX`          |
-| `GLFW_GREEN_BITS`            | 8                        | 0 to `INT_MAX`          |
-| `GLFW_BLUE_BITS`             | 8                        | 0 to `INT_MAX`          |
-| `GLFW_ALPHA_BITS`            | 8                        | 0 to `INT_MAX`          |
-| `GLFW_DEPTH_BITS`            | 24                       | 0 to `INT_MAX`          |
-| `GLFW_STENCIL_BITS`          | 8                        | 0 to `INT_MAX`          |
-| `GLFW_ACCUM_RED_BITS`        | 0                        | 0 to `INT_MAX`          |
-| `GLFW_ACCUM_GREEN_BITS`      | 0                        | 0 to `INT_MAX`          |
-| `GLFW_ACCUM_BLUE_BITS`       | 0                        | 0 to `INT_MAX`          |
-| `GLFW_ACCUM_ALPHA_BITS`      | 0                        | 0 to `INT_MAX`          |
-| `GLFW_AUX_BUFFERS`           | 0                        | 0 to `INT_MAX`          |
-| `GLFW_SAMPLES`               | 0                        | 0 to `INT_MAX`          |
-| `GLFW_STEREO`                | `GL_FALSE`               | `GL_TRUE` or `GL_FALSE` |
-| `GLFW_SRGB_CAPABLE`          | `GL_FALSE`               | `GL_TRUE` or `GL_FALSE` |
-| `GLFW_CLIENT_API`            | `GLFW_OPENGL_API`        | `GLFW_OPENGL_API` or `GLFW_OPENGL_ES_API` |
-| `GLFW_CONTEXT_VERSION_MAJOR` | 1                        | Any valid major version number of the chosen client API |
-| `GLFW_CONTEXT_VERSION_MINOR` | 0                        | Any valid minor version number of the chosen client API |
-| `GLFW_CONTEXT_ROBUSTNESS`    | `GLFW_NO_ROBUSTNESS`     | `GLFW_NO_ROBUSTNESS`, `GLFW_NO_RESET_NOTIFICATION` or `GLFW_LOSE_CONTEXT_ON_RESET` |
-| `GLFW_OPENGL_FORWARD_COMPAT` | `GL_FALSE`               | `GL_TRUE` or `GL_FALSE` |
-| `GLFW_OPENGL_DEBUG_CONTEXT`  | `GL_FALSE`               | `GL_TRUE` or `GL_FALSE` |
-| `GLFW_OPENGL_PROFILE`        | `GLFW_OPENGL_NO_PROFILE` | `GLFW_OPENGL_NO_PROFILE`, `GLFW_OPENGL_COMPAT_PROFILE` or `GLFW_OPENGL_CORE_PROFILE` |
-
-*/

docs/main.dox

@@ -8,9 +8,15 @@ GLFW is a free, Open Source, multi-platform library for opening a window,
 creating an OpenGL context and managing input.  It is easy to integrate into
 existing applications and does not lay claim to the main loop.
 
-[Quick introduction](@ref quick) is a short tutorial for people new to GLFW.
+This is the documentation for version 3.0, which has [many new features](@ref news).
 
-[Moving from GLFW 2 to 3](@ref moving) explains what has changed and how to
-update existing code to use the GLFW 3 API.
+There is a [quick tutorial](@ref quick) for people new to GLFW, which shows how
+to write a small but complete program.
+
+If you have used GLFW 2.x in the past, there is a
+[transition guide](@ref moving) that explains what has changed and how to update
+existing code to use the new API.
+
+As this is still unfinished software, there are still [a number of bugs](@ref bug).
 
 */

docs/moving.dox

@@ -7,7 +7,8 @@
 This is a transition guide for moving from GLFW 2 to 3.  It describes what has
 changed or been removed, but does *not* include entirely new features unless
 they are required when moving an existing code base onto the new API.  For example,
-use of the new multi-monitor support is required to create fullscreen windows.
+use of the new multi-monitor functions are required to create fullscreen windows
+with GLFW 3.
 
 
 @section moving_removed Removed features
@@ -65,11 +66,12 @@ callback, *not* the removal of the character callback itself.
 
 @subsection moving_wheel Mouse wheel position
 
-Scroll events do not represent an absolute state.  Instead, it's an
-interpretation of a relative change in state, like character input.  So, like
-character input, there is no sane 'current state' to return.  The mouse wheel
-callback has been replaced by a [scroll callback](@ref GLFWscrollfun) that
-receives two-dimensional scroll offsets.
+The `glfwGetMouseWheel` function has been removed.  Scroll events do not
+represent an absolute state, but is instead an interpretation of a relative
+change in state, like character input.  So, like character input, there is no
+sane 'current state' to return.  The mouse wheel callback has been replaced by
+a [scroll callback](@ref GLFWscrollfun) that receives two-dimensional scroll
+offsets.
 
 
 @subsection moving_stdcall GLFWCALL macro
@@ -87,7 +89,7 @@ point suffixes.
 
 The Win32 port of GLFW 3 will not compile in
 [MBCS mode](http://msdn.microsoft.com/en-us/library/5z097dxa.aspx).
-Hoever, because the use of the Unicode version of the Win32 API doesn't affect
+However, because the use of the Unicode version of the Win32 API doesn't affect
 the process as a whole, but only those windows created using it, it's perfectly
 possible to call MBCS functions from other parts of the same application.
 Therefore, even if an application using GLFW uses MBCS mode, there's no need for
@@ -122,13 +124,27 @@ or something else, are nowadays expected to be good desktop citizens and allow
 these hotkeys to function even when running in fullscreen mode.
 
 
+@subsection moving_autopoll Automatic polling of events
+
+GLFW 3 does not automatically poll for events on @ref glfwSwapBuffers, which
+means you need to call @ref glfwPollEvents or @ref glfwWaitEvents yourself.
+Unlike buffer swap, the event processing functions act on all windows at once.
+
+
 @subsection moving_terminate Automatic termination
 
-@ref glfwTerminate is no longer registered with `atexit` at initialization.  To
+GLFW 3 does not register @ref glfwTerminate with `atexit` at initialization.  To
 properly release all resources allocated by GLFW, you should therefore call @ref
 glfwTerminate yourself before exiting.
 
 
+@subsection moving_glu GLU header inclusion
+
+GLFW 3 does not include the GLU header by default and GLU itself has been
+deprecated, but you can request that the GLFW 3 header includes it by defining
+`GLFW_INCLUDE_GLU` before the inclusion of the GLFW 3 header.
+
+
 @section moving_changed Changes to existing features
 
 @subsection moving_window_handles Window handles
@@ -143,9 +159,10 @@ to an opaque struct.
 @subsection moving_monitor Multi-monitor support
 
 GLFW 3 provides support for multiple monitors, adding the `GLFWmonitor*` handle
-type and a set of related functions.  To request a fullscreen mode window, you
-need to specify which monitor you wish the window to use.  There is @ref
-glfwGetPrimaryMonitor that provides behaviour similar to that of GLFW 2.
+type and a set of related functions.  To request a fullscreen mode window,
+instead of passing `GLFW_FULLSCREEN` you specify which monitor you wish the
+window to use.  There is @ref glfwGetPrimaryMonitor that provides behaviour
+similar to that of GLFW 2.
 
 
 @subsection moving_window_close Window closing
@@ -172,34 +189,31 @@ functions.
 
 @subsection moving_keys Physical key input
 
-GLFW 3 uses the physical key locations named after the symbols they generate
-using the US keyboard layout, instead of layout-dependent characters like in
-GLFW 2.  This means that (for example) `GLFW_KEY_BACKSLASH` is always a single
-key and is the same key in the same place regardless of what keyboard layouts
-the users of your program has.
+GLFW 3 key tokens map to physical keys, unlike in GLFW 2 where they mapped to
+the values generated by the current keyboard layout.  The tokens are named
+according to the values they would have using the standard US layout, but this
+is only a convenience, as most programmers are assumed to know that layout.
+This means that (for example) `GLFW_KEY_LEFT_BRACKET` is always a single key and
+is the same key in the same place regardless of what keyboard layouts the users
+of your program has.
 
 The key input facility was never meant for text input, although using it that
 way worked slightly better in GLFW 2.  If you were using it to input text, you
 should be using the character callback instead, on both GLFW 2 and 3.  This will
 give you the characters being input, as opposed to the keys being pressed.
 
-GLFW 3 has key tokens for all keys on a standard keyboard, so instead of having
-to remember whether to check for `'a'` or `'A'`, you now check for `GLFW_KEY_A`.
+GLFW 3 has key tokens for all keys on a standard 105 key keyboard, so instead of
+having to remember whether to check for `'a'` or `'A'`, you now check for
+`GLFW_KEY_A`.
 
 
 @subsection moving_video_modes Video mode enumeration
 
-Video mode enumeration is now per-monitor.  The `glfwGetDesktopMode` function
-has been replaced by @ref glfwGetVideoMode, which returns the current mode of
-a monitor.  The @ref glfwGetVideoModes function now returns all available modes
-for a monitor instead of requiring you to guess how large an array you need.
-
-
-@subsection moving_glu GLU header inclusion
-
-Unlike GLFW 2, GLFW 3 doesn't include the GLU header by default, but you can
-make it do so by defining `GLFW_INCLUDE_GLU` before the inclusion of the GLFW
-3 header.
+Video mode enumeration is now per-monitor.  The @ref glfwGetVideoModes function
+now returns all available modes for a specific monitor instead of requiring you
+to guess how large an array you need.  The `glfwGetDesktopMode` function has
+been replaced by @ref glfwGetVideoMode, which returns the current mode of
+a monitor.
 
 
 @subsection moving_cursor Cursor positioning

docs/news.dox

@@ -0,0 +1,124 @@
+/*!
+
+@page news New features
+
+@tableofcontents
+
+
+@section news_30 New features in version 3.0
+
+@subsection news_30_cmake CMake build system
+
+GLFW now uses the CMake build system instead of the various makefiles and
+project files used by earlier versions.  CMake is available for all platforms
+supported by GLFW, is present in most package systems and can generate
+makefiles and/or project files for most popular development environments.
+
+For more information on how to use CMake, see the
+[CMake manual](http://cmake.org/cmake/help/documentation.html).
+
+
+@subsection new_30_multiwnd Multi-window support
+
+GLFW now supports the creation of multiple windows, each with their own OpenGL
+or OpenGL ES context, and all window functions now take a window handle.  Event
+callbacks are now per-window and are provided with the handle of the window that
+received the event.  The @ref glfwMakeContextCurrent function has been added to
+select which context is current on a given thread.
+
+
+@subsection news_30_multimon Multi-monitor support
+
+GLFW now explicitly supports multiple monitors.  They can be enumerated with
+@ref glfwGetMonitors, queried with @ref glfwGetVideoModes, @ref
+glfwGetMonitorPos, @ref glfwGetMonitorName and @ref glfwGetMonitorPhysicalSize,
+and specified at window creation to make the newly created window fullscren on
+that specific monitor.
+
+
+@subsection news_30_unicode Unicode support
+
+All string arguments to GLFW functions and all strings returned by GLFW use the
+UTF-8 encoding.  This includes the window title, error string, clipboard text,
+monitor and joystick names as well as the extension function arguments (as ASCII
+is a subset of UTF-8).
+
+
+@subsection news_30_clipboard Clipboard text I/O
+
+GLFW now supports reading and writing plain text to and from the system
+clipboard, with the @ref glfwGetClipboardString and @ref glfwSetClipboardString
+functions.
+
+
+@subsection news_30_gamma Gamma ramp support
+
+GLFW now supports setting and reading back the gamma ramp of monitors, with the
+@ref glfwGetGammaRamp and @ref glfwSetGammaRamp functions.  There is also @ref
+glfwSetGamma, which generates a ramp from a gamma value and then sets it.
+
+
+@subsection news_30_gles OpenGL ES and EGL support
+
+GLFW now supports the creation of OpenGL ES contexts, by setting the
+`GLFW_CLIENT_API` window hint to `GLFW_OPENGL_ES_API`, where creation of such
+contexts are supported.  Note that GLFW *does not implement* OpenGL ES, so your
+driver must provide support in a way usable by GLFW.  Modern nVidia and Intel
+drivers support creation of OpenGL ES context using the GLX and WGL APIs, while
+AMD currently only provides an EGL implementation.
+
+GLFW now has an (experimental) EGL context creation backend, which can be
+selected through CMake options.
+
+
+@subsection news_30_error Error callback
+
+GLFW now has an error callback, which can provide your application with much
+more detailed diagnostics than was previously possible.  The callback is passed
+an error code and a description string.
+
+
+@subsection news_30_wndptr Per-window user pointer
+
+Each window object has a user-defined pointer, retrieved with @ref
+glfwGetWindowUserPointer and set with @ref glfwSetWindowUserPointer, to make it
+easier to integrate GLFW into C++ code.
+
+
+@subsection news_30_iconifyfun Window iconification callback
+
+Each window object has a callback for iconification and restoration events, which is
+set with @ref glfwSetWindowIconifyCallback.
+
+
+@subsection news_30_wndposfun Window position callback
+
+Each window object has a callback for position events, which is set with @ref
+glfwSetWindowPosCallback.
+
+
+@subsection news_30_wndpos Window position query
+
+The position of a window can now be retrieved using @ref glfwGetWindowPos.
+
+
+@subsection news_30_focusfun Window focus callback
+
+Windows now have a callback for focus events, which is set with @ref
+glfwSetWindowFocusCallback.
+
+
+@subsection news_30_wndtitle Initial window title
+
+The title of a window is now specified at creation time, as one of the arguments
+to @ref glfwCreateWindow.
+
+
+@subsection news_30_hidden Hidden windows
+
+Windows can now be hidden with @ref glfwHideWindow, shown using @ref
+glfwShowWindow and created initially hidden with the `GLFW_VISIBLE` window hint.
+This allows for offscreen rendering in a way compatible with most drivers, as
+well as moving a window to a specific position before showing it.
+
+*/

docs/quick.dox

@@ -9,6 +9,10 @@ will introduce a few of the most commonly used functions, but there are many
 others.  To see detailed documentation on any GLFW function, just click on its
 name.
 
+This guide assumes no experience with earlier versions of GLFW.  If you
+have used GLFW 2.x in the past, you should also read the
+[transition guide](@ref moving).
+
 
 @section quick_include Including the GLFW header
 

docs/window.dox

@@ -0,0 +1,160 @@
+/*! @page window Window handling
+ 
+@tableofcontents
+
+The primary purpose of GLFW is to provide a simple interface to window
+management and OpenGL and OpenGL ES context creation.  GLFW supports
+multiple windows, which can be either a normal desktop window or
+a fullscreen window.
+
+@section window_object Window objects
+
+Text here.
+
+
+@section window_hints Window hints
+
+There are a number of hints that can be set before the creation of a window.
+Some affect the window itself, others its framebuffer or context.  These hints
+are set to their default values each time the library is initialized with @ref
+glfwInit, can be individually set with @ref glfwWindowHint and reset all at once
+to their defaults with @ref glfwDefaultWindowHints.
+
+Note again that they need to be set *before* the creation of the window you wish
+to have the specified properties.
+
+
+@subsection window_hints_hard Hard and soft constraints
+
+Some window hints are hard constraints.  These must match the available
+capabilities *exactly* for window and context creation to succeed.  Hints
+that are not hard constraints are matched as closely as possible, but the
+resulting window and context may differ from what these hints requested.  To
+find out the actual parameters of the created window and context, use the
+@ref glfwGetWindowParam function.
+
+The following hints are hard constraints:
+- `GLFW_STEREO`
+- `GLFW_CLIENT_API`
+
+The following additional hints are hard constraints if requesting an OpenGL
+context:
+- `GLFW_OPENGL_FORWARD_COMPAT`
+- `GLFW_OPENGL_PROFILE`
+
+Hints that do not apply to a given type of window or context are ignored.
+
+
+@subsection window_hints_fb Framebuffer related hints
+
+The `GLFW_RED_BITS`, `GLFW_GREEN_BITS`, `GLFW_BLUE_BITS`, `GLFW_ALPHA_BITS`,
+`GLFW_DEPTH_BITS` and `GLFW_STENCIL_BITS` hints specify the desired bit
+depths of the various components of the default framebuffer.
+
+The `GLFW_ACCUM_RED_BITS`, `GLFW_ACCUM_GREEN_BITS`, `GLFW_ACCUM_BLUE_BITS`
+and `GLFW_ACCUM_ALPHA_BITS` hints specify the desired bit depths of the
+various components of the accumulation buffer.
+
+The `GLFW_AUX_BUFFERS` hint specifies the desired number of auxiliary
+buffers.
+
+The `GLFW_STEREO` hint specifies whether to use stereoscopic rendering.
+
+The `GLFW_SAMPLES` hint specifies the desired number of samples to use for
+multisampling.
+
+The `GLFW_SRGB_CAPABLE` hint specifies whether the framebuffer should be
+sRGB capable.
+
+
+@subsection window_hints_ctx Context related hints
+
+The `GLFW_CLIENT_API` hint specifies which client API to create the context
+for.  Possible values are `GLFW_OPENGL_API` and `GLFW_OPENGL_ES_API`.
+
+The `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` hints
+specify the client API version that the created context must be compatible
+with.
+
+For OpenGL, these hints are *not* hard constraints, as they don't have to
+match exactly, but @ref glfwCreateWindow will still fail if the resulting
+OpenGL version is less than the one requested.  It is therefore perfectly
+safe to use the default of version 1.0 for legacy code and you will still
+get backwards-compatible contexts of version 3.0 and above when available.
+
+For OpenGL ES, these hints are hard constraints, as there is no backward
+compatibility between OpenGL ES versions.
+
+If an OpenGL context is requested, the `GLFW_OPENGL_FORWARD_COMPAT` hint
+specifies whether the OpenGL context should be forward-compatible, i.e. one
+where all functionality deprecated in the requested version of OpenGL is
+removed.  This may only be used if the requested OpenGL version is 3.0 or
+above.  If another client API is requested, this hint is ignored.
+
+If an OpenGL context is requested, the `GLFW_OPENGL_DEBUG_CONTEXT` hint
+specifies whether to create a debug OpenGL context, which may have
+additional error and performance issue reporting functionality.  If another
+client API is requested, this hint is ignored.
+
+If an OpenGL context is requested, the `GLFW_OPENGL_PROFILE` hint specifies
+which OpenGL profile to create the context for.  Possible values are one of
+`GLFW_OPENGL_CORE_PROFILE` or `GLFW_OPENGL_COMPAT_PROFILE`, or
+`GLFW_OPENGL_NO_PROFILE` to not request a specific profile.  If requesting
+an OpenGL version below 3.2, `GLFW_OPENGL_NO_PROFILE` must be used.  If
+another client API is requested, this hint is ignored.
+
+The `GLFW_CONTEXT_ROBUSTNESS` hint specifies the robustness strategy to be
+used by the context.  This can be one of `GLFW_NO_RESET_NOTIFICATION` or
+`GLFW_LOSE_CONTEXT_ON_RESET`, or `GLFW_NO_ROBUSTNESS` to not request
+a robustness strategy.
+
+
+@subsection window_hints_wnd Window related hints
+
+The `GLFW_RESIZABLE` hint specifies whether the window will be resizable by
+the user.  The window will still be resizable using the @ref
+glfwSetWindowSize function.  This hint is ignored for fullscreen windows.
+
+The `GLFW_VISIBLE` hint specifies whether the window will be initially
+visible.  This hint is ignored for fullscreen windows.
+
+
+@subsection window_hints_values Supported and default values
+
+| Name                         | Default value            | Supported values        |
+| ---------------------------- | ------------------------ | ----------------------- |
+| `GLFW_RESIZABLE`             | `GL_TRUE`                | `GL_TRUE` or `GL_FALSE` |
+| `GLFW_VISIBLE`               | `GL_TRUE`                | `GL_TRUE` or `GL_FALSE` |
+| `GLFW_RED_BITS`              | 8                        | 0 to `INT_MAX`          |
+| `GLFW_GREEN_BITS`            | 8                        | 0 to `INT_MAX`          |
+| `GLFW_BLUE_BITS`             | 8                        | 0 to `INT_MAX`          |
+| `GLFW_ALPHA_BITS`            | 8                        | 0 to `INT_MAX`          |
+| `GLFW_DEPTH_BITS`            | 24                       | 0 to `INT_MAX`          |
+| `GLFW_STENCIL_BITS`          | 8                        | 0 to `INT_MAX`          |
+| `GLFW_ACCUM_RED_BITS`        | 0                        | 0 to `INT_MAX`          |
+| `GLFW_ACCUM_GREEN_BITS`      | 0                        | 0 to `INT_MAX`          |
+| `GLFW_ACCUM_BLUE_BITS`       | 0                        | 0 to `INT_MAX`          |
+| `GLFW_ACCUM_ALPHA_BITS`      | 0                        | 0 to `INT_MAX`          |
+| `GLFW_AUX_BUFFERS`           | 0                        | 0 to `INT_MAX`          |
+| `GLFW_SAMPLES`               | 0                        | 0 to `INT_MAX`          |
+| `GLFW_STEREO`                | `GL_FALSE`               | `GL_TRUE` or `GL_FALSE` |
+| `GLFW_SRGB_CAPABLE`          | `GL_FALSE`               | `GL_TRUE` or `GL_FALSE` |
+| `GLFW_CLIENT_API`            | `GLFW_OPENGL_API`        | `GLFW_OPENGL_API` or `GLFW_OPENGL_ES_API` |
+| `GLFW_CONTEXT_VERSION_MAJOR` | 1                        | Any valid major version number of the chosen client API |
+| `GLFW_CONTEXT_VERSION_MINOR` | 0                        | Any valid minor version number of the chosen client API |
+| `GLFW_CONTEXT_ROBUSTNESS`    | `GLFW_NO_ROBUSTNESS`     | `GLFW_NO_ROBUSTNESS`, `GLFW_NO_RESET_NOTIFICATION` or `GLFW_LOSE_CONTEXT_ON_RESET` |
+| `GLFW_OPENGL_FORWARD_COMPAT` | `GL_FALSE`               | `GL_TRUE` or `GL_FALSE` |
+| `GLFW_OPENGL_DEBUG_CONTEXT`  | `GL_FALSE`               | `GL_TRUE` or `GL_FALSE` |
+| `GLFW_OPENGL_PROFILE`        | `GLFW_OPENGL_NO_PROFILE` | `GLFW_OPENGL_NO_PROFILE`, `GLFW_OPENGL_COMPAT_PROFILE` or `GLFW_OPENGL_CORE_PROFILE` |
+
+
+@section window_closing Window closing
+
+Text here.
+
+
+@section window_dims Window dimensions
+
+Text here.
+
+*/

include/GL/glfw3.h

@@ -558,9 +558,10 @@ typedef struct GLFWwindow GLFWwindow;
 /*! @brief The function signature for error callbacks.
  *  @param[in] error An [error code](@ref errors).
  *  @param[in] description A UTF-8 encoded string describing the error.
- *  @ingroup error
  *
  *  @sa glfwSetErrorCallback
+ *
+ *  @ingroup error
  */
 typedef void (* GLFWerrorfun)(int,const char*);
 
@@ -570,9 +571,10 @@ typedef void (* GLFWerrorfun)(int,const char*);
  *  the client area of the window.
  *  @param[in] ypos The new y-coordinate, in pixels, of the upper-left corner of
  *  the client area of the window.
- *  @ingroup window
  *
  *  @sa glfwSetWindowPosCallback
+ *
+ *  @ingroup window
  */
 typedef void (* GLFWwindowposfun)(GLFWwindow*,int,int);
 
@@ -580,25 +582,28 @@ typedef void (* GLFWwindowposfun)(GLFWwindow*,int,int);
  *  @param[in] window The window that the user resized.
  *  @param[in] width The new width, in pixels, of the window.
  *  @param[in] height The new height, in pixels, of the window.
- *  @ingroup window
  *
  *  @sa glfwSetWindowSizeCallback
+ *
+ *  @ingroup window
  */
 typedef void (* GLFWwindowsizefun)(GLFWwindow*,int,int);
 
 /*! @brief The function signature for window close callbacks.
  *  @param[in] window The window that the user attempted to close.
- *  @ingroup window
  *
  *  @sa glfwSetWindowCloseCallback
+ *
+ *  @ingroup window
  */
 typedef void (* GLFWwindowclosefun)(GLFWwindow*);
 
 /*! @brief The function signature for window content refresh callbacks.
  *  @param[in] window The window whose content needs to be refreshed.
- *  @ingroup window
  *
  *  @sa glfwSetWindowRefreshCallback
+ *
+ *  @ingroup window
  */
 typedef void (* GLFWwindowrefreshfun)(GLFWwindow*);
 
@@ -606,9 +611,10 @@ typedef void (* GLFWwindowrefreshfun)(GLFWwindow*);
  *  @param[in] window The window that was focused or defocused.
  *  @param[in] focused `GL_TRUE` if the window was focused, or `GL_FALSE` if
  *  it was defocused.
- *  @ingroup window
  *
  *  @sa glfwSetWindowFocusCallback
+ *
+ *  @ingroup window
  */
 typedef void (* GLFWwindowfocusfun)(GLFWwindow*,int);
 
@@ -616,9 +622,10 @@ typedef void (* GLFWwindowfocusfun)(GLFWwindow*,int);
  *  @param[in] window The window that was iconified or restored.
  *  @param[in] iconified `GL_TRUE` if the window was iconified, or `GL_FALSE`
  *  if it was restored.
- *  @ingroup window
  *
  *  @sa glfwSetWindowIconifyCallback
+ *
+ *  @ingroup window
  */
 typedef void (* GLFWwindowiconifyfun)(GLFWwindow*,int);
 
@@ -627,9 +634,10 @@ typedef void (* GLFWwindowiconifyfun)(GLFWwindow*,int);
  *  @param[in] button The [mouse button](@ref buttons) that was pressed or
  *  released.
  *  @param[in] action One of `GLFW_PRESS` or `GLFW_RELEASE`.
- *  @ingroup input
  *
  *  @sa glfwSetMouseButtonCallback
+ *
+ *  @ingroup input
  */
 typedef void (* GLFWmousebuttonfun)(GLFWwindow*,int,int);
 
@@ -637,9 +645,10 @@ typedef void (* GLFWmousebuttonfun)(GLFWwindow*,int,int);
  *  @param[in] window The window that received the event.
  *  @param[in] xpos The new x-coordinate of the cursor.
  *  @param[in] ypos The new y-coordinate of the cursor.
- *  @ingroup input
  *
  *  @sa glfwSetCursorPosCallback
+ *
+ *  @ingroup input
  */
 typedef void (* GLFWcursorposfun)(GLFWwindow*,double,double);
 
@@ -647,9 +656,10 @@ typedef void (* GLFWcursorposfun)(GLFWwindow*,double,double);
  *  @param[in] window The window that received the event.
  *  @param[in] entered `GL_TRUE` if the cursor entered the window's client
  *  area, or `GL_FALSE` if it left it.
- *  @ingroup input
  *
  *  @sa glfwSetCursorEnterCallback
+ *
+ *  @ingroup input
  */
 typedef void (* GLFWcursorenterfun)(GLFWwindow*,int);
 
@@ -657,9 +667,10 @@ typedef void (* GLFWcursorenterfun)(GLFWwindow*,int);
  *  @param[in] window The window that received the event.
  *  @param[in] xpos The scroll offset along the x-axis.
  *  @param[in] ypos The scroll offset along the y-axis.
- *  @ingroup input
  *
  *  @sa glfwSetScrollCallback
+ *
+ *  @ingroup input
  */
 typedef void (* GLFWscrollfun)(GLFWwindow*,double,double);
 
@@ -667,27 +678,30 @@ typedef void (* GLFWscrollfun)(GLFWwindow*,double,double);
  *  @param[in] window The window that received the event.
  *  @param[in] key The [keyboard key](@ref keys) that was pressed or released.
  *  @param[in] action @ref GLFW_PRESS, @ref GLFW_RELEASE or @ref GLFW_REPEAT.
- *  @ingroup input
  *
  *  @sa glfwSetKeyCallback
+ *
+ *  @ingroup input
  */
 typedef void (* GLFWkeyfun)(GLFWwindow*,int,int);
 
 /*! @brief The function signature for Unicode character callbacks.
  *  @param[in] window The window that received the event.
  *  @param[in] character The Unicode code point of the character.
- *  @ingroup input
  *
  *  @sa glfwSetCharCallback
+ *
+ *  @ingroup input
  */
 typedef void (* GLFWcharfun)(GLFWwindow*,unsigned int);
 
 /*! @brief The function signature for monitor configuration callbacks.
  *  @param[in] monitor The monitor that was connected or disconnected.
  *  @param[in] event One of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`.
- *  @ingroup monitor
  *
  *  @sa glfwSetMonitorCallback
+ *
+ *  @ingroup monitor
  */
 typedef void (* GLFWmonitorfun)(GLFWmonitor*,int);
 
@@ -1009,7 +1023,7 @@ GLFWAPI void glfwSetGammaRamp(GLFWmonitor* monitor, const GLFWgammaramp* ramp);
 /*! @brief Resets all window hints to their default values.
  *
  *  This function resets all window hints to their
- *  [default values](@ref hints).
+ *  [default values](@ref window_hints_values).
  *
  *  @note This function may only be called from the main thread.
  *
@@ -1026,100 +1040,9 @@ GLFWAPI void glfwDefaultWindowHints(void);
  *  glfwWindowHint or @ref glfwDefaultWindowHints, or until the library is
  *  terminated with @ref glfwTerminate.
  *
- *  @param[in] target The [window hint](@ref hints) to set.
+ *  @param[in] target The [window hint](@ref window_hints) to set.
  *  @param[in] hint The new value of the window hint.
  *
- *  @par Hard and soft constraints
- *
- *  Some window hints are hard constraints.  These must match the available
- *  capabilities *exactly* for window and context creation to succeed.  Hints
- *  that are not hard constraints are matched as closely as possible, but the
- *  resulting window and context may differ from what these hints requested.  To
- *  find out the actual parameters of the created window and context, use the
- *  @ref glfwGetWindowParam function.
- *
- *  The following hints are hard constraints:
- *  - `GLFW_STEREO`
- *  - `GLFW_CLIENT_API`
- *
- *  The following additional hints are hard constraints if requesting an OpenGL
- *  context:
- *  - `GLFW_OPENGL_FORWARD_COMPAT`
- *  - `GLFW_OPENGL_PROFILE`
- *
- *  Hints that do not apply to a given type of window or context are ignored.
- *
- *  @par Framebuffer hints
- *
- *  The `GLFW_RED_BITS`, `GLFW_GREEN_BITS`, `GLFW_BLUE_BITS`, `GLFW_ALPHA_BITS`,
- *  `GLFW_DEPTH_BITS` and `GLFW_STENCIL_BITS` hints specify the desired bit
- *  depths of the various components of the default framebuffer.
- *
- *  The `GLFW_ACCUM_RED_BITS`, `GLFW_ACCUM_GREEN_BITS`, `GLFW_ACCUM_BLUE_BITS`
- *  and `GLFW_ACCUM_ALPHA_BITS` hints specify the desired bit depths of the
- *  various components of the accumulation buffer.
- *
- *  The `GLFW_AUX_BUFFERS` hint specifies the desired number of auxiliary
- *  buffers.
- *
- *  The `GLFW_STEREO` hint specifies whether to use stereoscopic rendering.
- *
- *  The `GLFW_SAMPLES` hint specifies the desired number of samples to use for
- *  multisampling.
- *
- *  The `GLFW_SRGB_CAPABLE` hint specifies whether the framebuffer should be
- *  sRGB capable.
- *
- *  @par Context hints
- *
- *  The `GLFW_CLIENT_API` hint specifies which client API to create the context
- *  for.  Possible values are `GLFW_OPENGL_API` and `GLFW_OPENGL_ES_API`.
- *
- *  The `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` hints
- *  specify the client API version that the created context must be compatible
- *  with.
- *
- *  For OpenGL, these hints are *not* hard constraints, as they don't have to
- *  match exactly, but @ref glfwCreateWindow will still fail if the resulting
- *  OpenGL version is less than the one requested.  It is therefore perfectly
- *  safe to use the default of version 1.0 for legacy code and you will still
- *  get backwards-compatible contexts of version 3.0 and above when available.
- *
- *  For OpenGL ES, these hints are hard constraints, as there is no backward
- *  compatibility between OpenGL ES versions.
- *
- *  If an OpenGL context is requested, the `GLFW_OPENGL_FORWARD_COMPAT` hint
- *  specifies whether the OpenGL context should be forward-compatible, i.e. one
- *  where all functionality deprecated in the requested version of OpenGL is
- *  removed.  This may only be used if the requested OpenGL version is 3.0 or
- *  above.  If another client API is requested, this hint is ignored.
- *
- *  If an OpenGL context is requested, the `GLFW_OPENGL_DEBUG_CONTEXT` hint
- *  specifies whether to create a debug OpenGL context, which may have
- *  additional error and performance issue reporting functionality.  If another
- *  client API is requested, this hint is ignored.
- *
- *  If an OpenGL context is requested, the `GLFW_OPENGL_PROFILE` hint specifies
- *  which OpenGL profile to create the context for.  Possible values are one of
- *  `GLFW_OPENGL_CORE_PROFILE` or `GLFW_OPENGL_COMPAT_PROFILE`, or
- *  `GLFW_OPENGL_NO_PROFILE` to not request a specific profile.  If requesting
- *  an OpenGL version below 3.2, `GLFW_OPENGL_NO_PROFILE` must be used.  If
- *  another client API is requested, this hint is ignored.
- *
- *  The `GLFW_CONTEXT_ROBUSTNESS` hint specifies the robustness strategy to be
- *  used by the context.  This can be one of `GLFW_NO_RESET_NOTIFICATION` or
- *  `GLFW_LOSE_CONTEXT_ON_RESET`, or `GLFW_NO_ROBUSTNESS` to not request
- *  a robustness strategy.
- *
- *  @par Window hints
- *
- *  The `GLFW_RESIZABLE` hint specifies whether the window will be resizable by
- *  the user.  The window will still be resizable using the @ref
- *  glfwSetWindowSize function.  This hint is ignored for fullscreen windows.
- *
- *  The `GLFW_VISIBLE` hint specifies whether the window will be initially
- *  visible.  This hint is ignored for fullscreen windows.
- *
  *  @par New in GLFW 3
  *  Hints are no longer reset to their default values on window creation.  To
  *  set default hint values, use @ref glfwDefaultWindowHints.
@@ -1363,7 +1286,6 @@ GLFWAPI void glfwIconifyWindow(GLFWwindow* window);
  *  nothing.
  *
  *  @param[in] window The window to restore.
- *  @ingroup window
  *
  *  @note This function may only be called from the main thread.
  *
@@ -1371,6 +1293,8 @@ GLFWAPI void glfwIconifyWindow(GLFWwindow* window);
  *  windows.
  *
  *  @sa glfwIconifyWindow
+ *
+ *  @ingroup window
  */
 GLFWAPI void glfwRestoreWindow(GLFWwindow* window);
 
@@ -1643,7 +1567,6 @@ GLFWAPI int glfwGetInputMode(GLFWwindow* window, int mode);
  *  @param[in] mode One of `GLFW_CURSOR_MODE`, `GLFW_STICKY_KEYS` or
  *  `GLFW_STICKY_MOUSE_BUTTONS`.
  *  @param[in] value The new value of the specified input mode.
- *  @ingroup input
  *
  *  If `mode` is `GLFW_CURSOR_MODE`, the value must be one of the supported input
  *  modes:
@@ -1669,6 +1592,8 @@ GLFWAPI int glfwGetInputMode(GLFWwindow* window, int mode);
  *  GLFW_CURSOR_MODE is not yet implemented.
  *
  *  @sa glfwGetInputMode
+ *
+ *  @ingroup input
  */
 GLFWAPI void glfwSetInputMode(GLFWwindow* window, int mode, int value);
 
@@ -1826,13 +1751,19 @@ GLFWAPI void glfwSetCursorPosCallback(GLFWwindow* window, GLFWcursorposfun cbfun
 GLFWAPI void glfwSetCursorEnterCallback(GLFWwindow* window, GLFWcursorenterfun cbfun);
 
 /*! @brief Sets the scroll callback.
+ *
+ *  This function sets the scroll callback of the specified window, which is
+ *  called when a scrolling device is used, such as a mouse wheel or scrolling
+ *  area of a touchpad.
+ *
  *  @param[in] window The window whose callback to set.
  *  @param[in] cbfun The new scroll callback, or `NULL` to remove the currently
  *  set callback.
- *  @ingroup input
  *
  *  @remarks This receives all scrolling input, like that from a mouse wheel or
  *  a touchpad scrolling area.
+ *
+ *  @ingroup input
  */
 GLFWAPI void glfwSetScrollCallback(GLFWwindow* window, GLFWscrollfun cbfun);
 
@@ -1955,11 +1886,12 @@ GLFWAPI double glfwGetTime(void);
  *  up from that value.
  *
  *  @param[in] time The new value, in seconds.
- *  @ingroup time
  *
  *  @note The resolution of the timer is system dependent, but is usually on the
  *  order of a few micro- or nanoseconds.  It uses the highest-resolution
  *  monotonic time source on each supported platform.
+ *
+ *  @ingroup time
  */
 GLFWAPI void glfwSetTime(double time);
 
@@ -1973,11 +1905,12 @@ GLFWAPI void glfwSetTime(double time);
  *
  *  @param[in] window The window whose context to make current, or `NULL` to
  *  detach the current context.
- *  @ingroup context
  *
  *  @remarks This function may be called from secondary threads.
  *
  *  @sa glfwGetCurrentContext
+ *
+ *  @ingroup context
  */
 GLFWAPI void glfwMakeContextCurrent(GLFWwindow* window);
 
@@ -1988,11 +1921,12 @@ GLFWAPI void glfwMakeContextCurrent(GLFWwindow* window);
  *
  *  @return The window whose context is current, or `NULL` if no window's
  *  context is current.
- *  @ingroup context
  *
  *  @remarks This function may be called from secondary threads.
  *
  *  @sa glfwMakeContextCurrent
+ *
+ *  @ingroup context
  */
 GLFWAPI GLFWwindow* glfwGetCurrentContext(void);
 
@@ -2003,7 +1937,6 @@ GLFWAPI GLFWwindow* glfwGetCurrentContext(void);
  *  number of screen updates before swapping the buffers.
  *
  *  @param[in] window The window whose buffers to swap.
- *  @ingroup context
  *
  *  @remarks This function may be called from secondary threads.
  *
@@ -2012,6 +1945,8 @@ GLFWAPI GLFWwindow* glfwGetCurrentContext(void);
  *  @ref glfwWaitEvents yourself.
  *
  *  @sa glfwSwapInterval
+ *
+ *  @ingroup context
  */
 GLFWAPI void glfwSwapBuffers(GLFWwindow* window);
 
@@ -2023,11 +1958,12 @@ GLFWAPI void glfwSwapBuffers(GLFWwindow* window);
  *
  *  @param[in] interval The minimum number of screen updates to wait for
  *  until the buffers are swapped by @ref glfwSwapBuffers.
- *  @ingroup context
  *
  *  @remarks This function may be called from secondary threads.
  *
  *  @sa glfwSwapBuffers
+ *
+ *  @ingroup context
  */
 GLFWAPI void glfwSwapInterval(int interval);
 
@@ -2039,7 +1975,6 @@ GLFWAPI void glfwSwapInterval(int interval);
  *
  *  @param[in] extension The ASCII encoded name of the extension.
  *  @return `GL_TRUE` if the extension is available, or `GL_FALSE` otherwise.
- *  @ingroup context
  *
  *  @remarks This function may be called from secondary threads.
  *
@@ -2047,6 +1982,8 @@ GLFWAPI void glfwSwapInterval(int interval);
  *  it is recommended that you cache its results if it's going to be used
  *  freqently.  The extension strings will not change during the lifetime of
  *  a context, so there is no danger in doing this.
+ *
+ *  @ingroup context
  */
 GLFWAPI int glfwExtensionSupported(const char* extension);