Documentation work

README.md

@@ -6,14 +6,15 @@
 
 ## Introduction
 
-GLFW is a free, Open Source, multi-platform library for OpenGL, OpenGL ES and
+GLFW is an Open Source, multi-platform library for OpenGL, OpenGL ES and Vulkan
-Vulkan application development.  It provides a simple, platform-independent API
+application development.  It provides a simple, platform-independent API for
-for creating windows, contexts and surfaces, reading input, handling events, etc.
+creating windows, contexts and surfaces, reading input, handling events, etc.
 
 The current stable release is version 3.2.  See the
 [downloads](http://www.glfw.org/download.html) page for details and files, or
 fetch the `latest` branch, which always points to the latest stable release.
-Each release starting with 3.0 also has a corresponding annotated tag.
+Each release starting with 3.0 also has a corresponding [annotated
+tag](https://github.com/glfw/glfw/releases) with source and binary archives.
 
 This is version 3.2.1, which is _not yet described_.
 
@@ -26,7 +27,7 @@ the GLFW 3 API.
 
 ## Compiling GLFW
 
-GLFW itself needs only the headers and libraries for your window system.  It
+GLFW itself requires only the headers and libraries for your window system.  It
 does not need the headers for any context creation API (WGL, GLX, EGL, NSGL) or
 rendering API (OpenGL, OpenGL ES, Vulkan) to enable support for them.
 
@@ -62,6 +63,8 @@ in the documentation for more information.
 
 ## Dependencies
 
+GLFW itself depends only on the headers and libraries for your window system.
+
 The examples and test programs depend on a number of tiny libraries.  These are
 located in the `deps/` directory.
 
@@ -79,7 +82,7 @@ The Vulkan example additionally requires the Vulkan SDK to be installed, or it
 will not be included in the build.
 
 The documentation is generated with [Doxygen](http://doxygen.org/).  If CMake
-does not find Doxygen, the documentation will not be generated.
+does not find Doxygen, the documentation will not be generated when you build.
 
 
 ## Reporting bugs

docs/intro.dox

@@ -4,10 +4,10 @@
  
 @tableofcontents
 
-This guide introduces the basic concepts of GLFW and describes initialization reference
+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 on a specific function, see the
+tutorial, see @ref quick_guide instead.  For details about a specific function,
-[reference documentation](@ref init).
+see the [reference documentation](@ref init).
 
 There are also guides for the other areas of GLFW.
 
@@ -34,7 +34,7 @@ successfully initialized, and only from the main thread.
  - @ref glfwInit
  - @ref glfwTerminate
 
-Calling any other function before that time will cause a @ref
+Calling any other function before successful initialization will cause a @ref
 GLFW_NOT_INITIALIZED error.
 
 
@@ -50,13 +50,15 @@ if (!glfwInit())
 }
 @endcode
 
-If any part of initialization fails, all remaining bits are terminated as if
+If any part of initialization fails, any parts that succeeded are terminated as
-@ref glfwTerminate was called.  The library only needs to be initialized once
+if @ref glfwTerminate had been called.  The library only needs to be initialized
-and additional calls to an already initialized library will simply return
+once and additional calls to an already initialized library will simply return
 `GLFW_TRUE` immediately.
 
 Once the library has been successfully initialized, it should be terminated
-before the application exits.
+before the application exits.  Modern systems are very good at freeing resources
+allocated by programs that simply exit, but GLFW sometimes has to change global
+system settings and these might not be restored without termination.
 
 
 @subsection intro_init_terminate Terminating GLFW
@@ -70,7 +72,7 @@ glfwTerminate();
 
 This will destroy any remaining window, monitor and cursor objects, restore any
 modified gamma ramps, re-enable the screensaver if it had been disabled and free
-any resources allocated by GLFW.
+any other resources allocated by GLFW.
 
 Once the library is terminated, it is as if it had never been initialized and
 you will need to initialize it again before being able to use GLFW.  If the
@@ -282,9 +284,10 @@ allow calls from any thread in future releases.
 
 @subsection compatibility Version compatibility
 
-GLFW guarantees binary backward compatibility with earlier minor versions of the
+GLFW guarantees source and binary backward compatibility with earlier minor
-API.  This means that you can drop in a newer version of the GLFW DLL / shared
+versions of the API.  This means that you can drop in a newer version of the
-library / dynamic library and existing applications will continue to run.
+library and existing programs will continue to compile and existing binaries
+will continue to run.
 
 Once a function or constant has been added, the signature of that function or
 value of that constant will remain unchanged until the next major version of

docs/vulkan.dox

@@ -39,8 +39,8 @@ before including the GLFW header.
 #include <GLFW/glfw3.h>
 @endcode
 
-If you want to include the Vulkan header from a custom location or use your own
+If you instead want to include the Vulkan header from a custom location or use
-custom Vulkan header then you need to include them before the GLFW header.
+your own custom Vulkan header then do this before the GLFW header.
 
 @code
 #include <path/to/vulkan.h>