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).

Headers have `*.h` extension, @ref compilation-speedup-hpp "template implementation headers"
have `*.hpp` extension (hinting that they are something between `*.h` and
`*.cpp` files).

@subsection cpp-format Code format

@subsubsection cpp-types Builtin types

Use %Magnum's own type aliases for public API (e.g. @ref UnsignedInt, see
@ref types for more information), but use specific types when interacting with
third party libraries and OpenGL (e.g. `GLuint`) and rely only on implicit
conversions when converting between them. This helps avoiding sign, truncation
and other issues, e.g. `%Math::%Vector2<GLsizei>` will implicitly convert to
@ref Vector2i if and only if @ref Int is the same type as `GLsizei`.

@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.

@subsubsection cpp-forward-declarations Forward declarations and forward declaration headers

When a namespace has classes which are commonly forward-declared, consider
making a forward declaration header - it should have the same name as the
namespace itself and contain foward declarations for all classes, enums and
copies of all meaningful typedefs. See @ref compilation-forward-declarations
for more information.

@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}. Similarly for OpenGL ES extensions there is
@c \@es_extension command. Some extensions have slightly different URL,
with command @c \@es_extension2 you can specify extension filename, if the
previous command gives 404 error. The following produces link to
@es_extension2{NV,read_buffer_front,GL_NV_read_buffer} extension:
@code
@es_extension2{NV,read_buffer_front,GL_NV_read_buffer}
@endcode

@subsubsection documentation-commands-ref_gl Links to related OpenGL functions and definitions

If an function touches OpenGL, related OpenGL functions should be documented
in @c \@see block with @c \@fn_gl command. If only specific definition is used
in the function, document it with @c \@def_gl command. Example usage:
@code
// @see @fn_gl{Enable}/@fn_gl{Disable} with @def_gl{TEXTURE_CUBE_MAP_SEAMLESS}
inline static void setSeamless(bool enabled) {
    enabled ? glEnable(GL_TEXTURE_CUBE_MAP_SEAMLESS) : glDisable(GL_TEXTURE_CUBE_MAP_SEAMLESS);
}
@endcode

It produces link to the online manual, in this case @fn_gl{Enable}/@fn_gl{Disable}
with @def_gl{TEXTURE_CUBE_MAP_SEAMLESS}.

For functions which are not part of OpenGL core specification, but only as
extensions, use @c \@fn_gl_extension command, e.g.
@code
@fn_gl_extension{NamedCopyBufferSubData,EXT,direct_state_access}
@endcode
First parameter is function name without the suffix, the second two parameters
are the same as in @c \@extension command. It produced link to extension
specification, with function name as link text, in this case
@fn_gl_extension{NamedCopyBufferSubData,EXT,direct_state_access}.

@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.

Similarly for OpenGL ES there is command @c \@requires_gl for functionality
not available in OpenGL ES at all, @c \@requires_gles30 for functionality
requiring OpenGL ES 3.0 (i.e. not part of OpenGL 2.0) and
@c \@requires_es_extension for specific extensions not part of OpenGL ES
specification. When there is both required desktop OpenGL version/extension
and OpenGL ES version/extension, first come desktop requirements, then ES
requirements.

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

*/
}