Documentation work

docs/vulkan.dox

@@ -4,22 +4,24 @@
  
 @tableofcontents
 
-This guide is intended to fill the gaps between the Vulkan documentation and the
-rest of the GLFW documentation and is not a replacement for either.
+This guide is intended to fill the gaps between the [Vulkan
+documentation](https://www.khronos.org/vulkan/) and the rest of the GLFW
+documentation and is not a replacement for either.  It assumes some familiarity
+with Vulkan concepts like loaders, devices, queues and surfaces.
 
 To develop for Vulkan you should install an SDK for your platform, for example
-the [LunarG Vulkan SDK](http://lunarg.com/vulkan-sdk/).  Apart from the headers
-and libraries, it also provides the validation layers necessary for development.
+the [LunarG Vulkan SDK](https://vulkan.lunarg.com/).  Apart from the headers and
+libraries, it also provides the validation layers necessary for development.
 
-GLFW itself does not need a Vulkan SDK to enable support for Vulkan.  However,
-any Vulkan-specific test and example programs are built only if the CMake files
-find the LunarG SDK.
+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.
 
 
 @section vulkan_include Including the Vulkan and GLFW header files
 
-To include the Vulkan header, define `GLFW_INCLUDE_VULKAN` before including the
-GLFW header.
+To include the Vulkan header, define [GLFW_INCLUDE_VULKAN](@ref build_macros)
+before including the GLFW header.
 
 @code
 #define GLFW_INCLUDE_VULKAN
@@ -30,15 +32,15 @@ If you want to include the Vulkan header from a custom location or use your own
 custom Vulkan header then you need to include them before the GLFW header.
 
 @code
-#include <custom/path/vulkan.h>
+#include <path/to/vulkan.h>
 #include <GLFW/glfw3.h>
 @endcode
 
 Unless a Vulkan header is included, either by the GLFW header or above it, any
-GLFW functions that use Vulkan types will not be declared.
+GLFW functions that take or return Vulkan types will not be declared.
 
 The `VK_USE_PLATFORM_*_KHR` macros do not need to be defined for the Vulkan part
-of GLFW to work.
+of GLFW to work.  Define them only if you are using these extensions directly.
 
 
 @section vulkan_support Querying for Vulkan support
@@ -110,8 +112,9 @@ be passed to @ref glfwGetPhysicalDevicePresentationSupport and @ref
 glfwCreateWindowSurface.  The set of extensions will vary depending on platform
 and may also vary depending on graphics drivers and other factors.
 
-If it fails it will return `NULL` and Vulkan window surface creation will not be
-possible.  You may still use Vulkan for off-screen rendering and compute work.
+If it fails it will return `NULL` and GLFW will not be able to create Vulkan
+window surfaces.  You can still use Vulkan for off-screen rendering and compute
+work.
 
 The returned array will always contain `VK_KHR_surface`, so if you don't
 require any additional extensions you can pass this list directly to the
@@ -134,7 +137,7 @@ array, as it is an error to specify an extension more than once in the
 
 @section vulkan_present Querying for Vulkan presentation support
 
-Not every Vulkan queue family of every device can present images to surfaces.
+Not every queue family of every Vulkan device can present images to surfaces.
 To check whether a specific queue family of a physical device supports image
 presentation without first having to create a window and surface, call @ref
 glfwGetPhysicalDevicePresentationSupport.
@@ -146,15 +149,15 @@ if (glfwGetPhysicalDevicePresentationSupport(instance, physical_device, queue_fa
 }
 @endcode
 
-The `VK_KHR_surface` extension also provides the 
+The `VK_KHR_surface` extension additionally provides the 
 `vkGetPhysicalDeviceSurfaceSupportKHR` function, which performs the same test on
 an existing Vulkan surface.
 
 
 @section vulkan_window Creating the window
 
-Unless you will be using OpenGL or OpenGL ES in addition to Vulkan, there is no
-need to create a context for that window.  You can disable context creation by
+Unless you will be using OpenGL or OpenGL ES with the same window as Vulkan,
+there is no need to create a context.  You can disable context creation by
 setting the [GLFW_CLIENT_API](@ref window_hints_ctx) hint to `GLFW_NO_API`.
 
 @code