doc: implement Vulkan-specific Doxygen aliases.

mosra · May 14, 2018 · 7cb94ac · 7cb94ac
1 parent 8f9d138
commit 7cb94ac
Show file tree

Hide file tree

Showing 5 changed files with 71 additions and 5 deletions.
diff --git a/Doxyfile b/Doxyfile
@@ -275,6 +275,11 @@ ALIASES                = \
     "requires_webgl20=@xrefitem requires-webgl20 \"Requires WebGL 2.0\" \"Functionality requiring WebGL 2.0\"" \
     "requires_webgl_extension=@xrefitem requires-webgl-extension \"Requires WebGL extension\" \"Functionality requiring specific WebGL extension\"" \
     "webgl_extension{2}=<a href=\"https://www.khronos.org/registry/webgl/extensions/\1_\2/\">\1_\2</a>" \
+    "fn_vk{1}=<a href=\"https://www.khronos.org/registry/vulkan/specs/1.0/man/html/vk\1.html\">vk\1()</a>" \
+    "type_vk{1}=<a href=\"https://www.khronos.org/registry/vulkan/specs/1.0/man/html/Vk\1.html\">Vk\1</a>" \
+    "def_vk{2}=<a href=\"https://www.khronos.org/registry/vulkan/specs/1.0/man/html/Vk\2.html\">VK_\1</a>" \
+    "requires_vk_extension=@xrefitem requires-vk-extension \"Requires Vulkan extension\" \"Functionality requiring specific Vulkan extension\"" \
+    "vk_extension{2}= <a href=\"https://www.khronos.org/registry/vulkan/specs/1.0-extensions/html/vkspec.html#VK_\1_\2\">\1_\2</a>" \
     "fn_al{1}=`al\1()`" \
     "fn_alc{1}=`alc\1()`" \
     "def_al{1}=`AL_\1`" \
@@ -303,6 +308,9 @@ ALIASES                = \
     "fn_gl_extension_keyword{3}=@fn_gl_extension{\1,\2,\3}" \
     "def_gl_keyword{1}=@def_gl{\1}" \
     "def_gl_extension_keyword{3}=@def_gl_extension{\1,\2,\3}" \
+    "fn_vk_keyword{1}=@fn_vk{\1}" \
+    "type_vk_keyword{2}=@type_vk{\1,\2}" \
+    "def_vk_keyword{2}=@def_vk{\1,\2}" \
     "fn_al_keyword{1}=@fn_al{\1}" \
     "fn_alc_keyword{1}=@fn_alc{\1}" \
     "def_al_keyword{1}=@def_al{\1}" \

diff --git a/Doxyfile-mcss b/Doxyfile-mcss
@@ -55,6 +55,11 @@ ALIASES                = \
     "requires_webgl20=@xrefitem requires-webgl20 \"Requires WebGL 2.0\" \"Functionality requiring WebGL 2.0\"" \
     "requires_webgl_extension=@xrefitem requires-webgl-extension \"Requires WebGL extension\" \"Functionality requiring specific WebGL extension\"" \
     "webgl_extension{2}=@m_class{m-dox-external} <a href=\"https://www.khronos.org/registry/webgl/extensions/\1_\2/\">\1_\2</a>" \
+    "fn_vk{1}=@m_class{m-dox-external} <a href=\"https://www.khronos.org/registry/vulkan/specs/1.0/man/html/vk\1.html\">vk\1()</a>" \
+    "type_vk{1}=@m_class{m-dox-external} <a href=\"https://www.khronos.org/registry/vulkan/specs/1.0/man/html/Vk\1.html\">Vk\1</a>" \
+    "def_vk{2}=@m_class{m-dox-external} <a href=\"https://www.khronos.org/registry/vulkan/specs/1.0/man/html/Vk\2.html\">VK_\1</a>" \
+    "requires_vk_extension=@xrefitem requires-vk-extension \"Requires Vulkan extension\" \"Functionality requiring specific Vulkan extension\"" \
+    "vk_extension{2}=@m_class{m-dox-external} <a href=\"https://www.khronos.org/registry/vulkan/specs/1.0-extensions/html/vkspec.html#VK_\1_\2\">\1_\2</a>" \
     "fn_al{1}=`al\1()`" \
     "fn_alc{1}=`alc\1()`" \
     "def_al{1}=`AL_\1`" \
@@ -83,6 +88,9 @@ ALIASES                = \
     "fn_gl_extension_keyword{3}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keywords=\"gl\1\2()\" />@endxmlonly @fn_gl_extension{\1,\2,\3}" \
     "def_gl_keyword{1}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keywords=\"GL_\1\" />@endxmlonly @def_gl{\1}" \
     "def_gl_extension_keyword{3}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keywords=\"GL_\1_\2\" />@endxmlonly @def_gl_extension{\1,\2,\3}" \
+    "fn_vk_keyword{1}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keywords=\"vk\1()\" />@endxmlonly @fn_vk{\1}" \
+    "type_vk_keyword{1}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keywords=\"Vk\1\" />@endxmlonly @type_vk{\1}" \
+    "def_vk_keyword{2}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keywords=\"VK_\1\" />@endxmlonly @def_vk{\1,\2}" \
     "fn_al_keyword{1}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keywords=\"al\1()\" />@endxmlonly @fn_al{\1}" \
     "fn_alc_keyword{1}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keywords=\"alc\1()\" />@endxmlonly @fn_alc{\1}" \
     "def_al_keyword{1}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keywords=\"AL_\1\" />@endxmlonly @def_al{\1}" \

diff --git a/Doxyfile-public b/Doxyfile-public
@@ -51,6 +51,11 @@ ALIASES                = \
     "requires_webgl20=@xrefitem requires-webgl20 \"Requires WebGL 2.0\" \"Functionality requiring WebGL 2.0\"" \
     "requires_webgl_extension=@xrefitem requires-webgl-extension \"Requires WebGL extension\" \"Functionality requiring specific WebGL extension\"" \
     "webgl_extension{2}=@m_class{m-dox-external} <a href=\"https://www.khronos.org/registry/webgl/extensions/\1_\2/\">\1_\2</a>" \
+    "fn_vk{1}=@m_class{m-dox-external} <a href=\"https://www.khronos.org/registry/vulkan/specs/1.0/man/html/vk\1.html\">vk\1()</a>" \
+    "type_vk{1}=@m_class{m-dox-external} <a href=\"https://www.khronos.org/registry/vulkan/specs/1.0/man/html/Vk\1.html\">Vk\1</a>" \
+    "def_vk{2}=@m_class{m-dox-external} <a href=\"https://www.khronos.org/registry/vulkan/specs/1.0/man/html/Vk\2.html\">VK_\1</a>" \
+    "requires_vk_extension=@xrefitem requires-vk-extension \"Requires Vulkan extension\" \"Functionality requiring specific Vulkan extension\"" \
+    "vk_extension{2}=@m_class{m-dox-external} <a href=\"https://www.khronos.org/registry/vulkan/specs/1.0-extensions/html/vkspec.html#VK_\1_\2\">\1_\2</a>" \
     "fn_al{1}=`al\1()`" \
     "fn_alc{1}=`alc\1()`" \
     "def_al{1}=`AL_\1`" \
@@ -79,6 +84,9 @@ ALIASES                = \
     "fn_gl_extension_keyword{3}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keywords=\"gl\1\2()\" />@endxmlonly @fn_gl_extension{\1,\2,\3}" \
     "def_gl_keyword{1}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keywords=\"GL_\1\" />@endxmlonly @def_gl{\1}" \
     "def_gl_extension_keyword{3}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keywords=\"GL_\1_\2\" />@endxmlonly @def_gl_extension{\1,\2,\3}" \
+    "fn_vk_keyword{1}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keywords=\"vk\1()\" />@endxmlonly @fn_vk{\1}" \
+    "type_vk_keyword{1}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keywords=\"Vk\1\" />@endxmlonly @type_vk{\1}" \
+    "def_vk_keyword{2}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keywords=\"VK_\1\" />@endxmlonly @def_vk{\1,\2}" \
     "fn_al_keyword{1}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keywords=\"al\1()\" />@endxmlonly @fn_al{\1}" \
     "fn_alc_keyword{1}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keywords=\"alc\1()\" />@endxmlonly @fn_alc{\1}" \
     "def_al_keyword{1}=@xmlonly<mcss:search xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:keywords=\"AL_\1\" />@endxmlonly @def_al{\1}" \

diff --git a/doc/coding-style.dox b/doc/coding-style.dox
@@ -113,7 +113,7 @@ 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 and OpenAL extensions
+@subsubsection coding-style-documentation-commands-extension Links to OpenGL, Vulkan and OpenAL extensions
 
 If an OpenGL extension is referenced in the documentation, it should be done
 with @c \@gl_extension command:
@@ -147,6 +147,16 @@ produces this:
 @webgl_extension{EXT,color_buffer_float}
 </blockquote>
 
+Vulkan extensions can be referenced using @c \@vk_extension. For example
+
+@snippet coding-style.h vk_extension
+
+produces this link:
+
+<blockquote>
+@vk_extension{EXT,debug_report}
+</blockquote>
+
 OpenAL extensions can be referenced using @c \@al_extension, OpenAL context
 extension using @c \@alc_extension. For example
 
@@ -158,7 +168,7 @@ produces the following:
 @al_extension{EXT,float32}, @alc_extension{SOFT,HRTF}
 </blockquote>
 
-@subsubsection coding-style-documentation-commands-ref Links to related OpenGL, OpenAL functions and definitions
+@subsubsection coding-style-documentation-commands-ref Links to related OpenGL, Vulkan, 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
@@ -195,6 +205,18 @@ specification, with function name as link text:
 @fn_gl_extension{NamedCopyBufferSubData,EXT,direct_state_access}
 </blockquote>
 
+For Vulkan, the commands are @c \@fn_vk, @c \@type_vk and @c \@def_vk. Example:
+
+@snippet coding-style.h fn_vk
+
+Produces:
+
+<blockquote>
+-   @fn_vk{CreateInstance}
+-   @type_vk{InstanceCreateInfo}
+-   @def_vk{STRUCTURE_TYPE_INSTANCE_CREATE_INFO,StructureType}
+</blockquote>
+
 For OpenAL, the commands are @c \@fn_al, @c \@fn_alc, @c \@def_al and
 @c \@def_alc. Example:
 
@@ -214,7 +236,7 @@ it's @c \@fn_gl_keyword, @c \@fn_gl2_keyword, @c \@def_gl_keyword,
 @c \@def_alc_keyword. Their usage is equivalent to usage of commands without
 the `_keyword` suffix.
 
-@subsubsection coding-style-documentation-commands-requires Classes and functions requiring specific OpenGL, OpenAL version or extensions
+@subsubsection coding-style-documentation-commands-requires Classes and functions requiring specific OpenGL, Vulkan, 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
@@ -241,13 +263,17 @@ for specific extensions not part of the core OpenGL ES specification and
 WebGL specification. When there is more than just a single platform, first come
 desktop requirements, then ES requirements and WebGL requirements last.
 
-All classes and functions using those commands are cross-referenced in page
-@ref opengl-required-extensions.
+For Vulkan, the command is @c \@requires_vk_extension:
+
+@snippet coding-style.h requires_vk_extension
 
 For OpenAL, the command is @c \@requires_al_extension:
 
 @snippet coding-style.h requires_al_extension
 
+All classes and functions using those commands are cross-referenced from
+@ref opengl, @ref vulkan and @ref openal pages.
+
 @subsection coding-style-documentation-ordering Section ordering
 
 In detailed documentation the text should be always first, the blocks are then

diff --git a/doc/snippets/coding-style.h b/doc/snippets/coding-style.h
@@ -29,6 +29,10 @@ inline Collision operator/(const Point& a, const Sphere& b) { return (b/a).rever
 /** @webgl_extension{EXT,color_buffer_float} */
 /* [webgl_extension] */
 
+/* [vk_extension] */
+/** @vk_extension{EXT,debug_report} */
+/* [vk_extension] */
+
 /* [al_extension] */
 /** @al_extension{EXT,float32}, @alc_extension{SOFT,HRTF} */
 /* [al_extension] */
@@ -52,6 +56,14 @@ static void setSeamless(bool enabled) {
 /** @fn_gl_extension{NamedCopyBufferSubData,EXT,direct_state_access} */
 /* [fn_gl_extension] */
 
+/* [fn_vk] */
+/**
+-   @fn_vk{CreateInstance}
+-   @type_vk{InstanceCreateInfo}
+-   @def_vk{STRUCTURE_TYPE_INSTANCE_CREATE_INFO,StructureType}
+*/
+/* [fn_vk] */
+
 /* [fn_al] */
 /**
 ...
@@ -67,6 +79,10 @@ static void setListenerVelocity(const Vector3& velocity) {
 /** @requires_gl33 Extension @gl_extension{ARB,timer_query} */
 /* [requires_gl] */
 
+/* [requires_vk_extension] */
+/** @requires_vk_extension Extension @vk_extension{EXT,debug_report} */
+/* [requires_vk_extension] */
+
 /* [requires_al_extension] */
 /** @requires_al_extension Extension @al_extension{EXT,MCFORMATS} */
 /* [requires_al_extension] */