Thorough documentation review and update.

Now whole Magnum, Magnum::SceneGraph and Magnum::Math namespaces are
fully documented -- each class has at least "getting started"
documentation, larger modules are documented on separate pages.

src/AbstractResourceLoader.h

@@ -82,6 +82,9 @@ MyResourceManager manager;
 MeshResourceLoader loader;
 
 manager->setLoader(loader);
+
+// This will now automatically request the mesh from loader by calling load()
+Resource<Mesh> myMesh = manager->get<Mesh>("my-mesh");
 @endcode
 */
 template<class T> class AbstractResourceLoader {

src/BufferedTexture.h

@@ -30,13 +30,35 @@ namespace Magnum {
 @brief Buffered texture
 
 This texture is, unlike classic textures such as Texture or CubeMapTexture,
-used as simple data source, without any unneccessary interpolation and
-wrapping methods. Texture data are stored in buffer and after binding the
-buffer to the texture using setBuffer(), you can fill the buffer at any time
-using data setting functions in Buffer itself.
+used as simple data source, without any unnecessary interpolation and
+wrapping methods.
 
-When using buffered texture in the shader, use `samplerBuffer` and fetch the
-data using integer coordinates in `texelFetch()`.
+@section BufferedTexture-usage Usage
+
+%Texture data are stored in buffer and after binding the buffer to the texture
+using setBuffer(), you can fill the buffer at any time using data setting
+functions in Buffer itself.
+
+Note that the buffer is not managed (e.g. deleted on destruction) by the
+texture, so you have to manage it on your own. On the other hand it allows you
+to use one buffer for more textures or store more than one data in it.
+
+Example usage:
+@code
+Buffer* buffer;
+BufferedTexture texture;
+texture.setBuffer(buffer);
+
+constexpr static Vector3 data[] = {
+    // ...
+};
+buffer.setData(data, Buffer::Usage::StaticDraw);
+@endcode
+
+The texture is bound to layer specified by shader via bind(). In shader, the
+texture is used via `samplerBuffer`.  Unlike in classic textures, coordinates
+for buffered textures are integer coordinates passed to `texelFetch()`. See
+also AbstractShaderProgram documentation for more information.
 
 @section BufferedTexture-performance-optimization Performance optimizations
 If extension @extension{EXT,direct_state_access} is available, setBuffer()

src/Context.h

@@ -123,7 +123,10 @@ class MAGNUM_EXPORT Extension {
 /**
 @brief OpenGL context
 
-Provides access to version and extension information.
+Provides access to version and extension information. Instance available
+through Context::current() is automatically created during construction of
+*Application classes in Platform namespace so you can safely assume that the
+instance is available during whole lifetime of *Application object.
 */
 class MAGNUM_EXPORT Context {
     Context(const Context&) = delete;

src/CubeMapTexture.h

@@ -57,7 +57,7 @@ texture.setMagnificationFilter(Texture2D::Filter::Linear)
 @endcode
 
 The texture is bound to layer specified by shader via bind(). In shader, the
-texture is used via `samplerCube`. Unlike classic textures, coordinates for
+texture is used via `samplerCube`. Unlike in classic textures, coordinates for
 cube map textures is signed three-part vector from the center of the cube,
 which intersects one of the six sides of the cube map. See also
 AbstractShaderProgram for more information.

src/CubeMapTextureArray.h

@@ -59,11 +59,11 @@ for(std::size_t i = 0; i != 16; ++i) {
 @endcode
 
 The texture is bound to layer specified by shader via bind(). In shader, the
-texture is used via `samplerCubeArray`. Unlike classic textures, coordinates
-for cube map texture arrays is signed four-part vector. First three parts
-define vector from the center of the cube which intersects with one of the six
-sides of the cube map, fourth part is layer in the array. See also
-AbstractShaderProgram for more information.
+texture is used via `samplerCubeArray`. Unlike in classic textures,
+coordinates for cube map texture arrays is signed four-part vector. First
+three parts define vector from the center of the cube which intersects with
+one of the six sides of the cube map, fourth part is layer in the array. See
+also AbstractShaderProgram for more information.
 
 @see CubeMapTexture::setSeamless()
 @requires_gl40 Extension @extension{ARB,texture_cube_map_array}

src/IndexedMesh.h

@@ -41,6 +41,20 @@ you have to manage it on your own. On the other hand it allows you to use
 one index buffer for more meshes (with different vertex data in each mesh, for
 example) or store more than only index data in one buffer.
 
+Example usage -- creating a cube mesh, assigning vertex buffer with
+interleaved vertex attributes and compressed index buffer for use with
+Shaders::PhongShader:
+@code
+Buffer *vertexBuffer, *indexBuffer;
+Mesh* mesh;
+
+Primitives::Cube cube;
+MeshTools::interleave(mesh, vertexBuffer, Buffer::Usage::StaticDraw, *cube.positions(0), *cube.normals(0));
+MeshTools::compressIndices(mesh, indexBuffer, Buffer::Usage::StaticDraw, *cube.indices());
+mesh->setPrimitive(plane.primitive())
+    ->addInterleavedVertexBuffer(vertexBuffer, 0, Shaders::PhongShader::Position(), Shaders::PhongShader::Normal());
+@endcode
+
 @section IndexedMesh-drawing Rendering meshes
 
 From user point-of-view the operation is the same as for
@@ -50,7 +64,8 @@ From user point-of-view the operation is the same as for
 
 If @extension{APPLE,vertex_array_object} is supported, next to
 @ref Mesh-performance-optimization "optimizations in Mesh itself" the index
-buffer is bound on object construction instead of in every draw() call.
+buffer is bound on object construction instead of binding it in every draw()
+call.
 */
 class MAGNUM_EXPORT IndexedMesh: public Mesh {
     friend class Context;

src/Math/Matrix3.h

@@ -30,7 +30,7 @@ namespace Magnum { namespace Math {
 
 Provides functions for transformations in 2D. See Matrix4 for 3D
 transformations. See also @ref matrix-vector for brief introduction.
-@see Magnum::Matrix3
+@see Magnum::Matrix3, SceneGraph::MatrixTransformation2D
 @configurationvalueref{Magnum::Math::Matrix3}
 */
 template<class T> class Matrix3: public Matrix<3, T> {

src/Math/Matrix4.h

@@ -30,7 +30,7 @@ namespace Magnum { namespace Math {
 
 Provides functions for transformations in 3D. See Matrix3 for 2D
 transformations. See also @ref matrix-vector for brief introduction.
-@see Magnum::Matrix4
+@see Magnum::Matrix4, SceneGraph::MatrixTransformation3D
 @configurationvalueref{Magnum::Math::Matrix4}
 @todo Shearing
 @todo Reflection

src/Mesh.h

@@ -61,7 +61,7 @@ static constexpr Point3D positions[30] = {
 };
 buffer->setData(positions, Buffer::Usage::StaticDraw);
 
-mesh->setPrimitve(Mesh::Primitive::Triangles)
+mesh->setPrimitive(Mesh::Primitive::Triangles)
     ->setVertexCount(30)
     ->addVertexBuffer(buffer, MyShader::Position());
 @endcode
@@ -95,7 +95,9 @@ mesh->addVertexBuffer(buffer, MyShader::Color(Type::UsignedByte, MyShader::Color
 
 @section Mesh-drawing Rendering meshes
 
-Basic workflow is to set up respective shader (see @ref AbstractShaderProgram-rendering-workflow "AbstractShaderProgram documentation" for more infromation) and call Mesh::draw().
+Basic workflow is to set up respective shader (see
+@ref AbstractShaderProgram-rendering-workflow "AbstractShaderProgram documentation"
+for more infromation) and call Mesh::draw().
 
 @section Mesh-performance-optimization Performance optimizations
 

src/Profiler.h

@@ -50,7 +50,7 @@ sections.bufferSwap = p.addSection("Buffer swap");
 p.enable();
 
 // Mark sections in draw function
-void MyContext::drawEvent() {
+void MyApplication::drawEvent() {
     p.start();
 
     // ... misc stuff belogning to "Other" section

src/Query.h

@@ -326,9 +326,9 @@ class MAGNUM_EXPORT SampleQuery: public AbstractQuery {
 @brief %Query for elapsed time
 
 Queries timestamp after all previous OpenGL calls have been processed. It is
-similar to Query::Target::TimeElapsed query, but this query just retrieves
-timestamp, not time duration between Query::begin() and Query::end() calls.
-Example usage, compared to Query::Target::TimeElapsed:
+similar to @ref Query::Target "Query::Target::TimeElapsed" query, but this
+query just retrieves timestamp, not time duration between Query::begin() and
+Query::end() calls. Example usage, compared to @ref Query::Target "Query::Target::TimeElapsed":
 @code
 Query q1, q2;
 q1.begin(Query::Target::TimeElapsed);

src/Resource.h

@@ -65,6 +65,7 @@ Debug MAGNUM_EXPORT operator<<(Debug debug, ResourceState value);
 /**
 @brief Key for accessing resource
 
+See ResourceManager for more information.
 @see ResourceManager::referenceCount(), ResourceManager::state(),
     ResourceManager::get(), ResourceManager::set(), Resource::key()
 */

src/SceneGraph/AbstractCamera.h

@@ -16,7 +16,7 @@
 */
 
 /** @file
- * @brief Class Magnum::SceneGraph::AbstractCamera, enum AspectRatioPolicy, alias Magnum::SceneGraph::AbstractCamera2D, Magnum::SceneGraph::AbstractCamera3D
+ * @brief Class Magnum::SceneGraph::AbstractCamera, enum Magnum::SceneGraph::AspectRatioPolicy, alias Magnum::SceneGraph::AbstractCamera2D, Magnum::SceneGraph::AbstractCamera3D
  */
 
 #include "Math/Matrix3.h"
@@ -62,7 +62,7 @@ file to avoid linker errors. See also relevant sections in
  - @ref AbstractCamera "AbstractCamera<2>"
  - @ref AbstractCamera "AbstractCamera<3>"
 
-@see Drawable, DrawableGroup, AbstractCamera2D, AbstractCamera3D
+@see @ref scenegraph, Drawable, DrawableGroup, AbstractCamera2D, AbstractCamera3D
 */
 #ifndef DOXYGEN_GENERATING_OUTPUT
 template<std::uint8_t dimensions, class T>

src/SceneGraph/AbstractGroupedFeature.h

@@ -44,8 +44,8 @@ class Drawable: public SceneGraph::AbstractGroupedFeature3D<Drawable> {
 typedef SceneGraph::FeatureGroup3D<Drawable> DrawableGroup;
 @endcode
 
-@see AbstractGroupedFeature2D, AbstractGroupedFeature3D, FeatureGroup,
-    FeatureGroup2D, FeatureGroup3D
+@see @ref scenegraph, AbstractGroupedFeature2D, AbstractGroupedFeature3D,
+    FeatureGroup, FeatureGroup2D, FeatureGroup3D
 */
 #ifndef DOXYGEN_GENERATING_OUTPUT
 template<std::uint8_t dimensions, class Derived, class T>
@@ -62,7 +62,7 @@ class AbstractGroupedFeature: public AbstractFeature<dimensions, T> {
          * @param group     Group this feature belongs to
          *
          * Adds the feature to the object and to group, if specified.
-         * @see FeatureGroup::add(), FeatureGroup::remove()
+         * @see FeatureGroup::add()
          */
         inline AbstractGroupedFeature(AbstractObject<dimensions, T>* object, FeatureGroup<dimensions, Derived, T>* group = nullptr): AbstractFeature<dimensions, T>(object), _group(nullptr) {
             if(group) group->add(static_cast<Derived*>(this));

src/SceneGraph/AbstractTransformation.h

@@ -34,12 +34,12 @@ for introduction.
 
 @section AbstractTransformation-subclassing Subclassing
 
-When sublassing, you have to:
+When subclassing, you have to:
 
-- Implement all members described in **Subclass implementation** group above
+- Implement all members listed in **Subclass implementation** group above
 - Provide implicit (parameterless) constructor
 
-@see AbstractTransformation2D, AbstractTransformation3D
+@see @ref scenegraph, AbstractTransformation2D, AbstractTransformation3D
 */
 #ifndef DOXYGEN_GENERATING_OUTPUT
 template<std::uint8_t dimensions, class T>

src/SceneGraph/AbstractTranslationRotation2D.h

@@ -26,7 +26,7 @@ namespace Magnum { namespace SceneGraph {
 /**
 @brief Base for two-dimensional transformations supporting translation and rotation
 
-@see AbstractTranslationRotation3D
+@see @ref scenegraph, AbstractTranslationRotation3D
 */
 #ifndef DOXYGEN_GENERATING_OUTPUT
 template<class T>

src/SceneGraph/AbstractTranslationRotation3D.h

@@ -27,7 +27,7 @@ namespace Magnum { namespace SceneGraph {
 /**
 @brief Base for three-dimensional transformations supporting translation and rotation
 
-@see AbstractTranslationRotation2D
+@see @ref scenegraph, AbstractTranslationRotation2D
 */
 #ifndef DOXYGEN_GENERATING_OUTPUT
 template<class T>

src/SceneGraph/AbstractTranslationRotationScaling2D.h

@@ -26,7 +26,7 @@ namespace Magnum { namespace SceneGraph {
 /**
 @brief Base for two-dimensional transformations supporting translation, rotation and scaling
 
-@see AbstractTranslationRotationScaling2D
+@see @ref scenegraph, AbstractTranslationRotationScaling2D
 */
 #ifndef DOXYGEN_GENERATING_OUTPUT
 template<class T>

src/SceneGraph/AbstractTranslationRotationScaling3D.h

@@ -26,7 +26,7 @@ namespace Magnum { namespace SceneGraph {
 /**
 @brief Base for three-dimensional transformations supporting translation, rotation and scaling
 
-@see AbstractTranslationRotationScaling2D
+@see @ref scenegraph, AbstractTranslationRotationScaling2D
 */
 #ifndef DOXYGEN_GENERATING_OUTPUT
 template<class T>

src/SceneGraph/Camera2D.h

@@ -26,7 +26,14 @@ namespace Magnum { namespace SceneGraph {
 /**
 @brief Camera for two-dimensional scenes
 
-See Drawable documentation for more information.
+See Drawable documentation for introduction. The camera by default displays
+OpenGL unit cube `[(-1, -1, -1); (1, 1, 1)]` and doesn't do any aspect ratio
+correction. Common setup example:
+@code
+SceneGraph::Camera2D<>* camera = new SceneGraph::Camera2D<>(&cameraObject);
+camera->setProjection({4.0f/3.0f, 1.0f})
+      ->setAspectRatioPolicy(SceneGraph::AspectRatioPolicy::Extend);
+@endcode
 
 @section Camera2D-explicit-specializations Explicit template specializations
 
@@ -36,7 +43,7 @@ avoid linker errors. See @ref compilation-speedup-hpp for more information.
 
  - @ref Camera2D "Camera2D<GLfloat>"
 
-@see Camera3D, Drawable, DrawableGroup
+@see @ref scenegraph, Camera3D, Drawable, DrawableGroup
 */
 #ifndef DOXYGEN_GENERATING_OUTPUT
 template<class T>

src/SceneGraph/Camera3D.h

@@ -31,7 +31,14 @@ namespace Magnum { namespace SceneGraph {
 /**
 @brief Camera for three-dimensional scenes
 
-See Drawable documentation for more information.
+See Drawable documentation for introduction. The camera by default displays
+OpenGL unit cube `[(-1, -1, -1); (1, 1, 1)]` with orthographic projection and
+doesn't do any aspect ratio correction. Common setup example:
+@code
+SceneGraph::Camera3D<>* camera = new SceneGraph::Camera3D<>(&cameraObject);
+camera->setPerspective(deg(35.0f), 0.001f, 100.0f)
+      ->setAspectRatioPolicy(SceneGraph::AspectRatioPolicy::Extend);
+@endcode
 
 @section Camera3D-explicit-specializations Explicit template specializations
 
@@ -41,7 +48,7 @@ avoid linker errors. See @ref compilation-speedup-hpp for more information.
 
  - @ref Camera3D "Camera3D<GLfloat>"
 
-@see Camera2D, Drawable, DrawableGroup
+@see @ref scenegraph, Camera2D, Drawable, DrawableGroup
 */
 #ifndef DOXYGEN_GENERATING_OUTPUT
 template<class T>
@@ -54,7 +61,8 @@ class MAGNUM_SCENEGRAPH_EXPORT Camera3D: public AbstractCamera<3, T> {
          * @brief Constructor
          * @param object    %Object holding this feature
          *
-         * Sets orthographic projection to the default OpenGL cube (range @f$ [-1; 1] @f$ in all directions).
+         * Sets orthographic projection to the default OpenGL cube
+         * (range @f$ [-1; 1] @f$ in all directions).
          * @see setOrthographic(), setPerspective()
          */
         inline Camera3D(AbstractObject<3, T>* object): AbstractCamera<3, T>(object), _near(0.0f), _far(0.0f) {}

src/SceneGraph/Drawable.h

@@ -26,7 +26,7 @@ namespace Magnum { namespace SceneGraph {
 /**
 @brief %Drawable
 
-Adds drawing function to object. Each %Drawable is part of some DrawableGroup
+Adds drawing feature to object. Each %Drawable is part of some DrawableGroup
 and the whole group is drawn with particular camera using AbstractCamera::draw().
 
 @section Drawable-usage Usage
@@ -52,30 +52,34 @@ class DrawableObject: public Object3D, SceneGraph::Drawable3D<> {
 
 Then you add these objects to your scene and some drawable group and transform
 them as you like. You can also use DrawableGroup::add() and
-DrawableGroup::remove() for that.
+DrawableGroup::remove().
 @code
 Scene3D scene;
-SceneGraph::DrawableGroup3D<> group;
+SceneGraph::DrawableGroup3D<> drawables;
 
-(new DrawableObject(&scene, &group))
+(new DrawableObject(&scene, &drawables))
     ->translate(Vector3::yAxis(-0.3f))
     ->rotateX(deg(30.0f));
-(new AnotherDrawableObject(&scene, &group))
+(new AnotherDrawableObject(&scene, &drawables))
     ->translate(Vector3::zAxis(0.5f));
 // ...
 @endcode
 
 The last thing you need is Camera attached to some object (thus using its
-transformation) and with it you can perform drawing in your draw event:
+transformation) and with it you can perform drawing in your draw event
+implementation. See Camera2D and Camera3D documentation for more information.
 @code
 Camera3D<> camera(&cameraObject);
 
 void MyApplication::drawEvent() {
-    camera.draw(&group);
+    camera.draw(drawables);
+
+    swapBuffers();
+    // ...
 }
 @endcode
 
-@see Drawable2D, Drawable3D, DrawableGroup2D, DrawableGroup3D
+@see @ref scenegraph, Drawable2D, Drawable3D, DrawableGroup2D, DrawableGroup3D
 */
 #ifndef DOXYGEN_GENERATING_OUTPUT
 template<std::uint8_t dimensions, class T>
@@ -136,7 +140,7 @@ typedef Drawable<3, T = GLfloat> Drawable3D;
 @brief Group of drawables
 
 See Drawable for more information.
-@see DrawableGroup2D, DrawableGroup3D
+@see @ref scenegraph, DrawableGroup2D, DrawableGroup3D
 @todoc Remove workaround when Doxygen supports alias template
 */
 #if !defined(CORRADE_GCC46_COMPATIBILITY) && !defined(DOXYGEN_GENERATING_OUTPUT)

src/SceneGraph/FeatureGroup.h

@@ -31,7 +31,7 @@ namespace Magnum { namespace SceneGraph {
 @brief Group of features
 
 See AbstractGroupedFeature for more information.
-@see FeatureGroup2D, FeatureGroup3D
+@see @ref scenegraph, FeatureGroup2D, FeatureGroup3D
 */
 #ifndef DOXYGEN_GENERATING_OUTPUT
 template<std::uint8_t dimensions, class Feature, class T>

src/SceneGraph/MatrixTransformation2D.h

@@ -28,7 +28,8 @@ namespace Magnum { namespace SceneGraph {
 /**
 @brief Two-dimensional transformation implemented using matrices
 
-@see MatrixTransformation3D
+Uses Math::Matrix3 as underlying type.
+@see @ref scenegraph, MatrixTransformation3D
 */
 #ifndef DOXYGEN_GENERATING_OUTPUT
 template<class T>

src/SceneGraph/MatrixTransformation3D.h

@@ -28,7 +28,8 @@ namespace Magnum { namespace SceneGraph {
 /**
 @brief Three-dimensional transformation implemented using matrices
 
-@see MatrixTransformation2D
+Uses Math::Matrix4 as underlying type.
+@see @ref scenegraph, MatrixTransformation2D
 */
 #ifndef DOXYGEN_GENERATING_OUTPUT
 template<class T>

src/Shader.h

@@ -30,11 +30,10 @@
 namespace Magnum {
 
 /**
- * @brief %Shader
- *
- * Allows loading and compiling the shader from file or directly from source
- * string. Compiled shaders are then passed to AbstractShaderProgram subclasses
- * for linking and usage.
+@brief %Shader
+
+Allows loading and compiling the shader from file or directly from source
+string. See AbstractShaderProgram for more information.
  */
 class MAGNUM_EXPORT Shader {
     Shader(const Shader& other) = delete;

src/Texture.h

@@ -63,6 +63,9 @@ information.
 
 @section Texture-array Texture arrays
 
+You can create texture arrays by passing @ref Texture::Target "Texture2D::Target::Texture1DArray"
+or @ref Texture::Target "Texture3D::Target::Texture2DArray" to constructor.
+
 It is possible to specify each layer separately using setSubData(), but you
 have to allocate the memory for all layers first, possibly by passing properly
 sized empty Image to setData(). Example: 2D texture array with 16 layers of
@@ -90,13 +93,13 @@ etc.).
 
 @section Texture-rectangle Rectangle textures
 
-If you want to use rectangle textures, set target in constructor to
-`Target::Rectangle` and in shader use `sampler2DRect`. Unlike `sampler2D`,
-which accepts coordinates between 0 and 1, `sampler2DRect` accepts coordinates
-between 0 and `textureSizeInGivenDirection-1`. Note that rectangle textures
-don't support mipmapping and repeating wrapping modes, see @ref Texture::Filter
-"Filter", @ref Texture::Mipmap "Mipmap" and generateMipmap() documentation
-for more information.
+Rectangle texture is created by passing @ref Texture::Target "Texture::Target::Rectangle"
+to constructor. In shader, the texture is used via sampler2DRect`. Unlike
+`sampler2D`, which accepts coordinates between 0 and 1, `sampler2DRect`
+accepts coordinates between 0 and `textureSizeInGivenDirection-1`. Note that
+rectangle textures don't support mipmapping and repeating wrapping modes, see
+@ref Texture::Filter "Filter", @ref Texture::Mipmap "Mipmap" and
+generateMipmap() documentation for more information.
 
 @requires_gl Rectangle textures are not available in OpenGL ES.
 @requires_gl31 Extension @extension{ARB,texture_rectangle} (rectangle textures)