Documentation work

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

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

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

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.
 

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
 
 

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

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.