mirror of https://github.com/mosra/magnum.git
Browse Source
* All pages are now named with lowercased letters with dashes between letters. * Added coding style guidelines. * Extended building documentation with guide how to download Magnum.vectorfields
Vladimír Vondruš
14 years ago
11 changed files with 487 additions and 75 deletions
@ -1,30 +0,0 @@
|
||||
/** @page RequiredExtensions Functionality requiring specific OpenGL version or extensions |
||||
|
||||
The engine is meant to be run on OpenGL 3 capable hardware, but most of the |
||||
functionality is working in OpenGL 2.1 hardware too (i.e. integrated Intel |
||||
GPUs), unless stated otherwise. Following are lists of functionality requiring |
||||
specific OpenGL version. In most cases it is also specified which extension is |
||||
required for given functionality, so if given hardware supports required |
||||
extension, it doesn't need to have required OpenGL version too (e.g. |
||||
`APPLE_vertex_array_object` is supported on Intel GPUs even if they are |
||||
capable of OpenGL 2.1 only). |
||||
|
||||
- @subpage RequiresGL30 |
||||
- @subpage RequiresGL31 |
||||
- @subpage RequiresGL32 |
||||
- @subpage RequiresGL33 |
||||
- @subpage RequiresGL40 |
||||
- @subpage RequiresGL41 |
||||
- @subpage RequiresGL42 |
||||
- @subpage RequiresExtension |
||||
|
||||
@page RequiresGL30 Functionality requiring OpenGL 3.0 |
||||
@page RequiresGL31 Functionality requiring OpenGL 3.1 |
||||
@page RequiresGL32 Functionality requiring OpenGL 3.2 |
||||
@page RequiresGL33 Functionality requiring OpenGL 3.3 |
||||
@page RequiresGL40 Functionality requiring OpenGL 4.0 |
||||
@page RequiresGL41 Functionality requiring OpenGL 4.1 |
||||
@page RequiresGL42 Functionality requiring OpenGL 4.2 |
||||
@page RequiresExtension Functionality requiring specific OpenGL extension |
||||
|
||||
*/ |
||||
@ -0,0 +1,380 @@
|
||||
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. |
||||
|
||||
@section cpp C++ code |
||||
|
||||
All C++ header and source files are named after the class they contain with no |
||||
case change. Thus there should be only one class per file, but if the classes |
||||
are closely related and small enough, you can make an exception (see Query.h |
||||
or TypeTraits.h for example). |
||||
|
||||
Code in the root Magnum namespace is in `src/` directory, each subnamespace is |
||||
in its own subdirectory. Unit tests are in `Test` subnamespace (and |
||||
subdirectory). Implementation details (helper classes etc.) which shouldn't be |
||||
visible to end users should be in `Implementation` subnamespace in the same |
||||
file as the class/function for which the implementation is. See @ref documentation |
||||
section below for guide how to hide it also from Doxygen documentation. |
||||
|
||||
@subsection cpp-headers Headers |
||||
|
||||
Headers have an strict structure. Include guards are basically include path |
||||
with slashes replaced with underscores to make refactoring as easy as possible. |
||||
Directly after them is license block, blank line, then file documentation, |
||||
blank line and after that the contents of the header. Include guard ending is |
||||
only `endif`, without any additional comments. |
||||
|
||||
It's probably common practice, but repeating won't hurt: headers shouldn't |
||||
have `using` declarations inside them (unless there is good excuse, see |
||||
Magnum.h). |
||||
|
||||
@subsection cpp-sources Source files |
||||
|
||||
Source file have similar structure as headers - first license block, then |
||||
blank line, then the includes, then contents of the file. |
||||
|
||||
Unlike headers, it's good to use `using` declaration in source files as much |
||||
as needed to make the code less verbose (unless the name is used only once). |
||||
|
||||
@subsection cpp-format Code format |
||||
|
||||
@subsubsection cpp-naming Naming |
||||
|
||||
Namespaces, classes and structs, enums, type template names and static |
||||
constants should be named with `CamelCase`, i.e. first letter of the name and |
||||
each successive word uppercase, other lowercase. E.g. `%CubeMapTextureArray`. |
||||
Classes with pure virtual methods or base classes which are not meant to be |
||||
used directly should be prefixed with `Abstract`. If the class is not meant |
||||
to be instanced directly and doesn't have any pure virtual methods, consider |
||||
using pure virtual destructor (see AbstractTexture source for example). |
||||
|
||||
Functions, function parameters, non-type template names and variables should |
||||
be named with `camelCase`, i.e. first letter of the name lowercase, each |
||||
successive word starting with uppercase. E.g. `generateFlatNormals()`. |
||||
|
||||
Preprocessor macros should be written in uppercase with underscores between |
||||
words, e.g. `MAGNUM_EXPORTING`. |
||||
|
||||
Redundant information and abbrevations in names are not recommended (use |
||||
`determinant`, `inverse` and `attribute` instead of `det`, `inv` and `attr`). |
||||
Hungarian notation, `I` and `E` prefixes for interfaces and enums are |
||||
forbidden and cruelly punished, if found. Acronyms should be written with |
||||
first letter uppercase only to avoid visual collision with preprocessor macros |
||||
(`Http`, `Collada` and `Bptc` instead of `HTTP`, `COLLADA` and `BPTC`). 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. |
||||
|
||||
Private variables clashing with (mostly getter) function names can have |
||||
one underscore before them, don't use two underscores, as they are reserved |
||||
for internal usage by the C++ standard. Underscores before the name shouldn't |
||||
be used in public API or function parameters, as it looks ugly in the |
||||
documentation. |
||||
|
||||
@subsubsection cpp-namespace Namespace declarations |
||||
|
||||
Namespace declaration is on one line, separated with blank lines on both |
||||
sides. The code inside the declaration is not indented to save horizontal |
||||
space. |
||||
@code |
||||
namespace Magnum { namespace Math { namespace Geometry { |
||||
|
||||
// ... |
||||
|
||||
}}} |
||||
@endcode |
||||
|
||||
The only exception is with forward declarations: use indentation where it |
||||
improves readability, e.g.: |
||||
@code |
||||
namespace Corrade { namespace PluginManager { |
||||
class AbstractPluginManager; |
||||
}} |
||||
|
||||
namespace Magnum { |
||||
|
||||
namespace Math { |
||||
class Matrix4; |
||||
|
||||
namespace Geometry { |
||||
class Distance; |
||||
} |
||||
} |
||||
|
||||
// the actual code... |
||||
|
||||
} |
||||
@endcode |
||||
|
||||
@subsubsection cpp-classes Class and structure declarations |
||||
|
||||
Class and structure protection levels are ordered as following: first friend |
||||
declarations, then public members, then protected members and finally private |
||||
members, so class public interface is easy to spot at the top of the file. |
||||
|
||||
Members are ordered as following: first classes and enums, then static |
||||
functions, then non-static functions, then static variables, then non-static |
||||
variables. Again, classes and methods are more important for user than |
||||
variables, static members are more important than non-static. |
||||
|
||||
@subsubsection cpp-style Blocks, whitespace and indentation |
||||
|
||||
The goal is to preserve readability with minimal amount of wasted vertical |
||||
and horizontal space. |
||||
|
||||
Each file must have one blank line at the end (Git will warn you in the |
||||
diff if it's not the case), indentation is done exclusively with spaces (4 |
||||
spaces). Trailing whitespaces are not permitted (and you should set up your |
||||
Git installation to warn about that). |
||||
|
||||
The code should be wrapped around 80th column, exceptions for long single-line |
||||
statements are allowed unless it hurts readability. |
||||
|
||||
Indented is everything except namespace declarations (as specified above) - |
||||
blocks, class protection levels, `case` statements. Overlong line breaks are |
||||
indented also with 4 spaces or better where it makes more sense (e.g. for |
||||
aligning similar code), multiline comments are indented with three spaces for |
||||
the comment text block to be aligned. |
||||
|
||||
Whitespace is **not allowed** inside parentheses and between function name or |
||||
branch/loop statement and left parenthesis (or between constructed variable |
||||
name and left brace) and before semicolon. It **must be** around block braces |
||||
if the block is not empty. It **must not** be space before, but after the |
||||
comma. |
||||
@code |
||||
if ( statement ){foo (a ,b) ;} // awful! |
||||
if(statement) { foo(a, b); } // good |
||||
@endcode |
||||
|
||||
Whitespace should be around operators with low precedence (namely `+`, `-`, |
||||
`<<`, `>>` but not on unary `-`), around all boolean and comparison operators, |
||||
around `=` and related operators and around ternary operator. Whitespace is |
||||
should be around `/`, `*`, `%` to indicate they have precedence before |
||||
addition and substraction. Whitespace can or need not to be around binary |
||||
operators, whichever looks better in particular content. |
||||
|
||||
Block opening braces start on the same line as corresponding statement (class/ |
||||
function declaration, branch and loop statement), `else` and `else if` |
||||
statements have both braces on the same line too: |
||||
@code |
||||
if(expression) { |
||||
// ... |
||||
} else if(another || expression) { |
||||
// ... |
||||
} else { |
||||
// ... |
||||
} |
||||
@endcode |
||||
|
||||
If the block is only one statement and short enough, it can be on the same line: |
||||
@code |
||||
void setClearDepth(GLfloat depth) { clearDepth = depth; } |
||||
@endcode |
||||
@code |
||||
if(!initialized) return false; |
||||
@endcode |
||||
|
||||
@subsubsection cpp-switches Switch statements |
||||
|
||||
Switch statements are usually very verbose and thus they are often subject of |
||||
various shortening and whitespace tricks. The goal is to make them as readable |
||||
as possible without wasting too much vertical space, for example: |
||||
@code |
||||
switch(type) { |
||||
case Byte: size = 8; break; |
||||
case Short: size = 16; break; |
||||
case Int: size = 32; break; |
||||
case Long: size = 64; break; |
||||
case LongLong: size = 128; break; |
||||
|
||||
default: size = 0; |
||||
} |
||||
@endcode |
||||
|
||||
@subsubsection cpp-virtual Virtual functions |
||||
|
||||
Only base virtual functions should have `virtual` keyword, not the |
||||
reimplementations. |
||||
|
||||
@subsubsection cpp-includes Includes |
||||
|
||||
Includes should be organized into separate groups separated with blank line - |
||||
first header belonging to the particular source file (if the file is source |
||||
file), then system includes, then includes from the engine itself and then |
||||
internal includes used only in the particular file (e.g. `configure.h`). |
||||
Includes from system libraries and dependencies are in angle brackets, |
||||
includes from engine itself are in quotes. Includes should be sorted by |
||||
"level" (e.g. C includes (`<cstdlib>`) before C++ includes |
||||
(`<string>`) and those before dependencies (`<GL/gl.h>`)), then by |
||||
path name. |
||||
|
||||
@subsubsection cpp-macros Preprocessor macros |
||||
|
||||
Preprocessor macros should have the same indentation as surrounding code. If |
||||
the macro is long or contains code which should be spanned or multiple lines, |
||||
it should be wrapped on multiple lines, each successive line indented and the |
||||
line wrapping indicator `\` should be aligned around 80th column, preferably |
||||
on some tab-stop. |
||||
|
||||
@section comments Comments |
||||
|
||||
All comments should be in C-style (i.e. slash and asterisk, not two slashes). |
||||
There should always be space after leading asterisk and before trailing |
||||
asterisk, this is also the case for C++-style comments, if are used somewhere |
||||
(mostly in the documentation, because nesting of C-style comments is |
||||
impossible). |
||||
|
||||
Multi-line comments should be done in a way which preserves block align (so |
||||
when first line starts with slash, asterisk and space, the second line should |
||||
be indented with three spaces to align the text). |
||||
|
||||
@section documentation Doxygen documentation |
||||
|
||||
Doxygen documentation uses C-style comments with two asterisks, each |
||||
successive line should start with asterisk and space. However, documentation |
||||
block starting at beginning of the line (with no indentation) and spanning |
||||
more lines shouldn't have leading asterisks and use whole 80 column width to |
||||
avoid wasted space. |
||||
|
||||
Doxygen commands are prefixed with `@`. |
||||
|
||||
If the documentation comment is short enough, it can be on one line. If not, |
||||
the first line should contain only the slash and two asterisks. However, there |
||||
are exceptions for commands that can be on the first line of the multiline |
||||
documentation block - namely @c \@page, @c \@name, @c \@file, @c \@namespace |
||||
and other commands for "out-of-place" documentation. |
||||
|
||||
Doxygen documentation is mainly in header files, additional documentation |
||||
pages which doesn't belong to any particular class (e.g. namespaces, |
||||
overview...) is in `doc/` directory. In source file should be only @c \@todo |
||||
items related to particular lines of code. Documentation pages and additional |
||||
documentation files should be named in lowercase with dashes between words. |
||||
Additional documentation files use `*.dox` extension. |
||||
|
||||
File documentation block is after license block, it explains only in |
||||
@c \@brief what content given header contains. |
||||
|
||||
Namespace documentation is only in file `namespaces.dox` inside `doc/` |
||||
directory. |
||||
|
||||
Class and function documentation block nearly always starts with an @c \@brief |
||||
description (the only exception is enum value documentation). After that is |
||||
documentation of template parameters, function parameters and return value. |
||||
These are documented only if it's not obvious from the description or |
||||
function/parameter name (i.e. it's not needed for setters). |
||||
|
||||
Trivial function overloads (e.g. const overloads) are marked only with |
||||
@c \@overload keyword and are always *after* the original documented function. |
||||
|
||||
If the documentation is short enough, it can be placed after the documented |
||||
element only if it doesn't exceed 80 character limit too much (e.g. enum value |
||||
documentation). |
||||
|
||||
For hiding implementation details from documentation or for working around |
||||
Doxygen parsing issues (and false positive warnings), preprocessor define |
||||
`DOXYGEN_GENERATING_OUTPUT` can be used. It is defined only when doxygen |
||||
generates the documentation. If that works around some Doxygen parsing bug, |
||||
don't forget to mark it with @c \@todoc (see below). |
||||
|
||||
@subsection documentation-commands Special documentation commands |
||||
|
||||
@subsubsection documentation-commands-todoc Documentation-related TODOs |
||||
|
||||
TODOs about documentation (or about Doxygen workarounds) should be written |
||||
with @c \@todoc instead of @c \@todo. They will appear on @ref todoc |
||||
"separate page". |
||||
|
||||
@subsubsection documentation-commands-debugoperator Debugging operators |
||||
|
||||
Operators for printing types on Corrade's debug output should be marked with |
||||
@c \@debugoperator, e.g.: |
||||
@code |
||||
// @debugoperator{Matrix4} |
||||
template<class T> Corrade::Utility::Debug operator<<(Corrade::Utility::Debug debug, const Matrix4<T>& value) { |
||||
// ... |
||||
} |
||||
@endcode |
||||
They will appear as related functions within documentation of class specified |
||||
as the parameter. |
||||
|
||||
@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. |
||||
|
||||
@section git Git commit messages, branch and tag format |
||||
|
||||
It is encouraged to follow best practices of git commit messages as explained |
||||
here: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html |
||||
|
||||
In short, each commit message should be in this format, each line at most 72 |
||||
characters long: |
||||
|
||||
~~~~ |
||||
Capitalized short summary |
||||
|
||||
More detailed explanation text, if necessary, wrapped on multiple lines. |
||||
|
||||
- Bullet points, indented with one space before (if there is preceeding |
||||
paragraph) and one space after the bullet, indented to have the text |
||||
aligned. Colons are allowed too, but not mixed. |
||||
- Bullet points are separated from surrounding text with blank lines. |
||||
|
||||
It is good to use *emphasise*, _underline_ or `code` as in Markdown, if |
||||
necessary, but they shouldn't be overused. |
||||
|
||||
Multi-line code examples are indented with four spaces, as in Markdown |
||||
syntax. |
||||
~~~~ |
||||
|
||||
Branches and tags should be named with lowercase names with words separated |
||||
with colons (`-`), e.g. `physics-performance-tweaks`. Version tags start with |
||||
`v`, followed by version number, e.g. `v1.0.3`. |
||||
*/ |
||||
} |
||||
@ -1,13 +1,6 @@
|
||||
namespace Magnum { namespace Physics { |
||||
/** @page CollisionDetection Collision detection system |
||||
|
||||
The collision detection system consists of a low-level part, consisting of |
||||
shape collection providing collision detection and high-level part, |
||||
consisting of rigid bodies and their groups. |
||||
|
||||
@subpage CollisionDetectionShapes |
||||
|
||||
@page CollisionDetectionShapes Shapes providing collision detection features |
||||
/** @page collision-detection Collision detection |
||||
@brief Collection of simple shapes for high performance collision detection. |
||||
|
||||
The essential thing in collision detection is to define a complex object with |
||||
collection of simple shapes, for which it is easy to detect collisions. These |
||||
@ -0,0 +1,7 @@
|
||||
namespace Magnum { namespace Physics { |
||||
/** @page physics Physics library |
||||
@brief Collision detection and rigid body dynamics. |
||||
|
||||
@subpage collision-detection |
||||
*/ |
||||
}} |
||||
@ -0,0 +1,31 @@
|
||||
/** @page required-extensions Functionality requiring specific OpenGL version or extensions |
||||
@brief Functions not available on OpenGL 2.1 hardware. |
||||
|
||||
The engine is meant to be run on OpenGL 3 capable hardware, but most of the |
||||
functionality is working in OpenGL 2.1 hardware too (i.e. integrated Intel |
||||
GPUs), unless stated otherwise. Following are lists of functionality requiring |
||||
specific OpenGL version. In most cases it is also specified which extension is |
||||
required for given functionality, so if given hardware supports required |
||||
extension, it doesn't need to have required OpenGL version too (e.g. |
||||
`APPLE_vertex_array_object` is supported on Intel GPUs even if they are |
||||
capable of OpenGL 2.1 only). |
||||
|
||||
- @subpage requires-gl30 |
||||
- @subpage requires-gl31 |
||||
- @subpage requires-gl32 |
||||
- @subpage requires-gl33 |
||||
- @subpage requires-gl40 |
||||
- @subpage requires-gl41 |
||||
- @subpage requires-gl42 |
||||
- @subpage requires-extension |
||||
|
||||
@page requires-gl30 Functionality requiring OpenGL 3.0 |
||||
@page requires-gl31 Functionality requiring OpenGL 3.1 |
||||
@page requires-gl32 Functionality requiring OpenGL 3.2 |
||||
@page requires-gl33 Functionality requiring OpenGL 3.3 |
||||
@page requires-gl40 Functionality requiring OpenGL 4.0 |
||||
@page requires-gl41 Functionality requiring OpenGL 4.1 |
||||
@page requires-gl42 Functionality requiring OpenGL 4.2 |
||||
@page requires-extension Functionality requiring specific OpenGL extension |
||||
|
||||
*/ |
||||
Loading…
Reference in new issue