Platform: document why tickEvent() isn't private.

I attempted to make it private only to discover it was used by Magnum
Player to make the workflow with opt-in tweakable constants more
efficient. So let's document that.

doc/snippets/Platform.cpp

@@ -26,6 +26,11 @@
 
 #define DOXYGEN_ELLIPSIS(...) __VA_ARGS__
 
+#include <Corrade/configure.h>
+#if defined(CORRADE_TARGET_UNIX) || (defined(CORRADE_TARGET_WINDOWS) && !defined(CORRADE_TARGET_WINDOWS_RT)) || defined(CORRADE_TARGET_EMSCRIPTEN)
+#include <Corrade/Utility/Tweakable.h>
+#endif
+
 /* [windowed] */
 #include <Magnum/GL/DefaultFramebuffer.h>
 #include <Magnum/GL/Renderer.h>
@@ -236,3 +241,28 @@ MyApplication::MyApplication(const Arguments& arguments):
 /* [exit-from-constructor] */
 
 }
+
+#if defined(CORRADE_TARGET_UNIX) || (defined(CORRADE_TARGET_WINDOWS) && !defined(CORRADE_TARGET_WINDOWS_RT)) || defined(CORRADE_TARGET_EMSCRIPTEN)
+namespace H {
+
+struct MyApplication: Platform::Application {
+    MyApplication(const Arguments& arguments);
+
+    void tickEvent() override;
+
+    Utility::Tweakable _tweakable;
+};
+
+/* [tickEvent-conditional] */
+void MyApplication::tickEvent() {
+    if(!_tweakable.isEnabled()) {
+        Platform::Application::tickEvent();
+        return;
+    }
+
+    _tweakable.update();
+}
+/* [tickEvent-conditional] */
+
+}
+#endif

src/Magnum/Platform/GlfwApplication.h

@@ -929,6 +929,23 @@ class GlfwApplication {
          * will effectively stop the tick event from being fired and the app
          * returns back to waiting for input events. This can be used to
          * disable the tick event when not needed.
+         *
+         * @m_class{m-block m-success}
+         *
+         * @par Opting out of tick events at runtime
+         *      Unlike other event handlers, this function isn't @cpp private @ce
+         *      in order to allow subclasses to conditionally disable the tick
+         *      event by calling the base implementation. To the application it
+         *      looks the same as if the tick event wasn't overriden at all,
+         *      which effectively results in the function not being called ever
+         *      again. This is useful for example with
+         *      @relativeref{Corrade,Utility::Tweakable}, where periodical
+         *      polling for file updates doesn't need to be done if tweakable
+         *      constants aren't enabled at all.
+         * @par
+         *      @snippet Platform.cpp tickEvent-conditional
+         * @par
+         *      It's not possible to re-enable the tick event afterwards.
          */
         virtual void tickEvent();
 

src/Magnum/Platform/Sdl2Application.h

@@ -1448,6 +1448,23 @@ class Sdl2Application {
          * will effectively stop the tick event from being fired and the app
          * returns back to waiting for input events. This can be used to
          * disable the tick event when not needed.
+         *
+         * @m_class{m-block m-success}
+         *
+         * @par Opting out of tick events at runtime
+         *      Unlike other event handlers, this function isn't @cpp private @ce
+         *      in order to allow subclasses to conditionally disable the tick
+         *      event by calling the base implementation. To the application it
+         *      looks the same as if the tick event wasn't overriden at all,
+         *      which effectively results in the function not being called ever
+         *      again. This is useful for example with
+         *      @relativeref{Corrade,Utility::Tweakable}, where periodical
+         *      polling for file updates doesn't need to be done if tweakable
+         *      constants aren't enabled at all.
+         * @par
+         *      @snippet Platform.cpp tickEvent-conditional
+         * @par
+         *      It's not possible to re-enable the tick event afterwards.
          */
         virtual void tickEvent();