Documentation work

README.md

@@ -6,14 +6,15 @@
 
 ## Introduction
 
-GLFW is a free, Open Source, multi-platform library for OpenGL, OpenGL ES and
-Vulkan application development.  It provides a simple, platform-independent API
-for creating windows, contexts and surfaces, reading input, handling events, etc.
+GLFW is an Open Source, multi-platform library for OpenGL, OpenGL ES and Vulkan
+application development.  It provides a simple, platform-independent API for
+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
-[reference documentation](@ref init).
+tutorial, see @ref quick_guide instead.  For details about a specific function,
+see the [reference documentation](@ref init).
 
 There are also guides for the other areas of GLFW.
 
@@ -34,8 +34,8 @@ successfully initialized, and only from the main thread.
  - @ref glfwInit
  - @ref glfwTerminate
 
-Calling any other function before that time will cause a @ref
-GLFW_NOT_INITIALIZED error. 
+Calling any other function before successful initialization will cause a @ref
+GLFW_NOT_INITIALIZED error.
 
 
 @subsection intro_init_init Initializing GLFW
@@ -50,13 +50,15 @@ if (!glfwInit())
 }
 @endcode
 
-If any part of initialization fails, all remaining bits are terminated as if
-@ref glfwTerminate was called.  The library only needs to be initialized once
-and additional calls to an already initialized library will simply return
+If any part of initialization fails, any parts that succeeded are terminated as
+if @ref glfwTerminate had been called.  The library only needs to be initialized
+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
-API.  This means that you can drop in a newer version of the GLFW DLL / shared
-library / dynamic library and existing applications will continue to run.
+GLFW guarantees source and binary backward compatibility with earlier minor
+versions of the API.  This means that you can drop in a newer version of the
+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
-custom Vulkan header then you need to include them before the GLFW header.
+If you instead want to include the Vulkan header from a custom location or use
+your own custom Vulkan header then do this before the GLFW header.
 
 @code
 #include <path/to/vulkan.h>