From 1be81a15409ab5a485ce71cade96ff22e7e698fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Camilla=20L=C3=B6wy?= Date: Sun, 22 Oct 2017 16:27:17 +0200 Subject: [PATCH] Documentation work --- docs/build.dox | 14 +++++++------- docs/compile.dox | 8 ++++---- docs/context.dox | 2 +- docs/input.dox | 12 ++++++------ docs/intro.dox | 10 +++++----- docs/moving.dox | 2 +- docs/quick.dox | 12 +++++------- docs/window.dox | 10 +++++----- include/GLFW/glfw3.h | 14 ++++++-------- 9 files changed, 40 insertions(+), 44 deletions(-) diff --git a/docs/build.dox b/docs/build.dox index e428594e..18ce13ce 100644 --- a/docs/build.dox +++ b/docs/build.dox @@ -183,8 +183,8 @@ This section is about using CMake to compile and link GLFW along with your application. If you want to use an installed binary instead, see @ref build_link_cmake_package. -With just a few changes to your `CMakeLists.txt` you can have the GLFW source -tree built along with your application. +With a few changes to your `CMakeLists.txt` you can have the GLFW source tree +built along with your application. When including GLFW as part of your build, you probably don't want to build the GLFW tests, examples and documentation. To disable these, set the corresponding @@ -249,7 +249,7 @@ This section is about using CMake to link GLFW after it has been built and installed. If you want to build it along with your application instead, see @ref build_link_cmake_source. -With just a few changes to your `CMakeLists.txt`, you can locate the package and +With a few changes to your `CMakeLists.txt` you can locate the package and target files generated when GLFW is installed. @code{.cmake} @@ -312,8 +312,8 @@ GLFW library may look like this: cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --static --libs glfw3` @endcode -If you are using the shared version of the GLFW library, simply omit the -`--static` flag. +If you are using the shared version of the GLFW library, omit the `--static` +flag. @code{.sh} cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --libs glfw3` @@ -350,8 +350,8 @@ cc `pkg-config --cflags glfw3 glu` -o myprog myprog.c `pkg-config --static --lib @subsection build_link_xcode With Xcode on macOS -If you are using the dynamic library version of GLFW, simply add it to the -project dependencies. +If you are using the dynamic library version of GLFW, add it to the project +dependencies. If you are using the static library version of GLFW, add it and the Cocoa, OpenGL, IOKit and CoreVideo frameworks to the project as dependencies. They can diff --git a/docs/compile.dox b/docs/compile.dox index 35d65732..4486156e 100644 --- a/docs/compile.dox +++ b/docs/compile.dox @@ -13,7 +13,7 @@ build applications that use GLFW, see @ref build_guide. GLFW uses [CMake](http://www.cmake.org/) to generate project files or makefiles for a particular development environment. If you are on a Unix-like system such as Linux or FreeBSD or have a package system like Fink, MacPorts, Cygwin or -Homebrew, you can simply install its CMake package. If not, you can download +Homebrew, you can install its CMake package. If not, you can download installers for Windows and macOS from the [CMake website](http://www.cmake.org/). @@ -33,9 +33,9 @@ below. @subsubsection compile_deps_msvc Dependencies for Visual C++ on Windows -The Microsoft Platform SDK that is installed along with Visual C++ already -contains all the necessary headers, link libraries and tools except for CMake. -Move on to @ref compile_generate. +The Windows SDK bundled with Visual C++ already contains all the necessary +headers, link libraries and tools except for CMake. Move on to @ref +compile_generate. @subsubsection compile_deps_mingw Dependencies for MinGW or MinGW-w64 on Windows diff --git a/docs/context.dox b/docs/context.dox index 9aa72a5c..61292849 100644 --- a/docs/context.dox +++ b/docs/context.dox @@ -61,7 +61,7 @@ information. The name and number of this chapter unfortunately varies between versions and APIs, but has at times been named _Shared Objects and Multiple Contexts_. -GLFW comes with a simple object sharing test program called `sharing`. +GLFW comes with a barebones object sharing test program called `sharing`. @subsection context_offscreen Offscreen contexts diff --git a/docs/input.dox b/docs/input.dox index 0eaa8ef8..318d48d5 100644 --- a/docs/input.dox +++ b/docs/input.dox @@ -203,9 +203,9 @@ void character_callback(GLFWwindow* window, unsigned int codepoint) } @endcode -If you wish to receive even those Unicode code points generated with modifier -key combinations that a plain text field would ignore, or just want to know -exactly what modifier keys were used, set a character with modifiers callback. +If you also wish to receive those Unicode code points generated with modifier +key combinations that a plain text field would ignore, or want to know exactly +what modifier keys were used, set a character with modifiers callback. @code glfwSetCharModsCallback(window, charmods_callback); @@ -297,8 +297,8 @@ is provided normally via both the cursor position callback and through polling. other features of GLFW. It is not supported and will not work as robustly as `GLFW_CURSOR_DISABLED`. -If you just wish the cursor to become hidden when it is over a window, set -the cursor mode to `GLFW_CURSOR_HIDDEN`. +If you only wish the cursor to become hidden when it is over a window but still +want it to behave normally, set the cursor mode to `GLFW_CURSOR_HIDDEN`. @code glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_HIDDEN); @@ -501,7 +501,7 @@ void scroll_callback(GLFWwindow* window, double xoffset, double yoffset) } @endcode -A simple mouse wheel, being vertical, provides offsets along the Y-axis. +A normal mouse wheel, being vertical, provides offsets along the Y-axis. @section joystick Joystick input diff --git a/docs/intro.dox b/docs/intro.dox index 65aeef68..46a445aa 100644 --- a/docs/intro.dox +++ b/docs/intro.dox @@ -55,13 +55,13 @@ if (!glfwInit()) 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 +once and additional calls to an already initialized library will return `GLFW_TRUE` immediately. Once the library has been successfully initialized, it should be terminated 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. +allocated by programs that exit, but GLFW sometimes has to change global system +settings and these might not be restored without termination. @subsection init_hints Initialization hints @@ -79,8 +79,8 @@ during initialization. Once GLFW has been initialized, any values you set will be ignored until the library is terminated and initialized again. 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. +will only affect their specific platform. Other platforms will ignore them. +Setting these hints requires no platform specific headers or functions. @subsubsection init_hints_shared Shared init hints diff --git a/docs/moving.dox b/docs/moving.dox index af3da61c..0f33a7e5 100644 --- a/docs/moving.dox +++ b/docs/moving.dox @@ -221,7 +221,7 @@ GLFW 2, windows and contexts created with GLFW 3 will never be destroyed unless you choose them to be. Each window now has a close flag that is set to `GLFW_TRUE` when the user attempts to close that window. By default, nothing else happens and the window stays visible. It is then up to you to either destroy -the window, take some other action or simply ignore the request. +the window, take some other action or ignore the request. You can query the close flag at any time with @ref glfwWindowShouldClose and set it at any time with @ref glfwSetWindowShouldClose. diff --git a/docs/quick.dox b/docs/quick.dox index dc1a2f8d..ff2c6f06 100644 --- a/docs/quick.dox +++ b/docs/quick.dox @@ -69,7 +69,7 @@ if (!glfwInit()) } @endcode -Note that `GLFW_TRUE` and `GLFW_FALSE` are and will always be just one and zero. +Note that `GLFW_TRUE` and `GLFW_FALSE` are and will always be one and zero. When you are done using GLFW, typically just before the application exits, you need to terminate GLFW. @@ -86,14 +86,12 @@ functions that require it. @subsection quick_capture_error Setting an error callback Most events are reported through callbacks, whether it's a key being pressed, -a GLFW window being moved, or an error occurring. Callbacks are simply -C functions (or C++ static methods) that are called by GLFW with arguments -describing the event. +a GLFW window being moved, or an error occurring. Callbacks are C functions (or +C++ static methods) that are called by GLFW with arguments describing the event. In case a GLFW function fails, an error is reported to the GLFW error callback. You can receive these reports with an error callback. This function must have -the signature below. This simple error callback just prints the error -description to `stderr`. +the signature below but may do anything permitted in other callbacks. @code void error_callback(int error, const char* description) @@ -249,7 +247,7 @@ You can also set a framebuffer size callback using @ref glfwSetFramebufferSizeCallback and be notified when the size changes. Actual rendering with OpenGL is outside the scope of this tutorial, but there -are [many](https://open.gl/) [excellent](http://learnopengl.com/) +are [many](https://open.gl/) [excellent](https://learnopengl.com/) [tutorial](http://openglbook.com/) [sites](http://ogldev.atspace.co.uk/) that teach modern OpenGL. Some of them use GLFW to create the context and window while others use GLUT or SDL, but remember that OpenGL itself always works the diff --git a/docs/window.dox b/docs/window.dox index 39420804..85663e77 100644 --- a/docs/window.dox +++ b/docs/window.dox @@ -77,7 +77,7 @@ GLFWvidmode.blueBits | @ref GLFW_BLUE_BITS hint GLFWvidmode.refreshRate | @ref GLFW_REFRESH_RATE hint Once you have a full screen window, you can change its resolution, refresh rate -and monitor with @ref glfwSetWindowMonitor. If you just need change its +and monitor with @ref glfwSetWindowMonitor. If you only need change its resolution you can also call @ref glfwSetWindowSize. In all cases, the new video mode will be selected the same way as the video mode chosen by @ref glfwCreateWindow. If the window has an OpenGL or OpenGL ES context, it will be @@ -99,7 +99,7 @@ If the closest match for the desired video mode is the current one, the video mode will not be changed, making window creation faster and application switching much smoother. This is sometimes called _windowed full screen_ or _borderless full screen_ window and counts as a full screen window. To create -such a window, simply request the current video mode. +such a window, request the current video mode. @code const GLFWvidmode* mode = glfwGetVideoMode(monitor); @@ -151,8 +151,8 @@ and reset all at once to their defaults with @ref glfwDefaultWindowHints. Some hints are platform specific. These are always valid to 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 calls. +will ignore them. Setting these hints requires no platform specific headers or +calls. Note that hints need to be set _before_ the creation of the window and context you wish to have the specified attributes. @@ -694,7 +694,7 @@ glfwSetWindowAspectRatio(window, 16, 9); The aspect ratio is specified as a numerator and denominator, corresponding to the width and height, respectively. If you want a window to maintain its -current aspect ratio, simply use its current size as the ratio. +current aspect ratio, use its current size as the ratio. @code int width, height; diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h index 819d2cd6..8e6bc42c 100644 --- a/include/GLFW/glfw3.h +++ b/include/GLFW/glfw3.h @@ -274,14 +274,14 @@ extern "C" { /*! @brief One. * * One. Seriously. You don't _need_ to use this symbol in your code. It's - * just semantic sugar for the number 1. You can use `1` or `true` or `_True` + * semantic sugar for the number 1. You can also use `1` or `true` or `_True` * or `GL_TRUE` or whatever you want. */ #define GLFW_TRUE 1 /*! @brief Zero. * * Zero. Seriously. You don't _need_ to use this symbol in your code. It's - * just just semantic sugar for the number 0. You can use `0` or `false` or + * semantic sugar for the number 0. You can also use `0` or `false` or * `_False` or `GL_FALSE` or whatever you want. */ #define GLFW_FALSE 0 @@ -1629,9 +1629,8 @@ GLFWAPI void glfwTerminate(void); * again. * * 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. + * will only affect their specific platform. Other platforms will ignore them. + * Setting these hints requires no platform specific headers or functions. * * @param[in] hint The [init hint](@ref init_hints) to set. * @param[in] value The new value of the init hint. @@ -1664,9 +1663,8 @@ GLFWAPI void glfwInitHint(int hint, int value); * again. * * 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. + * will only affect their specific platform. Other platforms will ignore them. + * Setting these hints requires no platform specific headers or functions. * * @param[in] hint The [init hint](@ref init_hints) to set. * @param[in] value The new value of the init hint.