Documentation work.

Added window hints table, added detailed description of all public
functions, added project brief and added missing language to transition
guide.

docs/Doxyfile.in

@@ -38,7 +38,7 @@ PROJECT_NUMBER         = @GLFW_VERSION_FULL@
 # for a project that appears at the top of each page and should give viewer
 # a quick idea about the purpose of the project. Keep the description short.
 
-PROJECT_BRIEF          =
+PROJECT_BRIEF          = "A multi-platform library for OpenGL, window and input"
 
 # With the PROJECT_LOGO tag one can specify an logo or icon that is
 # included in the documentation. The maximum height of the logo should not
@@ -88,7 +88,7 @@ BRIEF_MEMBER_DESC      = YES
 # Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the
 # brief descriptions will be completely suppressed.
 
-REPEAT_BRIEF           = YES
+REPEAT_BRIEF           = NO
 
 # This tag implements a quasi-intelligent brief description abbreviator
 # that is used to form the text in various listings. Each string
@@ -106,7 +106,7 @@ ABBREVIATE_BRIEF       =
 # Doxygen will generate a detailed section even if there is only a brief
 # description.
 
-ALWAYS_DETAILED_SEC    = NO
+ALWAYS_DETAILED_SEC    = YES
 
 # If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all
 # inherited members of a class in the documentation of that class as if those

docs/hints.dox

@@ -0,0 +1,39 @@
+/*!
+
+@page hints Window hints
+
+These are all window hints.  Some relate to the window itself, others to its
+framebuffer or context.  They are set to their default values by @ref glfwInit,
+can be individually set with @ref glfwWindowHint and reset all at once to their
+defaults with @ref glfwDefaultWindowHints.
+
+Note that hints need to be set *before* the creation of the window you wish to
+have the specified properties.
+
+| Name                         | Default values           | Supported values        |
+| ---------------------------- | ------------------------ | ----------------------- |
+| `GLFW_RESIZABLE`             | `GL_TRUE`                | `GL_TRUE` or `GL_FALSE` |
+| `GLFW_VISIBLE`               | `GL_TRUE`                | `GL_TRUE` or `GL_FALSE` |
+| `GLFW_RED_BITS`              | 8                        | 0 to `INT_MAX`          |
+| `GLFW_GREEN_BITS`            | 8                        | 0 to `INT_MAX`          |
+| `GLFW_BLUE_BITS`             | 8                        | 0 to `INT_MAX`          |
+| `GLFW_ALPHA_BITS`            | 8                        | 0 to `INT_MAX`          |
+| `GLFW_DEPTH_BITS`            | 24                       | 0 to `INT_MAX`          |
+| `GLFW_STENCIL_BITS`          | 8                        | 0 to `INT_MAX`          |
+| `GLFW_ACCUM_RED_BITS`        | 0                        | 0 to `INT_MAX`          |
+| `GLFW_ACCUM_GREEN_BITS`      | 0                        | 0 to `INT_MAX`          |
+| `GLFW_ACCUM_BLUE_BITS`       | 0                        | 0 to `INT_MAX`          |
+| `GLFW_ACCUM_ALPHA_BITS`      | 0                        | 0 to `INT_MAX`          |
+| `GLFW_AUX_BUFFERS`           | 0                        | 0 to `INT_MAX`          |
+| `GLFW_SAMPLES`               | 0                        | 0 to `INT_MAX`          |
+| `GLFW_STEREO`                | `GL_FALSE`               | `GL_TRUE` or `GL_FALSE` |
+| `GLFW_SRGB_CAPABLE`          | `GL_FALSE`               | `GL_TRUE` or `GL_FALSE` |
+| `GLFW_CLIENT_API`            | `GLFW_OPENGL_API`        | `GLFW_OPENGL_API` or `GLFW_OPENGL_ES_API` |
+| `GLFW_CONTEXT_VERSION_MAJOR` | 1                        | Any valid major version number of the chosen client API |
+| `GLFW_CONTEXT_VERSION_MINOR` | 0                        | Any valid minor version number of the chosen client API |
+| `GLFW_CONTEXT_ROBUSTNESS`    | `GLFW_NO_ROBUSTNESS`     | `GLFW_NO_ROBUSTNESS`, `GLFW_NO_RESET_NOTIFICATION` or `GLFW_LOSE_CONTEXT_ON_RESET` |
+| `GLFW_OPENGL_FORWARD_COMPAT` | `GL_FALSE`               | `GL_TRUE` or `GL_FALSE` |
+| `GLFW_OPENGL_DEBUG_CONTEXT`  | `GL_FALSE`               | `GL_TRUE` or `GL_FALSE` |
+| `GLFW_OPENGL_PROFILE`        | `GLFW_OPENGL_NO_PROFILE` | `GLFW_OPENGL_NO_PROFILE`, `GLFW_OPENGL_COMPAT_PROFILE` or `GLFW_OPENGL_CORE_PROFILE` |
+
+*/

docs/moving.dox

@@ -68,7 +68,7 @@ callback, *not* the removal of the character callback itself.
 Scroll events do not represent an absolute state.  Instead, it's an
 interpretation of a relative change in state, like character input.  So, like
 character input, there is no sane 'current state' to return.  The mouse wheel
-callback has been replaced by a [scroll callback](@ref GFLWscrollfun) that
+callback has been replaced by a [scroll callback](@ref GLFWscrollfun) that
 receives two-dimensional scroll offsets.
 
 
@@ -127,8 +127,10 @@ these hotkeys to function even when running in fullscreen mode.
 @subsection moving_window_handles Window handles
 
 Because GLFW 3 supports multiple windows, window handle parameters have been
-added to all window-related GLFW functions and callbacks.  Window handles are of
-the `GLFWwindow*` type, i.e. a pointer to an opaque struct.
+added to all window-related GLFW functions and callbacks.  The handle of
+a newly created window is returned by @ref glfwCreateWindow (formerly
+`glfwOpenWindow`).  Window handles are of the `GLFWwindow*` type, i.e. a pointer
+to an opaque struct.
 
 
 @subsection moving_monitor Multi-monitor support
@@ -195,9 +197,17 @@ make it do so by defining `GLFW_INCLUDE_GLU` before the inclusion of the GLFW
 
 @subsection moving_cursor Cursor positioning
 
-GLFW 3 only allows you to position the cursor within a window (using @ref
-glfwSetCursorPos) when that window is active.  Unless the window is active, the
-function fails silently.
+GLFW 3 only allows you to position the cursor within a window using @ref
+glfwSetCursorPos (formerly `glfwSetMousePos`) when that window is active.
+Unless the window is active, the function fails silently.
+
+
+@subsection moving_hints Persistent window hints
+
+Window hints are no longer reset to their default values on window creation, but
+instead retain their values until modified by @ref glfwWindowHint (formerly
+`glfwOpenWindowHint`) or @ref glfwDefaultWindowHints, or until the library is
+terminated and re-initialized.
 
 
 @section moving_renamed Name changes