Doc++, code cleanup.

Some things from Coding Style were moved to Corrade.

doc/coding-style.dox

@@ -35,12 +35,11 @@ removing redundant prefixes) is encouraged.
 
 @subsubsection cpp-forward-declarations Forward declarations and forward declaration headers
 
-Use forward declarations in headers as much as possible, as it can
+When an namespace has classes which are commonly forward-declared, consider
-significantly reduce time of incremental compilation. When an namespace has
+making a forward declaration header - it should have the same name as the
-classes which are commonly forward-declared, consider making a forward
+namespace itself and contain foward declarations for all classes, enums and
-declaration header - it should have the same name as the namespace itself and
+copies of all meaningful typedefs. See @ref compilation-forward-declarations
-contain foward declarations for all classes, enums and copies of all
+for more information.
-meaningful typedefs. See SceneGraph/SceneGraph.h for an example.
 
 @section documentation Doxygen documentation
 

src/Timeline.h

@@ -27,26 +27,71 @@
 
 namespace Magnum {
 
-/** @brief %Timeline */
+/**
+@brief %Timeline
+
+Keeps track of time delta between frames and allows FPS limiting. Can be used
+as source for animation speed computations.
+
+@section Timeline-usage Basic usage
+
+Construct the timeline on initialization so the instance is available for
+whole lifetime of the application. Call start() before first draw event is
+performed, after everything is properly initialized.
+
+@note When timeline is started, it immediately starts measuring frame time.
+    Be prepared that time of first frame will be much longer than time of
+    following frames. It mainly depends on where you called start() in your
+    initialization routine, but can be also affected by driver- and
+    GPU-specific lazy texture binding, shader recompilations etc.
+
+In your draw event implementation don't forget to call nextFrame() after
+buffer swap. You can use previousFrameDuration() to compute animation speed.
+
+Example usage (in e.g. @ref Platform::GlutApplication "GlutApplication"
+subclass):
+@code
+MyApplication::MyApplication(...): Platform::GlutApplication(...) {
+    // Initialization ...
+
+    timeline.setMinimalFrameTime(1/120.0f); // 120 FPS at max
+    timeline.start();
+}
+
+void MyApplication::drawEvent() {
+    // Distance of object travelling at speed of 15 units per second
+    GLfloat distance = 15.0f*timeline.previousFrameDuration();
+
+    // Move object, draw ...
+
+    swapBuffers();
+    redraw();
+    timeline.nextFrame();
+}
+@endcode
+*/
 class MAGNUM_EXPORT Timeline {
     public:
         /**
          * @brief Constructor
          *
-         * Constructs stopped timeline.
+         * Creates stopped timeline.
          * @see start()
          */
         inline constexpr Timeline(): _minimalFrameTime(0), _previousFrameDuration(0), running(false) {}
 
         /** @brief Minimal frame time (in seconds) */
-        GLfloat minimalFrameTime() const { return _minimalFrameTime; }
+        inline constexpr GLfloat minimalFrameTime() const {
+            return _minimalFrameTime;
+        }
 
         /**
          * @brief Set minimal frame time
          *
+         * Default value is 0.
          * @see nextFrame()
          */
-        void setMinimalFrameTime(GLfloat seconds) {
+        inline void setMinimalFrameTime(GLfloat seconds) {
             _minimalFrameTime = seconds;
         }
 
@@ -60,6 +105,8 @@ class MAGNUM_EXPORT Timeline {
 
         /**
          * @brief Stop timeline
+         *
+         * @see start(), nextFrame()
          */
         void stop();
 
@@ -69,11 +116,11 @@ class MAGNUM_EXPORT Timeline {
          * If current frame time is smaller than minimal frame time, pauses
          * the execution for remaining time.
          * @note This function does nothing if the timeline is stopped.
-         * @see setMinimalFrameTime()
+         * @see setMinimalFrameTime(), stop()
          */
         void nextFrame();
 
-        /** @brief Duration of previous frame */
+        /** @brief Duration of previous frame (in seconds) */
         inline constexpr GLfloat previousFrameDuration() const {
             return _previousFrameDuration;
         }