Platform: suggest good practice when setting configuration flags.

src/Magnum/Platform/EmscriptenApplication.h

@@ -1006,8 +1006,10 @@ class EmscriptenApplication::GLConfiguration {
          * @brief Set context flags
          * @return Reference to self (for method chaining)
          *
-         * Default is @ref Flag::EnableExtensionsByDefault.
+         * Default is @ref Flag::EnableExtensionsByDefault. To avoid clearing
-         * @see @ref addFlags(), @ref clearFlags(), @ref GL::Context::flags()
+         * default flags by accident, prefer to use @ref addFlags() and
+         * @ref clearFlags() instead.
+         * @see @ref GL::Context::flags()
          */
         GLConfiguration& setFlags(Flags flags) {
             _flags = flags;

src/Magnum/Platform/GlfwApplication.h

@@ -834,8 +834,9 @@ class GlfwApplication::GLConfiguration {
          * @return Reference to self (for method chaining)
          *
          * Default is @ref Flag::ForwardCompatible on desktop GL and no flags
-         * on OpenGL ES.
+         * on OpenGL ES. To avoid clearing default flags by accident, prefer to
-         * @see @ref addFlags(), @ref clearFlags(), @ref GL::Context::flags()
+         * use @ref addFlags() and @ref clearFlags() instead.
+         * @see @ref GL::Context::flags()
          */
         GLConfiguration& setFlags(Flags flags) {
             _flags = flags;
@@ -1250,7 +1251,9 @@ class GlfwApplication::Configuration {
          * @brief Set window flags
          * @return  Reference to self (for method chaining)
          *
-         * Default is @ref WindowFlag::Focused.
+         * Default is @ref WindowFlag::Focused. To avoid clearing default flags
+         * by accident, prefer to use @ref addWindowFlags() and
+         * @ref clearWindowFlags() instead.
          */
         Configuration& setWindowFlags(WindowFlags windowFlags) {
             _windowFlags = windowFlags;

src/Magnum/Platform/Sdl2Application.h

@@ -1288,8 +1288,9 @@ class Sdl2Application::GLConfiguration {
          * @return Reference to self (for method chaining)
          *
          * Default is @ref Flag::ForwardCompatible on desktop GL and no flags
-         * on OpenGL ES.
+         * on OpenGL ES. To avoid clearing default flags by accident, prefer to
-         * @see @ref addFlags(), @ref clearFlags(), @ref GL::Context::flags()
+         * use @ref addFlags() and @ref clearFlags() instead.
+         * @see @ref GL::Context::flags()
          * @requires_gles Context flags are not available in WebGL.
          */
         GLConfiguration& setFlags(Flags flags) {
@@ -1823,7 +1824,9 @@ class Sdl2Application::Configuration {
          * @brief Set window flags
          * @return Reference to self (for method chaining)
          *
-         * Default are none.
+         * Default are none. To avoid clearing default flags by accident,
+         * prefer to use @ref addWindowFlags() and @ref clearWindowFlags()
+         * instead.
          */
         Configuration& setWindowFlags(WindowFlags flags) {
             _windowFlags = flags;

src/Magnum/Platform/WindowlessEglApplication.h

@@ -231,8 +231,9 @@ class WindowlessEglContext::Configuration {
          * @return Reference to self (for method chaining)
          *
          * Default is @ref Flag::ForwardCompatible on desktop GL and no flags
-         * on OpenGL ES.
+         * on OpenGL ES. To avoid clearing default flags by accident, prefer to
-         * @see @ref addFlags(), @ref clearFlags(), @ref GL::Context::flags()
+         * use @ref addFlags() and @ref clearFlags() instead.
+         * @see @ref GL::Context::flags()
          * @requires_gles Context flags are not available in WebGL.
          */
         Configuration& setFlags(Flags flags) {

src/Magnum/Platform/WindowlessGlxApplication.h

@@ -228,8 +228,9 @@ class WindowlessGlxContext::Configuration {
          * @return Reference to self (for method chaining)
          *
          * Default is @ref Flag::ForwardCompatible on desktop GL and no flags
-         * on OpenGL ES.
+         * on OpenGL ES. To avoid clearing default flags by accident, prefer to
-         * @see @ref addFlags(), @ref clearFlags(), @ref GL::Context::flags()
+         * use @ref addFlags() and @ref clearFlags() instead.
+         * @see @ref GL::Context::flags()
          */
         Configuration& setFlags(Flags flags) {
             _flags = flags;

src/Magnum/Platform/WindowlessWglApplication.h

@@ -215,8 +215,9 @@ class WindowlessWglContext::Configuration {
          * @return Reference to self (for method chaining)
          *
          * Default is @ref Flag::ForwardCompatible on desktop GL and no flags
-         * on OpenGL ES.
+         * on OpenGL ES. To avoid clearing default flags by accident, prefer to
-         * @see @ref addFlags(), @ref clearFlags(), @ref GL::Context::flags()
+         * use @ref addFlags() and @ref clearFlags() instead.
+         * @see @ref GL::Context::flags()
          */
         Configuration& setFlags(Flags flags) {
             _flags = flags;

src/Magnum/Platform/WindowlessWindowsEglApplication.h

@@ -190,7 +190,9 @@ class WindowlessWindowsEglContext::Configuration {
          * @brief Set context flags
          * @return Reference to self (for method chaining)
          *
-         * Default is no flag. See also @ref GL::Context::flags().
+         * Default is no flag. To avoid clearing default flags by accident,
+         * prefer to use @ref addFlags() and @ref clearFlags() instead.
+         * @see @ref GL::Context::flags()
          */
         Configuration& setFlags(Flags flags) {
             _flags = flags;