From 79945ab6fce4bf0b53faab1d2f694f4cd934d562 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Mon, 18 Jun 2012 12:50:18 +0200 Subject: [PATCH] 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 | 29 ++++++++++++++++++++++++++++ doc/mainpage.dox | 5 +++++ doc/namespaces.dox | 9 ++++++--- src/AbstractImage.h | 2 +- src/AbstractShaderProgram.h | 2 +- src/AbstractTexture.h | 2 +- src/Buffer.h | 2 +- src/BufferedImage.h | 6 ++++++ src/BufferedTexture.h | 2 +- src/Camera.h | 2 +- src/CubeMapTexture.h | 2 +- src/CubeMapTextureArray.h | 2 +- src/Framebuffer.h | 2 +- src/Image.h | 6 ++++++ src/IndexedMesh.h | 2 +- src/Light.h | 2 +- src/Math/MathTypeTraits.h | 2 +- src/Mesh.h | 2 +- src/MeshTools/Clean.h | 2 +- src/MeshTools/CombineIndexedArrays.h | 2 +- src/MeshTools/CompressIndices.h | 6 ++++++ src/MeshTools/FlipNormals.h | 6 ++++++ src/MeshTools/GenerateFlatNormals.h | 2 +- src/MeshTools/Interleave.h | 6 ++++++ src/MeshTools/Subdivide.h | 2 +- src/MeshTools/Tipsify.h | 2 +- src/Object.h | 2 +- src/Primitives/Capsule.h | 2 +- src/Primitives/Cube.h | 4 +++- src/Primitives/Icosphere.h | 4 ++-- src/Primitives/Plane.h | 2 +- src/Primitives/UVSphere.h | 4 +++- src/Query.h | 6 ++++++ src/Renderbuffer.h | 2 +- src/Scene.h | 4 +++- src/Shader.h | 2 +- src/Shaders/PhongShader.h | 2 +- src/SizeTraits.h | 6 ++++++ src/Texture.h | 6 ++++++ src/TypeTraits.h | 6 ++++++ 40 files changed, 129 insertions(+), 32 deletions(-) create mode 100644 doc/groups.dox diff --git a/doc/groups.dox b/doc/groups.dox new file mode 100644 index 000000000..22e833e4b --- /dev/null +++ b/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 +*/ +} diff --git a/doc/mainpage.dox b/doc/mainpage.dox index 823158654..b8356dd0f 100644 --- a/doc/mainpage.dox +++ b/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 diff --git a/doc/namespaces.dox b/doc/namespaces.dox index 4b3aebff6..1905ab375 100644 --- a/doc/namespaces.dox +++ b/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. diff --git a/src/AbstractImage.h b/src/AbstractImage.h index 151b79421..5e7239e09 100644 --- a/src/AbstractImage.h +++ b/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. diff --git a/src/AbstractShaderProgram.h b/src/AbstractShaderProgram.h index c248f6136..d34c5b7a5 100644 --- a/src/AbstractShaderProgram.h +++ b/src/AbstractShaderProgram.h @@ -27,7 +27,7 @@ namespace Magnum { -/** +/** @ingroup rendering @brief Base class for shaders @section AbstractShaderProgramSubclassing Subclassing workflow diff --git a/src/AbstractTexture.h b/src/AbstractTexture.h index d5a24292d..1942ee780 100644 --- a/src/AbstractTexture.h +++ b/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()", diff --git a/src/Buffer.h b/src/Buffer.h index ef621ac7c..d69fe6bef 100644 --- a/src/Buffer.h +++ b/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) diff --git a/src/BufferedImage.h b/src/BufferedImage.h index c7ada6f3f..1ecc8a5e4 100644 --- a/src/BufferedImage.h +++ b/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 diff --git a/src/BufferedTexture.h b/src/BufferedTexture.h index a1ea04f3e..5710e8399 100644 --- a/src/BufferedTexture.h +++ b/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, diff --git a/src/Camera.h b/src/Camera.h index 41ad8685d..5bb224782 100644 --- a/src/Camera.h +++ b/src/Camera.h @@ -28,7 +28,7 @@ namespace Magnum { -/** +/** @ingroup scene @brief %Camera object */ class MAGNUM_EXPORT Camera: public Object { diff --git a/src/CubeMapTexture.h b/src/CubeMapTexture.h index 8db13f20a..ddb455c14 100644 --- a/src/CubeMapTexture.h +++ b/src/CubeMapTexture.h @@ -23,7 +23,7 @@ namespace Magnum { -/** +/** @ingroup textures @brief Cube map texture %Texture used mainly for environemnt maps. See AbstractTexture documentation diff --git a/src/CubeMapTextureArray.h b/src/CubeMapTextureArray.h index e9f09de81..af6cdcb23 100644 --- a/src/CubeMapTextureArray.h +++ b/src/CubeMapTextureArray.h @@ -23,7 +23,7 @@ namespace Magnum { -/** +/** @ingroup textures @brief Cube map texture array For information about usage, see CubeMapTexture documentation. diff --git a/src/Framebuffer.h b/src/Framebuffer.h index 9a564efe4..2344742bb 100644 --- a/src/Framebuffer.h +++ b/src/Framebuffer.h @@ -26,7 +26,7 @@ namespace Magnum { -/** +/** @ingroup textures @brief %Framebuffer @requires_gl30 Extension @extension{EXT,framebuffer_object} diff --git a/src/Image.h b/src/Image.h index aaf697122..b80bff16b 100644 --- a/src/Image.h +++ b/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 diff --git a/src/IndexedMesh.h b/src/IndexedMesh.h index bac05586b..dad9582cf 100644 --- a/src/IndexedMesh.h +++ b/src/IndexedMesh.h @@ -24,7 +24,7 @@ namespace Magnum { -/** +/** @ingroup rendering mesh * @brief Indexed mesh */ class MAGNUM_EXPORT IndexedMesh: public Mesh { diff --git a/src/Light.h b/src/Light.h index ae1a71b60..1675753f4 100644 --- a/src/Light.h +++ b/src/Light.h @@ -23,7 +23,7 @@ namespace Magnum { -/** +/** @ingroup scene * @brief Basic light object * * Provides cached light position. diff --git a/src/Math/MathTypeTraits.h b/src/Math/MathTypeTraits.h index bc95deddd..88e60ae24 100644 --- a/src/Math/MathTypeTraits.h +++ b/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 diff --git a/src/Mesh.h b/src/Mesh.h index 6054b4200..345788748 100644 --- a/src/Mesh.h +++ b/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 diff --git a/src/MeshTools/Clean.h b/src/MeshTools/Clean.h index 750828003..643d17136 100644 --- a/src/MeshTools/Clean.h +++ b/src/MeshTools/Clean.h @@ -119,7 +119,7 @@ template 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, diff --git a/src/MeshTools/CombineIndexedArrays.h b/src/MeshTools/CombineIndexedArrays.h index 04fdce252..d8b1dc7b9 100644 --- a/src/MeshTools/CombineIndexedArrays.h +++ b/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 diff --git a/src/MeshTools/CompressIndices.h b/src/MeshTools/CompressIndices.h index fcb51ec45..3c2a90665 100644 --- a/src/MeshTools/CompressIndices.h +++ b/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 diff --git a/src/MeshTools/FlipNormals.h b/src/MeshTools/FlipNormals.h index 39ad881fa..77dd880e8 100644 --- a/src/MeshTools/FlipNormals.h +++ b/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& indices, std::vector flipNormals(normals); } +/*@}*/ + }} #endif \ No newline at end of file diff --git a/src/MeshTools/GenerateFlatNormals.h b/src/MeshTools/GenerateFlatNormals.h index 92be1db28..fec2d00fa 100644 --- a/src/MeshTools/GenerateFlatNormals.h +++ b/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 diff --git a/src/MeshTools/Interleave.h b/src/MeshTools/Interleave.h index a873a5403..18d8eec7b 100644 --- a/src/MeshTools/Interleave.h +++ b/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 inline void interleave(Mesh* mesh, Buffer* buffer, Buffer:: return Implementation::Interleave()(mesh, buffer, usage, attributes...); } +/*@}*/ + }} #endif diff --git a/src/MeshTools/Subdivide.h b/src/MeshTools/Subdivide.h index 638cce284..37e1f02e7 100644 --- a/src/MeshTools/Subdivide.h +++ b/src/MeshTools/Subdivide.h @@ -84,7 +84,7 @@ template class Subdivide { } #endif -/** +/** @ingroup mesh @brief %Subdivide the mesh @tparam Vertex Vertex data type @tparam Interpolator See `interpolator` function parameter diff --git a/src/MeshTools/Tipsify.h b/src/MeshTools/Tipsify.h index 1b0077cc9..ae7e935ba 100644 --- a/src/MeshTools/Tipsify.h +++ b/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 diff --git a/src/Object.h b/src/Object.h index 337d0525f..4c6494c0d 100644 --- a/src/Object.h +++ b/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 diff --git a/src/Primitives/Capsule.h b/src/Primitives/Capsule.h index f4a199339..84273e170 100644 --- a/src/Primitives/Capsule.h +++ b/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. diff --git a/src/Primitives/Cube.h b/src/Primitives/Cube.h index bacc1829c..0a7864b91 100644 --- a/src/Primitives/Cube.h +++ b/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 */ diff --git a/src/Primitives/Icosphere.h b/src/Primitives/Icosphere.h index 5cd011e03..7ce808846 100644 --- a/src/Primitives/Icosphere.h +++ b/src/Primitives/Icosphere.h @@ -27,7 +27,7 @@ namespace Magnum { namespace Primitives { template 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 */ diff --git a/src/Primitives/Plane.h b/src/Primitives/Plane.h index d21eee942..dffe9ce4e 100644 --- a/src/Primitives/Plane.h +++ b/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. diff --git a/src/Primitives/UVSphere.h b/src/Primitives/UVSphere.h index 4e6be3b63..6f50caee4 100644 --- a/src/Primitives/UVSphere.h +++ b/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: /** diff --git a/src/Query.h b/src/Query.h index 8823d712b..4d1289ea3 100644 --- a/src/Query.h +++ b/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 diff --git a/src/Renderbuffer.h b/src/Renderbuffer.h index 3fd9864a6..45112dbde 100644 --- a/src/Renderbuffer.h +++ b/src/Renderbuffer.h @@ -23,7 +23,7 @@ namespace Magnum { -/** +/** @ingroup textures @brief %Renderbuffer Attachable to Framebuffer as render target. diff --git a/src/Scene.h b/src/Scene.h index 2ed62cc42..744d81262 100644 --- a/src/Scene.h +++ b/src/Scene.h @@ -23,7 +23,9 @@ namespace Magnum { -/** @brief %Scene */ +/** @ingroup scene +@brief %Scene +*/ class MAGNUM_EXPORT Scene: public Object { public: /** @brief Constructor */ diff --git a/src/Shader.h b/src/Shader.h index 1aa51b8ca..5168a8260 100644 --- a/src/Shader.h +++ b/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 diff --git a/src/Shaders/PhongShader.h b/src/Shaders/PhongShader.h index dad97184e..b7c3f0f6d 100644 --- a/src/Shaders/PhongShader.h +++ b/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 diff --git a/src/SizeTraits.h b/src/SizeTraits.h index 5d03f3520..844a394df 100644 --- a/src/SizeTraits.h +++ b/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 struct Log { }; #endif +/*@}*/ + } #endif diff --git a/src/Texture.h b/src/Texture.h index ae36d15c0..af22d29fc 100644 --- a/src/Texture.h +++ b/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 diff --git a/src/TypeTraits.h b/src/TypeTraits.h index 906583f7e..2b2f6fe30 100644 --- a/src/TypeTraits.h +++ b/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 { typedef GLubyte Type; }; template<> struct TypeOf { typedef GLbyte Type; };