magnum/doc/coding-style.dox

namespace Magnum {
/** @page coding-style Coding style
@brief Coding style and best practices to preserve maintainability and
consistent style across whole project.

@tableofcontents

Please note that if you have a good excuse to either break the rules or modify
them, feel free to do it (and update this guide accordingly, if appropriate).
Nothing is worse than rule that hurts productivity instead of improving it.

This guide builds upon Corrade's coding style guide and extends it where
needed. You are encouraged to read it first:

 - @ref corrade-coding-style

@section cpp C++ code

@subsection cpp-headers Headers

Headers shouldn't have `using` declarations inside them (unless there is good
excuse, see Magnum.h).

@subsection cpp-format Code format

@subsubsection cpp-naming Naming

When writing wrappers for OpenGL functions and defines, try to match the
original name as closely as possible, although expanding abbrevations (and
removing redundant prefixes) is encouraged.

@section documentation Doxygen documentation

@subsection documentation-commands Special documentation commands

Additionally to @c \@todoc, @c \@debugoperator @c \@configurationvalue and
@c \@configurationvalueref (same as in Corrade), these are defined:

@subsubsection documentation-commands-collisionoperator Physics collision operators

Out-of-class operators for collision in Physics namespace should be marked with
@c \@collisionoperator, e.g.:
@code
// @collisionoperator{Point,Sphere}
inline bool operator%(const Point& a, const Sphere& b) { return b % a; }
@endcode
They will appear as related functions within documentation of class for which
the operator is implemented (not of class in which the operator is
implemented), thus efficiently connecting the two classes together in the
documentation.

@subsubsection documentation-commands-extension Links to OpenGL extensions

If an OpenGL extension is referenced in the documentation, it should be done
with @c \@extension command:
@code
@extension{ARB,timer_query}
@endcode
It produces link to the specification of the extension in OpenGL registry,
e.g. @extension{ARB,timer_query}.

@subsubsection documentation-commands-requires Classes and functions requiring specific OpenGL version or extensions

If any class or function requires specific OpenGL version above 2.1, it should
be marked with appropriate command @c \@requires_glXX, where `XX` is version
number (e.g. `42` for OpenGL 4.2) or @c \@requires_extension for specific
extension which is not in any core OpenGL version. It should be used in
conjunction with @c \@extension command, if there is an extension providing
the same functionality. For example:
@code
@requires_GL33 Extension @extension{ARB,timer_query}
@endcode

If class is marked with the command, member and related functions shouldn't be
marked. On the other hand, if the version/extension is needed only by one
function, only the function should be marked. If the extension is needed only
for some functionality (not related to any member function), it should be
noted in the description.

All classes and functions using those commands are cross-referenced in page
@ref required-extensions.

*/
}