Added internal docs.

CMakeLists.txt

@@ -19,7 +19,7 @@ find_package(Doxygen)
 
 option(GLFW_DOCUMENT_INTERNALS "Include internals in documentation" OFF)
 if (GLFW_DOCUMENT_INTERNALS)
-    set(GLFW_DOC_HEADERS "${GLFW_SOURCE_DIR}/src/internal.h")
+    set(GLFW_INTERNAL_DOCS "${GLFW_SOURCE_DIR}/src/internal.h ${GLFW_SOURCE_DIR}/docs/internal.dox")
 endif()
 
 if (APPLE)

docs/Doxyfile.in

@@ -668,7 +668,17 @@ WARN_LOGFILE           = @GLFW_BINARY_DIR@/docs/warnings.txt
 # directories like "/usr/src/myproject". Separate the files or directories
 # with spaces.
 
-INPUT                  = @GLFW_DOC_HEADERS@ @GLFW_SOURCE_DIR@/include/GLFW/ @GLFW_SOURCE_DIR@/docs/
+INPUT                  = @GLFW_INTERNAL_DOCS@                         \
+                         @GLFW_SOURCE_DIR@/include/GLFW/glfw3.h       \
+                         @GLFW_SOURCE_DIR@/include/GLFW/glfw3native.h \
+                         @GLFW_SOURCE_DIR@/docs/compat.dox            \
+                         @GLFW_SOURCE_DIR@/docs/context.dox           \
+                         @GLFW_SOURCE_DIR@/docs/main.dox              \
+                         @GLFW_SOURCE_DIR@/docs/monitor.dox           \
+                         @GLFW_SOURCE_DIR@/docs/moving.dox            \
+                         @GLFW_SOURCE_DIR@/docs/news.dox              \
+                         @GLFW_SOURCE_DIR@/docs/quick.dox             \
+                         @GLFW_SOURCE_DIR@/docs/window.dox
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is

docs/internal.dox

@@ -0,0 +1,116 @@
+/*!
+
+@page internals Internal structure
+
+@tableofcontents
+
+There are several interfaces inside GLFW.  Each interface has its own area of
+responsibility and its own naming conventions.
+
+
+@section internals_public Public interface
+
+The most well-known is the public interface, described in the glfw3.h header
+file.  This is implemented in source files shared by all platforms and these
+files contain no platform-specific code.  This code usually ends up calling the
+platform and internal interfaces to do the actual work.
+
+The public interface uses the OpenGL naming conventions except with GLFW and
+glfw instead of GL and gl.  For struct members, where OpenGL sets no precedent,
+it use headless camel case.
+
+Examples: @ref glfwCreateWindow, @ref GLFWwindow, @ref GLFWvidmode.redBits,
+`GLFW_RED_BITS`
+
+
+@section internals_native Native interface
+
+The [native interface](@ref native) is a small set of publicly available
+but platform-specific functions, described in the glfw3native.h header file and
+used to gain access to the underlying window, context and (on some platforms)
+display handles used by the platform interface.
+
+The function names of the native interface are similar to those of the public
+interface, but embeds the name of the interface that the returned handle is
+from.
+
+Examples: @ref glfwGetX11Window, @ref glfwGetWGLContext
+
+
+@section internals_internal Internal interface
+
+The internal interface consists of utility functions used by all other
+interfaces.  It is shared code implemented in the same shared source files as
+the public and event interfaces.  The internal interface is described in the
+internal.h header file.
+
+The internal interface is in charge of GLFW's global data, which it stores in
+a `_GLFWlibrary` struct named `_glfw`.
+
+The internal interface uses the same style as the public interface, except all
+global names have a leading underscore.
+
+Examples: @ref _glfwIsValidContextConfig, @ref _GLFWwindow, `_glfw.currentRamp`
+
+
+@section internals_platform Platform interface
+
+The platform interface implements all platform-specific operations as a service
+to the public interface.  This includes event processing.  The platform
+interface is never directly called by users of GLFW and never directly calls the
+user's code.  It is also prohibited from modifying the platform-independent part
+of the internal structs.  Instead, it calls the event interface when events
+interesting to GLFW are received.
+
+The platform interface mirrors those parts of the public interface that needs to
+perform platform-specific operations on some or all platforms.  The are also
+named the same except that the glfw function prefix is replaced by
+_glfwPlatform.
+
+Examples: @ref _glfwPlatformCreateWindow
+
+The platform interface also defines structs that contain platform-specific
+global and per-object state.  Their names mirror those of the internal
+interface, except that an interface-specific suffix is added.
+
+Examples: `_GLFWwindowX11`, `_GLFWcontextWGL`
+
+These structs are incorporated as members into the internal interface structs
+using special macros that name them after the specific interface used.  This
+prevents shared code from accidentally using these members.
+
+Examples: `window.win32.handle`, `_glfw.x11.display`
+
+
+@section internals_event Event interface
+
+The event interface is implemented in the same shared source files as the public
+interface and is responsible for delivering the events it receives to the user,
+either via callbacks, via window state changes or both.
+
+The function names of the event interface use a `_glfwInput` prefix and the
+ObjectEvent pattern.
+
+Examples: @ref _glfwInputWindowFocus, @ref _glfwInputCursorMotion
+
+
+@section internals_static Static functions
+
+Static functions may be used by any interface and have no prefixes or suffixes.
+These use headless camel case.
+
+Examples: `clearScrollOffsets`
+
+
+@section internals_config Configuration macros
+
+GLFW uses a number of configuration macros to select at compile time which
+interfaces and code paths to use.  They are defined in the config.h header file,
+which is generated from the `config.h.in` file by CMake.
+
+Configuration macros the same style as tokens in the public interface, except
+with a leading underscore.
+
+Examples: `_GLFW_HAS_GLXGETPROCADDRESS` 
+
+*/