From c98d09f15d3c41a8509a1cc2df44f3619e155d7f Mon Sep 17 00:00:00 2001 From: Camilla Berglund Date: Tue, 9 Aug 2016 01:34:56 +0200 Subject: [PATCH] Documentation work --- README.md | 15 +++++++++------ docs/intro.dox | 29 ++++++++++++++++------------- docs/vulkan.dox | 4 ++-- 3 files changed, 27 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index e6e863d8..b78b60f2 100644 --- a/README.md +++ b/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 diff --git a/docs/intro.dox b/docs/intro.dox index 2de6abe1..4ae189c2 100644 --- a/docs/intro.dox +++ b/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 diff --git a/docs/vulkan.dox b/docs/vulkan.dox index 988c2b84..a9cefd27 100644 --- a/docs/vulkan.dox +++ b/docs/vulkan.dox @@ -39,8 +39,8 @@ before including the GLFW header. #include @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