doc: updated Coding Style.

* Using external snippets to be able to show the /* */ comments.
 * Adapted to the new theme.
 * Mentioning special OpenAL Doxygen commands.

Doxyfile

@@ -867,7 +867,7 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                =
+EXCLUDE                = doc/snippets/
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded

doc/coding-style.dox

@@ -34,17 +34,15 @@ 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
+This guide builds upon @ref corrade-coding-style "Corrade's coding style guide"
-needed. You are encouraged to read it first:
+and extends it where needed. You are encouraged to read it first.
-
- - @ref corrade-coding-style
 
 @section coding-style-cpp C++ code
 
 @subsection coding-style-cpp-headers Headers
 
-Headers shouldn't have `using` declarations inside them (unless there is good
+Headers shouldn't have @cpp using @ce declarations inside them (unless there is
-excuse, see Magnum.h).
+good excuse, see @ref Magnum.h).
 
 Headers have `*.h` extension, @ref compilation-speedup-hpp "template implementation headers"
 have `*.hpp` extension (hinting that they are something between `*.h` and
@@ -56,10 +54,11 @@ have `*.hpp` extension (hinting that they are something between `*.h` and
 
 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
+third party libraries and OpenGL (e.g. @cpp GLuint @ce) and rely only on
-conversions when converting between them. This helps avoiding sign, truncation
+implicit conversions when converting between them. This helps avoiding sign,
-and other issues, e.g. `Math::Vector2<GLsizei>` will implicitly convert to
+truncation and other issues, e.g. @cpp Math::Vector2<GLsizei> @ce will
-@ref Vector2i if and only if @ref Int is the same type as `GLsizei`.
+implicitly convert to @ref Vector2i if and only if @ref Int is the same type as
+@cpp GLsizei @ce.
 
 @subsubsection coding-style-cpp-naming Naming
 
@@ -70,7 +69,7 @@ removing redundant prefixes) is encouraged.
 @subsubsection coding-style-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
+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.
@@ -83,16 +82,8 @@ platforms (see @ref portability-target for more information). Put related
 documentation also into the conditional compilation block and don't forget to
 appropriately mark the class/function
 (@ref coding-style-documentation-commands-requires "see below"). Example:
-@code
+
-#ifndef MAGNUM_TARGET_GLES
+@snippet coding-style.h glcompatibility
-//
-// @brief Set polygon mode
-//
-// @requires_gl Polygon mode is not available in OpenGL ES.
-//
-void setPolygonMode(PolygonMode mode);
-#endif
-@endcode
 
 @section coding-style-documentation Doxygen documentation
 
@@ -100,68 +91,96 @@ void setPolygonMode(PolygonMode mode);
 
 Additionally to @c \@todoc, @c \@debugoperator, @c \@debugoperatorenum,
 @c \@debugoperatorclassenum, @c \@configurationvalue and
-@c \@configurationvalueref (same as in Corrade), these are defined:
+@c \@configurationvalueref defined @ref corrade-coding-style-documentation-commands "the same as in Corrade",
+these are defined:
 
 @subsubsection coding-style-documentation-commands-collisionoperator Shape collision operators
 
 Out-of-class operators for collision and collision occurence in Shapes
 namespace should be marked with @c \@collisionoperator and @c \@collisionoccurenceoperator,
 e.g.:
-@code
-// @collisionoccurenceoperator{Point,Sphere}
-inline bool operator%(const Point& a, const Sphere& b) { return b % a; }
 
-// @collisionoperator{Point,Sphere}
+@snippet coding-style.h collisionoperator
-inline Collision operator/(const Point& a, const Sphere& b) { return (b/a).reverted(); }
+
-@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 coding-style-documentation-commands-extension Links to OpenGL extensions
+@subsubsection coding-style-documentation-commands-extension Links to OpenGL and OpenAL extensions
 
 If an OpenGL extension is referenced in the documentation, it should be done
 with @c \@extension command:
-@code
+
+@snippet coding-style.h extension
+
+It produces a link to the specification of the extension in OpenGL registry:
+
+<blockquote>
 @extension{ARB,timer_query}
-@endcode
+</blockquote>
-It produces link to the specification of the extension in OpenGL registry:
-> @extension{ARB,timer_query}
 
 With command @c \@extension2 you can specify extension filename, if the
 previous command gives 404 error. For example
-@code
+
-@extension2{NV,read_buffer_front,GL_NV_read_buffer}
+@snippet coding-style.h extension2
-@endcode
+
 produces this link:
-> @extension2{NV,read_buffer_front,GL_NV_read_buffer}
 
-@subsubsection coding-style-documentation-commands-ref_gl Links to related OpenGL functions and definitions
+<blockquote>
+@extension2{NV,read_buffer_front,GL_NV_read_buffer}
+</blockquote>
+
+OpenAL extensions can be referenced using @c \@al_extension, OpenAL context
+extension using @c \@alc_extension. For example
+
+@snippet coding-style.h al_extension
+
+produces the following:
+
+<blockquote>
+@al_extension{EXT,float32}, @alc_extension{SOFT,HRTF}
+</blockquote>
+
+@subsubsection coding-style-documentation-commands-ref_gl Links to related OpenGL, OpenAL 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}
+@snippet coding-style.h fn_gl
-static void setSeamless(bool enabled) {
+
-    enabled ? glEnable(GL_TEXTURE_CUBE_MAP_SEAMLESS) : glDisable(GL_TEXTURE_CUBE_MAP_SEAMLESS);
+It produces a link to the online manual:
-}
+
-@endcode
+<blockquote>
-It produces link to the online manual:
+@fn_gl{Enable}/@fn_gl{Disable} with @def_gl{TEXTURE_CUBE_MAP_SEAMLESS}
-> @fn_gl{Enable}/@fn_gl{Disable} with @def_gl{TEXTURE_CUBE_MAP_SEAMLESS}.
+</blockquote>
 
 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}
+@snippet coding-style.h fn_gl_extension
-@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:
-> @fn_gl_extension{NamedCopyBufferSubData,EXT,direct_state_access}.
 
-@subsubsection coding-style-documentation-commands-requires Classes and functions requiring specific OpenGL version or extensions
+<blockquote>
+@fn_gl_extension{NamedCopyBufferSubData,EXT,direct_state_access}
+</blockquote>
+
+For OpenAL, the commands are @c \@fn_al, @c \@fn_alc, @c \@def_al and
+@c \@def_alc. Example:
+
+@snippet coding-style.h fn_al
+
+Produces:
+
+<blockquote>
+@fn_al{Listenerfv} with @def_al{VELOCITY}
+</blockquote>
+
+@subsubsection coding-style-documentation-commands-requires Classes and functions requiring specific OpenGL, OpenAL 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
@@ -169,9 +188,8 @@ 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}
+@snippet coding-style.h requires_gl
-@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
@@ -190,6 +208,10 @@ requirements.
 All classes and functions using those commands are cross-referenced in page
 @ref opengl-required-extensions.
 
+For OpenAL, the command is @c \@requires_al_extension:
+
+@snippet coding-style.h requires_al_extension
+
 @subsection coding-style-documentation-ordering Section ordering
 
 In detailed documentation the text should be always first, the blocks are then
@@ -206,14 +228,15 @@ and in most cases only for internal use.
 
 All unit tests use Corrade's @ref Corrade::TestSuite "TestSuite".
 
-Don't forget to test all `constexpr` methods --- many compilers don't implicitly
+Don't forget to test all @cpp constexpr @ce methods --- many compilers don't
-check whether the `constexpr` keyword can be used but then complain when you
+implicitly check whether the @cpp constexpr @ce keyword can be used but then
-force the expression to be constant. It's better not to have given method
+complain when you force the expression to be constant. It's better not to have
-marked as `constexpr` than have it marked it errorneously. It's usually not
+given method marked as @cpp constexpr @ce than have it marked it errorneously.
-desirable to have special test case for `constexpr` behaviors, add `constexpr`
+It's usually not desirable to have special test case for @cpp constexpr @ce
-keywords to existing test cases to avoid duplicated testing of the same thing.
+behaviors, add @cpp constexpr @ce keywords to existing test cases to avoid
-Example (testing copy constructor):
+duplicated testing of the same thing. Example (testing a copy constructor):
-@code
+
+@code{.cpp}
 constexpr Vector3 a(1.5f, 2.0f, 0.4f);
 constexpr Vector3 b(a);
 CORRADE_COMPARE(b, Vector3(1.5f, 2.0f, 0.4f));
@@ -223,9 +246,11 @@ Don't forget to test implicit/explicit constructors and conversion operators
 where it matters (i.e. all low-level and frequently used types like vectors,
 matrices etc.). If the constructor/operator is implicit, test it in the context
 where explicit one would fail to compile, if it is explicit, test its
-explicitness with `std::is_convertible` (it should return `false`). These tests
+explicitness with @ref std::is_convertible (it should return @cpp false @ce).
-might catch various ambiguous call errors which would otherwise be unnoticed:
+These tests might catch various ambiguous call errors which would otherwise be
-@code
+unnoticed:
+
+@code{.cpp}
 Vector2 a = {1.5f, 0.5f}; // Explicit constructor would fail to compile here
 CORRADE_COMPARE(a, Vector2(1.5f, 0.5f));
 
@@ -240,7 +265,8 @@ only for low-level frequently used types (vectors, matrices) where such error
 would do largest harm. Depending on how copy constructor is implemented, you
 probably don't need to test classic copy construction, as it would be handled
 by the already tested one. Example (copy construction from base type):
-@code
+
+@code{.cpp}
 Vector<3, Float> a(1.5f, 2.0f, 0.4f);
 Vector3 b(a);
 CORRADE_COMPARE(b, Vector3(1.5f, 2.0f, 0.4f));

doc/snippets/coding-style.h

@@ -0,0 +1,64 @@
+/* [glcompatibility] */
+#ifndef MAGNUM_TARGET_GLES
+/**
+@brief Set polygon mode
+
+@requires_gl Polygon mode is not available in OpenGL ES.
+*/
+void setPolygonMode(PolygonMode mode);
+#endif
+/* [glcompatibility] */
+
+/* [collisionoperator] */
+/** @collisionoccurenceoperator{Point,Sphere} */
+inline bool operator%(const Point& a, const Sphere& b) { return b % a; }
+
+/** @collisionoperator{Point,Sphere} */
+inline Collision operator/(const Point& a, const Sphere& b) { return (b/a).reverted(); }
+/* [collisionoperator] */
+
+/* [extension] */
+/** @extension{ARB,timer_query} */
+/* [extension] */
+
+/* [extension2] */
+/** @extension2{NV,read_buffer_front,GL_NV_read_buffer} */
+/* [extension2] */
+
+/* [al_extension] */
+/** @al_extension{EXT,float32}, @alc_extension{SOFT,HRTF} */
+/* [al_extension] */
+
+/* [fn_gl] */
+/**
+...
+
+@see @fn_gl{Enable}/@fn_gl{Disable} with @def_gl{TEXTURE_CUBE_MAP_SEAMLESS}
+*/
+static void setSeamless(bool enabled) {
+    enabled ? glEnable(GL_TEXTURE_CUBE_MAP_SEAMLESS) : glDisable(GL_TEXTURE_CUBE_MAP_SEAMLESS);
+}
+/* [fn_gl] */
+
+/* [fn_gl_extension] */
+/** @fn_gl_extension{NamedCopyBufferSubData,EXT,direct_state_access} */
+/* [fn_gl_extension] */
+
+/* [fn_al] */
+/**
+...
+
+@see @fn_al{Listenerfv} with @def_al{VELOCITY}
+*/
+static void setListenerVelocity(const Vector3& velocity) {
+    alListenerfv(AL_VELOCITY, velocity.data());
+}
+/* [fn_al] */
+
+/* [requires_gl] */
+/** @requires_gl33 Extension @extension{ARB,timer_query} */
+/* [requires_gl] */
+
+/* [requires_al_extension] */
+/** @requires_al_extension Extension @al_extension{EXT,MCFORMATS} */
+/* [requires_al_extension] */