From 80c203f3bb1259dbba8ea8bcef9e637d15e695da Mon Sep 17 00:00:00 2001 From: Camilla Berglund Date: Fri, 19 Feb 2016 10:29:13 +0100 Subject: [PATCH] Separate guide and reference documentation tags --- docs/build.dox | 8 ++++---- docs/compat.dox | 2 +- docs/compile.dox | 6 +++--- docs/context.dox | 17 ++++++++++------- docs/input.dox | 15 ++++++++------- docs/internal.dox | 2 +- docs/intro.dox | 19 +++++++++++-------- docs/main.dox | 28 ++++++++++++++-------------- docs/monitor.dox | 15 ++++++++------- docs/moving.dox | 4 ++-- docs/news.dox | 2 +- docs/quick.dox | 16 ++++++++-------- docs/rift.dox | 2 +- docs/vulkan.dox | 12 +++++++++++- docs/window.dox | 15 ++++++++------- include/GLFW/glfw3.h | 32 ++++++++++++++++---------------- 16 files changed, 107 insertions(+), 88 deletions(-) diff --git a/docs/build.dox b/docs/build.dox index 16cb35a4..4e812b38 100644 --- a/docs/build.dox +++ b/docs/build.dox @@ -1,13 +1,13 @@ /*! -@page build Building applications +@page build_guide Building applications @tableofcontents This is about compiling and linking applications that use GLFW. For information on -how to write such applications, start with the [introductory tutorial](@ref quick). -For information on how to compile the GLFW library itself, see the @ref compile -guide. +how to write such applications, start with the +[introductory tutorial](@ref quick_guide). For information on how to compile +the GLFW library itself, see @ref compile_guide. This is not a tutorial on compilation or linking. It assumes basic understanding of how to compile and link a C program as well as how to use the diff --git a/docs/compat.dox b/docs/compat.dox index be1cf70d..030d359a 100644 --- a/docs/compat.dox +++ b/docs/compat.dox @@ -1,6 +1,6 @@ /*! -@page compat Standards conformance +@page compat_guide Standards conformance @tableofcontents diff --git a/docs/compile.dox b/docs/compile.dox index 97907cc7..38710008 100644 --- a/docs/compile.dox +++ b/docs/compile.dox @@ -1,11 +1,11 @@ /*! -@page compile Compiling GLFW +@page compile_guide Compiling GLFW @tableofcontents This is about compiling the GLFW library itself. For information on how to -build applications that use GLFW, see the @ref build guide. +build applications that use GLFW, see @ref build_guide. @section compile_cmake Using CMake @@ -156,7 +156,7 @@ necessary to compile GLFW. Go ahead and compile the actual GLFW library with these files, as you would with any other project. Once the GLFW library is compiled, you are ready to build your applications, -linking it to the GLFW library. See the @ref build guide for more information. +linking it to the GLFW library. See @ref build_guide for more information. @subsection compile_options CMake options diff --git a/docs/context.dox b/docs/context.dox index 57aed221..62bbc61f 100644 --- a/docs/context.dox +++ b/docs/context.dox @@ -1,16 +1,19 @@ /*! -@page context Context guide +@page context_guide Context guide @tableofcontents This guide introduces the OpenGL and OpenGL ES context related functions of -GLFW. There are also guides for the other areas of the GLFW API. +GLFW. For details on a specific function, see the +[reference documentation](@ref context). There are also guides for the other +areas of the GLFW API. - - @ref intro - - @ref window - - @ref monitor - - @ref input + - @ref intro_guide + - @ref window_guide + - @ref vulkan_guide + - @ref monitor_guide + - @ref input_guide @section context_object Context objects @@ -29,7 +32,7 @@ the `glfwinfo` test program. @note Vulkan does not have a context and the Vulkan instance is created via the Vulkan API itself. If you will be using Vulkan to render to a window, disable context creation by setting the [GLFW_CLIENT_API](@ref window_hints_ctx) hint to -`GLFW_NO_API`. For more information, see the @ref vulkan. +`GLFW_NO_API`. For more information, see the @ref vulkan_guide. @subsection context_hints Context creation hints diff --git a/docs/input.dox b/docs/input.dox index 5798fde4..136319b9 100644 --- a/docs/input.dox +++ b/docs/input.dox @@ -1,16 +1,17 @@ /*! -@page input Input guide +@page input_guide Input guide @tableofcontents -This guide introduces the input related functions of GLFW. There are also -guides for the other areas of GLFW. +This guide introduces the input related functions of GLFW. For details on +a specific function, see the [reference documentation](@ref input). There are +also guides for the other areas of GLFW. - - @ref intro - - @ref window - - @ref context - - @ref monitor + - @ref intro_guide + - @ref window_guide + - @ref context_guide + - @ref monitor_guide GLFW provides many kinds of input. While some can only be polled, like time, or only received via callbacks, like scrolling, there are those that provide both diff --git a/docs/internal.dox b/docs/internal.dox index 0389af6e..593ad67d 100644 --- a/docs/internal.dox +++ b/docs/internal.dox @@ -1,6 +1,6 @@ /*! -@page internals Internal structure +@page internals_guide Internal structure @tableofcontents diff --git a/docs/intro.dox b/docs/intro.dox index a54bf96f..b0be0a8b 100644 --- a/docs/intro.dox +++ b/docs/intro.dox @@ -1,18 +1,21 @@ /*! -@page intro Introduction to the API +@page intro_guide Introduction to the API @tableofcontents -This guide introduces the basic concepts of GLFW and describes initialization, +This guide introduces the basic concepts of GLFW and describes initialization reference error handling and API guarantees and limitations. For a broad but shallow -tutorial, see @ref quick instead. There are also guides for the other areas of -GLFW. +tutorial, see @ref quick_guide instead. For details on a specific function, see the +[reference documentation](@ref init). - - @ref window - - @ref context - - @ref monitor - - @ref input +There are also guides for the other areas of GLFW. + + - @ref window_guide + - @ref context_guide + - @ref vulkan_guide + - @ref monitor_guide + - @ref input_guide @section intro_init Initialization and termination diff --git a/docs/main.dox b/docs/main.dox index 9b59822e..9669001b 100644 --- a/docs/main.dox +++ b/docs/main.dox @@ -11,20 +11,20 @@ for creating windows, contexts and surfaces, reading input, handling events, etc See @ref news_32 for release highlights or the [version history](http://www.glfw.org/changelog.html) for details. -@ref quick is a guide for those new to GLFW. It takes you through how to write -a small but complete program. For people coming from GLFW 2, the @ref moving -guide explains what has changed and how to update existing code to use the new -API. +@ref quick_guide is a guide for those new to GLFW. It takes you through how to +write a small but complete program. For people coming from GLFW 2, @ref +moving_guide explains what has changed and how to update existing code to use +the new API. There are guides for each of the various areas of the API. - - @ref intro – initialization, error handling and high-level design - - @ref window – creating and working with windows and framebuffers - - @ref context – working with OpenGL and OpenGL ES contexts - - @ref monitor – enumerating and working with monitors and video modes - - @ref input – receiving events, polling and processing input + - @ref intro_guide – initialization, error handling and high-level design + - @ref window_guide – creating and working with windows and framebuffers + - @ref context_guide – working with OpenGL and OpenGL ES contexts + - @ref monitor_guide – enumerating and working with monitors and video modes + - @ref input_guide – receiving events, polling and processing input -Once you have written a program, see the @ref compile and @ref build guides. +Once you have written a program, see @ref compile_guide and @ref build_guide. The [reference documentation](modules.html) provides more detailed information about specific functions. @@ -32,15 +32,15 @@ about specific functions. There is a section on @ref guarantees_limitations for pointer lifetimes, reentrancy, thread safety, event order and backward and forward compatibility. -The @ref vulkan guide fills in the gaps for how to use Vulkan with GLFW. +The @ref vulkan_guide guide fills in the gaps for how to use Vulkan with GLFW. -The @ref rift fills in the gaps for how to use LibOVR with GLFW. +The @ref rift_guide fills in the gaps for how to use LibOVR with GLFW. The [FAQ](http://www.glfw.org/faq.html) answers many common questions about the design, implementation and use of GLFW. -Finally, the @ref compat guide explains what APIs, standards and protocols GLFW -uses and what happens when they are not present on a given machine. +Finally, the @ref compat_guide guide explains what APIs, standards and protocols +GLFW uses and what happens when they are not present on a given machine. This documentation was generated with Doxygen. The sources for it are available in both the [source distribution](http://www.glfw.org/download.html) and diff --git a/docs/monitor.dox b/docs/monitor.dox index 3b3c843c..16fb1c82 100644 --- a/docs/monitor.dox +++ b/docs/monitor.dox @@ -1,16 +1,17 @@ /*! -@page monitor Monitor guide +@page monitor_guide Monitor guide @tableofcontents -This guide introduces the monitor related functions of GLFW. There are also -guides for the other areas of GLFW. +This guide introduces the monitor related functions of GLFW. For details on +a specific function, see the [reference documentation](@ref monitor). There are +also guides for the other areas of GLFW. - - @ref intro - - @ref window - - @ref context - - @ref input + - @ref intro_guide + - @ref window_guide + - @ref context_guide + - @ref input_guide @section monitor_object Monitor objects diff --git a/docs/moving.dox b/docs/moving.dox index a222a357..7baab6f1 100644 --- a/docs/moving.dox +++ b/docs/moving.dox @@ -1,6 +1,6 @@ /*! -@page moving Moving from GLFW 2 to 3 +@page moving_guide Moving from GLFW 2 to 3 @tableofcontents @@ -130,7 +130,7 @@ GLFW 3 provides support for multiple monitors. To request a full screen mode wi instead of passing `GLFW_FULLSCREEN` you specify which monitor you wish the window to use. The @ref glfwGetPrimaryMonitor function returns the monitor that GLFW 2 would have selected, but there are many other -[monitor functions](@ref monitor). Monitor handles are pointers to the +[monitor functions](@ref monitor_guide). Monitor handles are pointers to the [opaque](https://en.wikipedia.org/wiki/Opaque_data_type) type @ref GLFWmonitor. @par Old basic full screen diff --git a/docs/news.dox b/docs/news.dox index 0ccb4c89..ed13fb7f 100644 --- a/docs/news.dox +++ b/docs/news.dox @@ -96,7 +96,7 @@ and the cursor position directly instead of returning cached data. @subsection news_31_libovr Better interoperability with Oculus Rift GLFW now provides native access functions for the OS level handles corresponding -to monitor objects, as well as a [brief guide](@ref rift). It is also regularly +to monitor objects, as well as the @ref rift_guide. It is also regularly tested for compatibility with the latest version of LibOVR (0.4.4 on release). diff --git a/docs/quick.dox b/docs/quick.dox index 54393272..dccc834d 100644 --- a/docs/quick.dox +++ b/docs/quick.dox @@ -1,6 +1,6 @@ /*! -@page quick Getting started +@page quick_guide Getting started @tableofcontents @@ -10,7 +10,7 @@ and exit when the user closes the window or presses _Escape_. This guide will introduce a few of the most commonly used functions, but there are many more. This guide assumes no experience with earlier versions of GLFW. If you -have used GLFW 2 in the past, read the @ref moving guide, as some functions +have used GLFW 2 in the past, read @ref moving_guide, as some functions behave differently in GLFW 3. @@ -346,11 +346,11 @@ This tutorial used only a few of the many functions GLFW provides. There are guides for each of the areas covered by GLFW. Each guide will introduce all the functions for that category. - - @ref intro - - @ref window - - @ref context - - @ref monitor - - @ref input + - @ref intro_guide + - @ref window_guide + - @ref context_guide + - @ref monitor_guide + - @ref input_guide You can access reference documentation for any GLFW function by clicking it and the reference for each function links to related functions and guide sections. @@ -359,6 +359,6 @@ The tutorial ends here. Once you have written a program that uses GLFW, you will need to compile and link it. How to do that depends on the development environment you are using and is best explained by the documentation for that environment. To learn about the details that are specific to GLFW, see -@ref build. +@ref build_guide. */ diff --git a/docs/rift.dox b/docs/rift.dox index edf206f7..bb518dd7 100644 --- a/docs/rift.dox +++ b/docs/rift.dox @@ -1,6 +1,6 @@ /*! -@page rift Oculus Rift guide +@page rift_guide Oculus Rift guide @tableofcontents diff --git a/docs/vulkan.dox b/docs/vulkan.dox index af9ffce0..97099f87 100644 --- a/docs/vulkan.dox +++ b/docs/vulkan.dox @@ -1,6 +1,6 @@ /*! -@page vulkan Vulkan guide +@page vulkan_guide Vulkan guide @tableofcontents @@ -18,6 +18,16 @@ The GLFW library does not need the Vulkan SDK to enable support for Vulkan. However, any Vulkan-specific test and example programs are built only if the CMake files find a Vulkan SDK. +For details on a specific function, see the +[reference documentation](@ref vulkan). There are also guides for the other +areas of the GLFW API. + + - @ref intro_guide + - @ref window_guide + - @ref context_guide + - @ref monitor_guide + - @ref input_guide + @section vulkan_include Including the Vulkan and GLFW header files diff --git a/docs/window.dox b/docs/window.dox index acb58858..1612e274 100644 --- a/docs/window.dox +++ b/docs/window.dox @@ -1,16 +1,17 @@ /*! -@page window Window guide +@page window_guide Window guide @tableofcontents -This guide introduces the window related functions of GLFW. There are also -guides for the other areas of GLFW. +This guide introduces the window related functions of GLFW. For details on +a specific function, see the [reference documentation](@ref window). There are +also guides for the other areas of GLFW. - - @ref intro - - @ref context - - @ref monitor - - @ref input + - @ref intro_guide + - @ref context_guide + - @ref monitor_guide + - @ref input_guide @section window_object Window objects diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h index 3b07bdf5..43b33f14 100644 --- a/include/GLFW/glfw3.h +++ b/include/GLFW/glfw3.h @@ -46,37 +46,37 @@ extern "C" { * * For more information about how to use this file, see @ref build_include. */ -/*! @defgroup context Context handling +/*! @defgroup context Context reference * - * This is the reference documentation for context related functions. For more - * information, see the @ref context. + * 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 support +/*! @defgroup vulkan Vulkan reference * - * This is the reference documentation for Vulkan related functions. For more - * information, see the @ref 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 errors +/*! @defgroup init Initialization, version and error reference * * This is the reference documentation for initialization and termination of - * the library, version management and error handling. For more information, - * see the @ref intro. + * the library, version management and error handling. For more task-oriented + * information, see the @ref intro_guide. */ -/*! @defgroup input Input handling +/*! @defgroup input Input reference * * This is the reference documentation for input related functions and types. - * For more information, see the @ref input. + * For more task-oriented information, see the @ref input_guide. */ -/*! @defgroup monitor Monitor handling +/*! @defgroup monitor Monitor reference * * This is the reference documentation for monitor related functions and types. - * For more information, see the @ref monitor. + * For more task-oriented information, see the @ref monitor_guide. */ -/*! @defgroup window Window handling +/*! @defgroup window Window reference * * This is the reference documentation for window related functions and types, - * including creation, deletion and event polling. For more information, see - * the @ref window. + * including creation, deletion and event polling. For more task-oriented + * information, see the @ref window_guide. */