Documentation work.

Fixes #276.

docs/intro.dox

@@ -0,0 +1,166 @@
+/*! 
+
+@page intro Introduction to the GLFW API
+ 
+@tableofcontents
+
+This guide will introduce the basic concepts of GLFW and describes
+initialization, error handling and version management.  There are other guides
+for the various areas of the GLFW API.
+
+ - @ref window
+ - @ref context
+ - @ref monitor
+ - @ref input
+
+
+@section intro_init Initialization and termination
+
+Before most GLFW functions may be called, the library must be initialized.
+This initialization checks what features are available on the machine,
+enumerates monitors and joysticks, initializes the timer and performs any
+required platform-specific initialization.
+
+Only the following functions may be called before the library has been
+successfully initialized.
+
+ - @ref glfwGetVersion
+ - @ref glfwGetVersionString
+ - @ref glfwSetErrorCallback
+ - @ref glfwInit
+ - @ref glfwTerminate
+
+Calling any other function before that time will cause a `GLFW_NOT_INITIALIZED`
+error. 
+
+
+@subsection intro_init_init Initializing GLFW
+
+The library is initialized with @ref glfwInit, which returns `GL_FALSE` if an
+error occurred.
+
+@code
+if (!glfwInit())
+{
+    // Handle initialization failure
+}
+@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
+`GL_TRUE` immediately.
+
+Once the library has been successfully initialized, it should be terminated
+before the application exits.
+
+
+@subsection intro_init_terminate Terminating GLFW
+
+Before your application exits, you should terminate the GLFW library if it has
+been initialized.  This is done with @ref glfwTerminate.
+
+@code
+glfwTerminate();
+@endcode
+
+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.
+
+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
+library had not been successfully initialized or had already been terminated,
+additional calls return immediately. 
+
+
+@section intro_error Error handling
+
+Some GLFW functions have return values that indicate an error, but this is often
+not very helpful when trying to figure out *why* the error occurred.  Also, far
+from all GLFW functions have such return values.
+
+This is where the error callback comes in.  This callback is called whenever an
+error occurs.  It is set with @ref glfwSetErrorCallback, a function that may be
+called before @ref glfwInit and after @ref glfwTerminate.
+
+@code
+glfwSetErrorCallback(error_callback);
+@endcode
+
+The error callback receives a human-readable description of the error and (when
+possible) its cause.  The description is a regular C string using the UTF-8
+encoding.  The callback is also provided with an [error code](@ref errors). 
+
+@code
+void error_callback(int error, const char* description)
+{
+    puts(description);
+}
+@endcode
+
+The error code indicates the general category of the error.  Some error codes,
+such as `GLFW_NOT_INITIALIZED` has only a single meaning, whereas others like
+`GLFW_PLATFORM_ERROR` are used for many different errors.
+
+@note The description string is only valid until the error callback returns, as
+it may have been generated specifically for that error.  This lets GLFW provide
+much more specific error descriptions but means you must make a copy if you want
+to keep the description string.
+
+
+@section intro_version Version management
+
+GLFW provides mechanisms for identifying what version of GLFW your application
+was compiled against as well as what version it is currently using.  The GLFW
+API is binary-compatible with later minor versions, i.e. an executable using the
+3.0 API will be able to use a version 3.2 DLL.
+
+As long as an executable does not use any newer functions, it can also use an
+older minor version DLL, although any window hints or other tokens added since
+that older version will cause errors to be reported.
+
+
+@subsection intro_version_compile Compile-time version
+
+The compile-time version of GLFW is provided by the GLFW header with the
+`GLFW_VERSION_MAJOR`, `GLFW_VERSION_MINOR` and `GLFW_VERSION_REVISION` macros.
+
+
+@subsection intro_version_runtime Run-time version
+
+The run-time version can be retrieved with @ref glfwGetVersion, a function that
+may be called before @ref glfwInit and after @ref glfwTerminate 
+
+@code
+int major, minor, revision;
+glfwGetVersion(&major, &minor, &revision);
+@endcode
+
+
+@subsection intro_version_string Version string
+
+GLFW 3 also provides a compile-time generated version string that describes the
+version, platform, compiler and any platform-specific compile-time options.
+This is primarily intended for submitting bug reports, to allow developers to
+see which code paths are enabled in a binary.
+
+The version string is returned by @ref glfwGetVersionString, a function that may
+be called before @ref glfwInit and after @ref glfwTerminate.
+
+The format of the string is as follows:
+ - The version of GLFW
+ - The name of the window system API
+ - The name of the context creation API
+ - Any additional options or APIs
+
+For example, when compiling GLFW 3.0 with MinGW using the Win32 and WGL
+back ends, the version string may look something like this:
+
+    3.0.0 Win32 WGL MinGW
+
+@note Do not parse the version string to find the GLFW library version.  The
+@ref glfwGetVersion function provides the version of the library binary in
+numeric form.
+
+*/