Documentation: organizing the classes into "modules".

While namespaces act for hierarchy, modules are something like "tags" -
usable when you want to check related classes of e.g. CubeMapTexture.

Not sure how to name module for Math and Physics namespaces and
Contexts/Trade, though.

doc/groups.dox

@@ -0,0 +1,29 @@
+namespace Magnum {
+
+/** @page modules */
+
+/**
+@defgroup scene Scene graph
+@brief %Scene hierarchy, cameras, lights and other objects
+*/
+
+/**
+@defgroup mesh Meshes
+@brief Creating, modifying and rendering meshes
+*/
+
+/**
+@defgroup rendering Rendering
+@brief %Shader, buffer and mesh management, render queries
+*/
+
+/** @ingroup rendering
+@defgroup textures Textures
+@brief Access to OpenGL textures, image data wrappers and framebuffer operations
+*/
+
+/**
+@defgroup utility Utility
+@brief Various supporting utility classes
+*/
+}

doc/mainpage.dox

@@ -50,6 +50,11 @@ in step-by-step tutorial. Then you can dig deeper and try @ref example-index
 "other examples", read about fundamental principles in the documentation or
 start experimenting on your own!
 
+@subsection module-overview Module overview
+
+Classes in %Magnum are grouped into a few modules for a better orientation.
+Check the @ref modules "module index" for more information about all classes.
+
 @subsection getting-started-hacking Hacking Magnum
 
 If you want to hack on this engine, if you spotted a bug, need an feature or

doc/namespaces.dox

@@ -41,7 +41,8 @@ Functions for computing intersections, distances, areas and volumes.
 /** @dir MeshTools
  * @brief Namespace Magnum::MeshTools
  */
-/** @namespace Magnum::MeshTools
+/** @ingroup mesh
+@namespace Magnum::MeshTools
 @brief %Mesh tools
 
 Tools for generating, optimizing and cleaning meshes.
@@ -50,7 +51,8 @@ Tools for generating, optimizing and cleaning meshes.
 /** @dir Primitives
  * @brief Namespace Magnum::Primitives
  */
-/** @namespace Magnum::Primitives
+/** @ingroup mesh
+@namespace Magnum::Primitives
 @brief Primitive library
 
 Basic primitives for testing purposes.
@@ -59,7 +61,8 @@ Basic primitives for testing purposes.
 /** @dir Shaders
  * @brief Namespace Magnum::Shaders
  */
-/** @namespace Magnum::Shaders
+/** @ingroup rendering
+@namespace Magnum::Shaders
 @brief Sample shaders
 
 Collection of shaders for testing purposes.

src/AbstractImage.h

@@ -23,7 +23,7 @@
 
 namespace Magnum {
 
-/**
+/** @ingroup textures
 @brief Non-templated base for one-, two- or three-dimensional images
 
 See Image, BufferedImage, Trade::ImageData documentation for more information.

src/AbstractShaderProgram.h

@@ -27,7 +27,7 @@
 
 namespace Magnum {
 
-/**
+/** @ingroup rendering
 @brief Base class for shaders
 
 @section AbstractShaderProgramSubclassing Subclassing workflow

src/AbstractTexture.h

@@ -23,7 +23,7 @@
 
 namespace Magnum {
 
-/**
+/** @ingroup textures
 @brief Base for textures
 
 @attention Don't forget to call @ref Texture::setWrapping() "setWrapping()",

src/Buffer.h

@@ -23,7 +23,7 @@
 
 namespace Magnum {
 
-/**
+/** @ingroup rendering
 @brief Class for managing buffers
 
 @todo Support for buffer copying (OpenGL 3.1, ARB_copy_buffer)

src/BufferedImage.h

@@ -25,6 +25,10 @@
 
 namespace Magnum {
 
+/** @addtogroup textures
+ * @{
+ */
+
 /**
 @brief %Buffered image
 
@@ -110,6 +114,8 @@ typedef BufferedImage<2> BufferedImage2D;
 /** @brief Three-dimensional buffered image */
 typedef BufferedImage<3> BufferedImage3D;
 
+/*@}*/
+
 }
 
 #endif

src/BufferedTexture.h

@@ -24,7 +24,7 @@
 
 namespace Magnum {
 
-/**
+/** @ingroup textures
 @brief Buffered texture
 
 This texture is, unlike classic textures such as Texture or CubeMapTexture,

src/Camera.h

@@ -28,7 +28,7 @@
 
 namespace Magnum {
 
-/**
+/** @ingroup scene
 @brief %Camera object
  */
 class MAGNUM_EXPORT Camera: public Object {

src/CubeMapTexture.h

@@ -23,7 +23,7 @@
 
 namespace Magnum {
 
-/**
+/** @ingroup textures
 @brief Cube map texture
 
 %Texture used mainly for environemnt maps. See AbstractTexture documentation

src/CubeMapTextureArray.h

@@ -23,7 +23,7 @@
 
 namespace Magnum {
 
-/**
+/** @ingroup textures
 @brief Cube map texture array
 
 For information about usage, see CubeMapTexture documentation.

src/Framebuffer.h

@@ -26,7 +26,7 @@
 
 namespace Magnum {
 
-/**
+/** @ingroup textures
 @brief %Framebuffer
 
 @requires_gl30 Extension @extension{EXT,framebuffer_object}

src/Image.h

@@ -24,6 +24,10 @@
 
 namespace Magnum {
 
+/** @addtogroup textures
+ * @{
+ */
+
 /**
 @brief %Image
 
@@ -124,6 +128,8 @@ typedef Image<2> Image2D;
 /** @brief Three-dimensional image */
 typedef Image<3> Image3D;
 
+/*@}*/
+
 }
 
 #endif

src/IndexedMesh.h

@@ -24,7 +24,7 @@
 
 namespace Magnum {
 
-/**
+/** @ingroup rendering mesh
  * @brief Indexed mesh
  */
 class MAGNUM_EXPORT IndexedMesh: public Mesh {

src/Light.h

@@ -23,7 +23,7 @@
 
 namespace Magnum {
 
-/**
+/** @ingroup scene
  * @brief Basic light object
  *
  * Provides cached light position.

src/Math/MathTypeTraits.h

@@ -33,7 +33,7 @@
 
 namespace Magnum { namespace Math {
 
-/**
+/** @ingroup utility
 @brief Traits class for numeric types
 
 Traits classes are usable for detecting type features at compile time without

src/Mesh.h

@@ -30,7 +30,7 @@ namespace Magnum {
 
 class Buffer;
 
-/**
+/** @ingroup rendering mesh
 @brief Base class for managing non-indexed meshes
 
 @todo Support for normalized values (e.g. for color as char[4] passed to

src/MeshTools/Clean.h

@@ -119,7 +119,7 @@ template<class Vertex, size_t vertexSize = Vertex::Size> class Clean {
 }
 #endif
 
-/**
+/** @ingroup mesh
 @brief %Clean the mesh
 @tparam Vertex      Vertex data type
 @tparam vertexSize  How many initial vertex fields are important (for example,

src/MeshTools/CombineIndexedArrays.h

@@ -89,7 +89,7 @@ class CombineIndexedArrays {
 }
 #endif
 
-/**
+/** @ingroup mesh
 @brief Combine indexed arrays
 @param indexedArrays Index and attribute arrays
 @return Array with resulting indices

src/MeshTools/CompressIndices.h

@@ -73,6 +73,10 @@ class CompressIndices {
 }
 #endif
 
+/** @addtogroup mesh
+ * @{
+ */
+
 /**
 @brief Compress vertex indices
 @param indices  Index array
@@ -115,6 +119,8 @@ inline void compressIndices(IndexedMesh* mesh, Buffer::Usage usage, const std::v
     return Implementation::CompressIndices{indices}(mesh, usage);
 }
 
+/*@}*/
+
 }}
 
 #endif

src/MeshTools/FlipNormals.h

@@ -24,6 +24,10 @@
 
 namespace Magnum { namespace MeshTools {
 
+/** @addtogroup mesh
+ * @{
+ */
+
 /**
 @brief Flip face winding
 
@@ -57,6 +61,8 @@ inline void flipNormals(std::vector<unsigned int>& indices, std::vector<Vector3>
     flipNormals(normals);
 }
 
+/*@}*/
+
 }}
 
 #endif

src/MeshTools/GenerateFlatNormals.h

@@ -26,7 +26,7 @@
 
 namespace Magnum { namespace MeshTools {
 
-/**
+/** @ingroup mesh
 @brief Generate flat normals
 @param indices      Array of triangle face indexes
 @param vertices     Vertex array

src/MeshTools/Interleave.h

@@ -95,6 +95,10 @@ class Interleave {
 }
 #endif
 
+/** @addtogroup mesh
+ * @{
+ */
+
 /**
 @brief %Interleave vertex attributes
 @param attributes   Attribute arrays
@@ -144,6 +148,8 @@ template<class ...T> inline void interleave(Mesh* mesh, Buffer* buffer, Buffer::
     return Implementation::Interleave()(mesh, buffer, usage, attributes...);
 }
 
+/*@}*/
+
 }}
 
 #endif

src/MeshTools/Subdivide.h

@@ -84,7 +84,7 @@ template<class Vertex, class Interpolator> class Subdivide {
 }
 #endif
 
-/**
+/** @ingroup mesh
 @brief %Subdivide the mesh
 @tparam Vertex          Vertex data type
 @tparam Interpolator    See `interpolator` function parameter

src/MeshTools/Tipsify.h

@@ -51,7 +51,7 @@ class MESHTOOLS_EXPORT Tipsify {
 }
 #endif
 
-/**
+/** @ingroup mesh
 @brief %Tipsify the mesh
 @param indices      Indices array to operate on
 @param vertexCount  Vertex count

src/Object.h

@@ -38,7 +38,7 @@ class Camera;
   not needed)
 */
 
-/**
+/** @ingroup scene
  * @brief Base for all positioned objects
  *
  * @todo Transform transformation when changing parent, so the object stays in

src/Primitives/Capsule.h

@@ -23,7 +23,7 @@
 
 namespace Magnum { namespace Primitives {
 
-/**
+/** @ingroup mesh
 @brief %Capsule primitive
 
 Cylinder along Y axis with hemispheres instead of caps.

src/Primitives/Cube.h

@@ -23,7 +23,9 @@
 
 namespace Magnum { namespace Primitives {
 
-/** @brief %Cube primitive */
+/** @ingroup mesh
+@brief %Cube primitive
+*/
 class Cube: public Trade::MeshData {
     public:
         /** @brief Constructor */

src/Primitives/Icosphere.h

@@ -27,7 +27,7 @@ namespace Magnum { namespace Primitives {
 
 template<size_t subdivisions> class Icosphere;
 
-/**
+/** @ingroup mesh
 @brief %Icosphere primitive with zero subdivisions
 
 @todo Use own computed (and more precise) icosahedron data, not these stolen
@@ -39,7 +39,7 @@ template<> class Icosphere<0>: public Trade::MeshData {
         Icosphere();
 };
 
-/**
+/** @ingroup mesh
  * @brief %Icosphere primitive
  * @tparam subdivisions     Number of subdivisions
  */

src/Primitives/Plane.h

@@ -23,7 +23,7 @@
 
 namespace Magnum { namespace Primitives {
 
-/**
+/** @ingroup mesh
 @brief %Plane primitive
 
 2x2 plane with normals in positive Z direction.

src/Primitives/UVSphere.h

@@ -23,7 +23,9 @@
 
 namespace Magnum { namespace Primitives {
 
-/** @brief UV Sphere primitive */
+/** @ingroup mesh
+@brief UV Sphere primitive
+*/
 class UVSphere: public Capsule {
     public:
         /**

src/Query.h

@@ -23,6 +23,10 @@
 
 namespace Magnum {
 
+/** @addtogroup rendering
+ * @{
+ */
+
 /**
 @brief Base class for queries
 
@@ -279,6 +283,8 @@ class TimeQuery: public AbstractQuery {
         }
 };
 
+/*@}*/
+
 }
 
 #endif

src/Renderbuffer.h

@@ -23,7 +23,7 @@
 
 namespace Magnum {
 
-/**
+/** @ingroup textures
 @brief %Renderbuffer
 
 Attachable to Framebuffer as render target.

src/Scene.h

@@ -23,7 +23,9 @@
 
 namespace Magnum {
 
-/** @brief %Scene */
+/** @ingroup scene
+@brief %Scene
+*/
 class MAGNUM_EXPORT Scene: public Object {
     public:
         /** @brief Constructor */

src/Shader.h

@@ -26,7 +26,7 @@
 
 namespace Magnum {
 
-/**
+/** @ingroup rendering
  * @brief %Shader
  *
  * Allows loading and compiling the shader from file or directly from source

src/Shaders/PhongShader.h

@@ -24,7 +24,7 @@
 
 namespace Magnum { namespace Shaders {
 
-/**
+/** @ingroup rendering
 @brief Phong shader
 
 @requires_gl33 The shader is written in GLSL 3.3, although it should be trivial

src/SizeTraits.h

@@ -23,6 +23,10 @@
 
 namespace Magnum {
 
+/** @addtogroup utility
+ * @{
+ */
+
 /**
 @brief Traits class providing suitable types for given data sizes
 @tparam byte    Highest byte needed (counting from zero)
@@ -171,6 +175,8 @@ template<size_t base> struct Log<base, 0> {
 };
 #endif
 
+/*@}*/
+
 }
 
 #endif

src/Texture.h

@@ -23,6 +23,10 @@
 
 namespace Magnum {
 
+/** @addtogroup textures
+ * @{
+ */
+
 /**
 @brief %Texture
 
@@ -163,6 +167,8 @@ typedef Texture<2> Texture2D;
 /** @brief Three-dimensional texture */
 typedef Texture<3> Texture3D;
 
+/*@}*/
+
 }
 
 #endif

src/TypeTraits.h

@@ -23,6 +23,10 @@
 
 namespace Magnum {
 
+/** @addtogroup utility
+ * @{
+ */
+
 /**
 @brief Traits class for plain OpenGL types
 
@@ -136,6 +140,8 @@ struct MAGNUM_EXPORT TypeInfo {
 /** @todo Other texture types, referenced in glTexImage2D function manual */
 /** @todo Using Vector3 for textures? */
 
+/*@}*/
+
 #ifndef DOXYGEN_GENERATING_OUTPUT
 template<> struct TypeOf<Type::UnsignedByte> { typedef GLubyte Type; };
 template<> struct TypeOf<Type::Byte> { typedef GLbyte Type; };