|
|
|
@ -39,9 +39,9 @@ needed. You are encouraged to read it first: |
|
|
|
|
|
|
|
|
|
|
|
- @ref corrade-coding-style |
|
|
|
- @ref corrade-coding-style |
|
|
|
|
|
|
|
|
|
|
|
@section cpp C++ code |
|
|
|
@section coding-style-cpp C++ code |
|
|
|
|
|
|
|
|
|
|
|
@subsection cpp-headers Headers |
|
|
|
@subsection coding-style-cpp-headers Headers |
|
|
|
|
|
|
|
|
|
|
|
Headers shouldn't have `using` declarations inside them (unless there is good |
|
|
|
Headers shouldn't have `using` declarations inside them (unless there is good |
|
|
|
excuse, see Magnum.h). |
|
|
|
excuse, see Magnum.h). |
|
|
|
@ -50,9 +50,9 @@ Headers have `*.h` extension, @ref compilation-speedup-hpp "template implementat |
|
|
|
have `*.hpp` extension (hinting that they are something between `*.h` and |
|
|
|
have `*.hpp` extension (hinting that they are something between `*.h` and |
|
|
|
`*.cpp` files). |
|
|
|
`*.cpp` files). |
|
|
|
|
|
|
|
|
|
|
|
@subsection cpp-format Code format |
|
|
|
@subsection coding-style-cpp-format Code format |
|
|
|
|
|
|
|
|
|
|
|
@subsubsection cpp-types Builtin types |
|
|
|
@subsubsection coding-style-cpp-types Builtin types |
|
|
|
|
|
|
|
|
|
|
|
Use %Magnum's own type aliases for public API (e.g. @ref UnsignedInt, see |
|
|
|
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 |
|
|
|
@ref types for more information), but use specific types when interacting with |
|
|
|
@ -61,13 +61,13 @@ conversions when converting between them. This helps avoiding sign, truncation |
|
|
|
and other issues, e.g. `%Math::%Vector2<GLsizei>` will implicitly convert to |
|
|
|
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`. |
|
|
|
@ref Vector2i if and only if @ref Int is the same type as `GLsizei`. |
|
|
|
|
|
|
|
|
|
|
|
@subsubsection cpp-naming Naming |
|
|
|
@subsubsection coding-style-cpp-naming Naming |
|
|
|
|
|
|
|
|
|
|
|
When writing wrappers for OpenGL functions and defines, try to match the |
|
|
|
When writing wrappers for OpenGL functions and defines, try to match the |
|
|
|
original name as closely as possible, although expanding abbrevations (and |
|
|
|
original name as closely as possible, although expanding abbrevations (and |
|
|
|
removing redundant prefixes) is encouraged. |
|
|
|
removing redundant prefixes) is encouraged. |
|
|
|
|
|
|
|
|
|
|
|
@subsubsection cpp-forward-declarations Forward declarations and forward declaration headers |
|
|
|
@subsubsection coding-style-cpp-forward-declarations Forward declarations and forward declaration headers |
|
|
|
|
|
|
|
|
|
|
|
When a namespace has classes which are commonly forward-declared, consider |
|
|
|
When a namespace has classes which are commonly forward-declared, consider |
|
|
|
making a forward declaration header - it should have the same name as the |
|
|
|
making a forward declaration header - it should have the same name as the |
|
|
|
@ -75,14 +75,14 @@ namespace itself and contain foward declarations for all classes, enums and |
|
|
|
copies of all meaningful typedefs. See @ref compilation-forward-declarations |
|
|
|
copies of all meaningful typedefs. See @ref compilation-forward-declarations |
|
|
|
for more information. |
|
|
|
for more information. |
|
|
|
|
|
|
|
|
|
|
|
@section compatibility Compatibility with various OpenGL editions |
|
|
|
@section coding-style-compatibility Compatibility with various OpenGL editions |
|
|
|
|
|
|
|
|
|
|
|
If any class, function or part of code depends on particular OpenGL edition |
|
|
|
If any class, function or part of code depends on particular OpenGL edition |
|
|
|
(e.g. only for desktop), use conditional compilation to avoid erors on other |
|
|
|
(e.g. only for desktop), use conditional compilation to avoid erors on other |
|
|
|
platforms (see @ref portability-target for more information). Put related |
|
|
|
platforms (see @ref portability-target for more information). Put related |
|
|
|
documentation also into the conditional compilation block and don't forget to |
|
|
|
documentation also into the conditional compilation block and don't forget to |
|
|
|
appropriately mark the class/function (@ref documentation-commands-requires "see below"). |
|
|
|
appropriately mark the class/function |
|
|
|
Example: |
|
|
|
(@ref coding-style-documentation-commands-requires "see below"). Example: |
|
|
|
@code |
|
|
|
@code |
|
|
|
#ifndef MAGNUM_TARGET_GLES |
|
|
|
#ifndef MAGNUM_TARGET_GLES |
|
|
|
// |
|
|
|
// |
|
|
|
@ -94,15 +94,15 @@ void setPolygonMode(PolygonMode mode); |
|
|
|
#endif |
|
|
|
#endif |
|
|
|
@endcode |
|
|
|
@endcode |
|
|
|
|
|
|
|
|
|
|
|
@section documentation Doxygen documentation |
|
|
|
@section coding-style-documentation Doxygen documentation |
|
|
|
|
|
|
|
|
|
|
|
@subsection documentation-commands Special documentation commands |
|
|
|
@subsection coding-style-documentation-commands Special documentation commands |
|
|
|
|
|
|
|
|
|
|
|
Additionally to @c \@todoc, @c \@debugoperator, @c \@debugoperatorenum, |
|
|
|
Additionally to @c \@todoc, @c \@debugoperator, @c \@debugoperatorenum, |
|
|
|
@c \@debugoperatorclassenum, @c \@configurationvalue and |
|
|
|
@c \@debugoperatorclassenum, @c \@configurationvalue and |
|
|
|
@c \@configurationvalueref (same as in %Corrade), these are defined: |
|
|
|
@c \@configurationvalueref (same as in %Corrade), these are defined: |
|
|
|
|
|
|
|
|
|
|
|
@subsubsection documentation-commands-collisionoperator Shape collision operators |
|
|
|
@subsubsection coding-style-documentation-commands-collisionoperator Shape collision operators |
|
|
|
|
|
|
|
|
|
|
|
Out-of-class operators for collision and collision occurence in Shapes |
|
|
|
Out-of-class operators for collision and collision occurence in Shapes |
|
|
|
namespace should be marked with @c \@collisionoperator and @c \@collisionoccurenceoperator, |
|
|
|
namespace should be marked with @c \@collisionoperator and @c \@collisionoccurenceoperator, |
|
|
|
@ -119,7 +119,7 @@ the operator is implemented (not of class in which the operator is |
|
|
|
implemented), thus efficiently connecting the two classes together in the |
|
|
|
implemented), thus efficiently connecting the two classes together in the |
|
|
|
documentation. |
|
|
|
documentation. |
|
|
|
|
|
|
|
|
|
|
|
@subsubsection documentation-commands-extension Links to OpenGL extensions |
|
|
|
@subsubsection coding-style-documentation-commands-extension Links to OpenGL extensions |
|
|
|
|
|
|
|
|
|
|
|
If an OpenGL extension is referenced in the documentation, it should be done |
|
|
|
If an OpenGL extension is referenced in the documentation, it should be done |
|
|
|
with @c \@extension command: |
|
|
|
with @c \@extension command: |
|
|
|
@ -138,7 +138,7 @@ specify extension filename, if the previous command gives 404 error. For example |
|
|
|
produces this link: |
|
|
|
produces this link: |
|
|
|
> @es_extension2{NV,read_buffer_front,GL_NV_read_buffer} |
|
|
|
> @es_extension2{NV,read_buffer_front,GL_NV_read_buffer} |
|
|
|
|
|
|
|
|
|
|
|
@subsubsection documentation-commands-ref_gl Links to related OpenGL functions and definitions |
|
|
|
@subsubsection coding-style-documentation-commands-ref_gl Links to related OpenGL functions and definitions |
|
|
|
|
|
|
|
|
|
|
|
If an function touches OpenGL, related OpenGL functions should be documented |
|
|
|
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 @c \@see block with @c \@fn_gl command. If only specific definition is used |
|
|
|
@ -162,7 +162,7 @@ are the same as in @c \@extension command. It produced link to extension |
|
|
|
specification, with function name as link text: |
|
|
|
specification, with function name as link text: |
|
|
|
> @fn_gl_extension{NamedCopyBufferSubData,EXT,direct_state_access}. |
|
|
|
> @fn_gl_extension{NamedCopyBufferSubData,EXT,direct_state_access}. |
|
|
|
|
|
|
|
|
|
|
|
@subsubsection documentation-commands-requires Classes and functions requiring specific OpenGL version or extensions |
|
|
|
@subsubsection coding-style-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 |
|
|
|
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 |
|
|
|
be marked with appropriate command @c \@requires_glXX, where `XX` is version |
|
|
|
@ -191,7 +191,7 @@ requirements. |
|
|
|
All classes and functions using those commands are cross-referenced in page |
|
|
|
All classes and functions using those commands are cross-referenced in page |
|
|
|
@ref opengl-required-extensions. |
|
|
|
@ref opengl-required-extensions. |
|
|
|
|
|
|
|
|
|
|
|
@section unit-tests Unit tests |
|
|
|
@section coding-style-unit-tests Unit tests |
|
|
|
|
|
|
|
|
|
|
|
All unit tests use Corrade's @ref Corrade::TestSuite "TestSuite". |
|
|
|
All unit tests use Corrade's @ref Corrade::TestSuite "TestSuite". |
|
|
|
|
|
|
|
|
|
|
|
|