From 0f12be7549ac463cc56e6a2cf0afbd8df0b84dc2 Mon Sep 17 00:00:00 2001 From: Camilla Berglund Date: Thu, 11 Aug 2016 19:04:21 +0200 Subject: [PATCH] Documentation work --- .github/CONTRIBUTING.md | 33 +++++++++++++++++++++++++-------- docs/context.dox | 5 ++--- docs/input.dox | 5 +++-- docs/intro.dox | 4 ++-- docs/monitor.dox | 5 +++-- docs/vulkan.dox | 5 ++--- docs/window.dox | 9 +++++++-- 7 files changed, 44 insertions(+), 22 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index ee0d0a7c..672264dc 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -19,13 +19,17 @@ ## Asking a question -Questions about how to use GLFW should be asked in the [support -section](http://discourse.glfw.org/c/support) of the forum or in the IRC channel -`#glfw` on [Freenode](http://freenode.net/). +Questions about how to use GLFW should be asked either in the [support +section](http://discourse.glfw.org/c/support) of the forum, under the [Stack +Overflow tag](https://stackoverflow.com/questions/tagged/glfw) or [Game +Development tag](https://gamedev.stackexchange.com/questions/tagged/glfw) on +Stack Exchange or in the IRC channel `#glfw` on +[Freenode](http://freenode.net/). Questions about the design or implementation of GLFW or about future plans should be asked in the [dev section](http://discourse.glfw.org/c/dev) of the -forum or in the IRC channel `#glfw` on [Freenode](http://freenode.net/). +forum or in the IRC channel. Please don't open a GitHub issue to discuss design +questions without first checking with a maintainer. ## Reporting a bug @@ -38,6 +42,15 @@ doesn't, that might be a separate bug. If GLFW is crashing or triggering asserts, make sure that all your object handles and other pointers are valid. +For bugs where it makes sense, a [Short, Self Contained, Correct (Compilable), +Example](http://www.sscce.org/) is absolutely invaluable. Just put it inline in +the body text. Note that if the bug is reproducible with one of the test +programs that come with GLFW, just mention that instead. + +__Don't worry about adding too much information__. Unimportant information can +be abbreviated or removed later, but missing information can stall bug fixing, +especially when your schedule doesn't align with that of the maintainer. + There are issue labels for both platforms and GPU manufacturers, so there is no need to mention these in the subject line. If you do, it will be removed when the issue is labeled. @@ -261,13 +274,17 @@ Please explain why you need the feature and how you intend to use it. If you have a specific API design in mind, please add that as well. If you have or are planning to write code for the feature, see the section below. +If there already is a request for the feature you need, add your specific use +case unless it is already mentioned. If it is, give it a :+1:. + ## Contributing a bug fix -__Note:__ You must have all necessary rights to any code you contribute. If you -did not write the code yourself, you must explain where it came from and under -what license. Even code using the same license as GLFW may not be copied -without attribution. +__Note:__ You must have all necessary [intellectual +property rights](https://en.wikipedia.org/wiki/Intellectual_property) to any +code you contribute. If you did not write the code yourself, you must explain +where it came from and under what license you received it. Even code using the +same license as GLFW may not be copied without attribution. __There is no preferred patch size__. A one character fix is just as welcome as a thousand line one, if that is the appropriate size for the fix. diff --git a/docs/context.dox b/docs/context.dox index 7cc1f120..ad3b1848 100644 --- a/docs/context.dox +++ b/docs/context.dox @@ -5,9 +5,8 @@ @tableofcontents This guide introduces the OpenGL and OpenGL ES context related functions of -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. +GLFW. For details on a specific function in this category, see the @ref +context. There are also guides for the other areas of the GLFW API. - @ref intro_guide - @ref window_guide diff --git a/docs/input.dox b/docs/input.dox index 7ac3f229..1a06e62a 100644 --- a/docs/input.dox +++ b/docs/input.dox @@ -5,12 +5,13 @@ @tableofcontents 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. +a specific function in this category, see the @ref input. There are also guides +for the other areas of GLFW. - @ref intro_guide - @ref window_guide - @ref context_guide + - @ref vulkan_guide - @ref monitor_guide GLFW provides many kinds of input. While some can only be polled, like time, or diff --git a/docs/intro.dox b/docs/intro.dox index 4ae189c2..f7840800 100644 --- a/docs/intro.dox +++ b/docs/intro.dox @@ -6,8 +6,8 @@ This guide introduces the basic concepts of GLFW and describes initialization, error handling and API guarantees and limitations. For a broad but shallow -tutorial, see @ref quick_guide instead. For details about a specific function, -see the [reference documentation](@ref init). +tutorial, see @ref quick_guide instead. For details on a specific function in +this category, see the @ref init. There are also guides for the other areas of GLFW. diff --git a/docs/monitor.dox b/docs/monitor.dox index 0f50a3c7..0aa0b050 100644 --- a/docs/monitor.dox +++ b/docs/monitor.dox @@ -5,12 +5,13 @@ @tableofcontents 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. +a specific function in this category, see the @ref monitor. There are also +guides for the other areas of GLFW. - @ref intro_guide - @ref window_guide - @ref context_guide + - @ref vulkan_guide - @ref input_guide diff --git a/docs/vulkan.dox b/docs/vulkan.dox index a9cefd27..e704222a 100644 --- a/docs/vulkan.dox +++ b/docs/vulkan.dox @@ -18,9 +18,8 @@ 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. +For details on a specific function in this category, see the @ref vulkan. There +are also guides for the other areas of the GLFW API. - @ref intro_guide - @ref window_guide diff --git a/docs/window.dox b/docs/window.dox index 2a04dd25..0f2a6844 100644 --- a/docs/window.dox +++ b/docs/window.dox @@ -5,11 +5,12 @@ @tableofcontents 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. +a specific function in this category, see the @ref window. There are also +guides for the other areas of GLFW. - @ref intro_guide - @ref context_guide + - @ref vulkan_guide - @ref monitor_guide - @ref input_guide @@ -268,6 +269,10 @@ creation API is used on a given platform may fail if you change this hint. This can be resolved by having it load via @ref glfwGetProcAddress, which always uses the selected API. +@bug On some Linux systems, creating contexts via both the native and EGL APIs +in a single process will cause the application to segfault. Stick to one API or +the other on Linux for now. + `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` specify the client API version that the created context must be compatible with. The exact behavior of these hints depend on the requested client API.