Documentation work

docs/header.html

@@ -25,7 +25,6 @@ $extrastylesheet
 		<ul class="glfwnavbar">
 			<li><a href="http://www.glfw.org/documentation.html">Documentation</a></li>
 			<li><a href="http://www.glfw.org/download.html">Download</a></li>
-			<li><a href="http://www.glfw.org/media.html">Media</a></li>
 			<li><a href="http://www.glfw.org/community.html">Community</a></li>
 		</ul>
 	</div>

docs/intro.dox

@@ -82,6 +82,9 @@ Some hints are platform specific.  These may be set on any platform but they
 will only affect their specific platform.  Other platforms will simply ignore
 them.  Setting these hints requires no platform specific headers or functions.
 
+
+@subsubsection init_hints_shared Shared init hints
+
 @anchor GLFW_JOYSTICK_HAT_BUTTONS
 __GLFW_JOYSTICK_HAT_BUTTONS__ specifies whether to also expose joystick hats as
 buttons, for compatibility with earlier versions of GLFW that did not have @ref
@@ -299,35 +302,39 @@ functions not on this list will not be made non-reentrant.
 
 @subsection thread_safety Thread safety
 
-Most GLFW functions must only be called from the main thread, but some may be
+Most GLFW functions must only be called from the main thread (the thread that
-called from any thread.  However, no GLFW function may be called from any thread
+calls main), but some may be called from any thread once the library has been
-but the main thread until GLFW has been successfully initialized, including
+initialized.  Before initialization the whole library is thread-unsafe.
-functions that may called before initialization.
 
 The reference documentation for every GLFW function states whether it is limited
 to the main thread.                                                        
 
-Initialization and termination, event processing and the creation and
+Initialization, termination, event processing and the creation and
-destruction of windows, contexts and cursors are all limited to the main thread
+destruction of windows, cursors and OpenGL and OpenGL ES contexts are all
-due to limitations of one or several platforms.
+restricted to the main thread due to limitations of one or several platforms.
 
 Because event processing must be performed on the main thread, all callbacks
 except for the error callback will only be called on that thread.  The error
 callback may be called on any thread, as any GLFW function may generate errors.
 
-The posting of empty events may be done from any thread.  The window user
+The error code and description may be queried from any thread.
-pointer and close flag may also be accessed and modified from any thread, but
+
-this is not synchronized by GLFW.  The following window related functions may
+ - @ref glfwGetError
-be called from any thread:
+
+Empty events may be posted from any thread.
 
  - @ref glfwPostEmptyEvent
+
+The window user pointer and close flag may be read and written from any thread,
+but this is not synchronized by GLFW.
+
  - @ref glfwGetWindowUserPointer
  - @ref glfwSetWindowUserPointer
  - @ref glfwWindowShouldClose
  - @ref glfwSetWindowShouldClose
 
-Rendering may be done on any thread.  The following context related functions
+These functions for working with OpenGL and OpenGL ES contexts may be called
-may be called from any thread:
+from any thread, but the window object is not synchronized by GLFW.
 
  - @ref glfwMakeContextCurrent
  - @ref glfwGetCurrentContext
@@ -336,27 +343,23 @@ may be called from any thread:
  - @ref glfwExtensionSupported
  - @ref glfwGetProcAddress
 
-The raw timer may be queried from any thread.  The following raw timer related
+The raw timer functions may be called from any thread.
-functions may be called from any thread:
 
  - @ref glfwGetTimerFrequency
  - @ref glfwGetTimerValue
 
-The regular timer may be used from any thread, but the reading and writing of
+The regular timer may be used from any thread, but reading and writing the timer
-the timer offset is not synchronized by GLFW.  The following timer related
+offset is not synchronized by GLFW.
-functions may be called from any thread:
 
  - @ref glfwGetTime
  - @ref glfwSetTime
 
-Library version information may be queried from any thread.  The following
+Library version information may be queried from any thread.
-version related functions may be called from any thread:
 
  - @ref glfwGetVersion
  - @ref glfwGetVersionString
 
-Vulkan objects may be created and information queried from any thread.  The
+All Vulkan related functions may be called from any thread.
-following Vulkan related functions may be called from any thread:
 
  - @ref glfwVulkanSupported
  - @ref glfwGetRequiredInstanceExtensions
@@ -364,9 +367,9 @@ following Vulkan related functions may be called from any thread:
  - @ref glfwGetPhysicalDevicePresentationSupport
  - @ref glfwCreateWindowSurface
 
-GLFW uses no synchronization objects internally except for thread-local storage
+GLFW uses synchronization objects internally only to manage the per-thread
-to keep track of the current context for each thread.  Synchronization is left
+context and error states.  Additional synchronization is left to the
-to the application.
+application.
 
 Functions that may currently be called from any thread will always remain so,
 but functions that are currently limited to the main thread may be updated to