From 7cb94ac32d30155feb1a23d47f0a2195aaf3512d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Tue, 6 Mar 2018 12:05:28 +0100 Subject: [PATCH] doc: implement Vulkan-specific Doxygen aliases. --- Doxyfile | 8 ++++++++ Doxyfile-mcss | 8 ++++++++ Doxyfile-public | 8 ++++++++ doc/coding-style.dox | 36 +++++++++++++++++++++++++++++++----- doc/snippets/coding-style.h | 16 ++++++++++++++++ 5 files changed, 71 insertions(+), 5 deletions(-) diff --git a/Doxyfile b/Doxyfile index d2dba2b0e..8f55c5e4c 100644 --- 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}=\1_\2" \ + "fn_vk{1}=vk\1()" \ + "type_vk{1}=Vk\1" \ + "def_vk{2}=VK_\1" \ + "requires_vk_extension=@xrefitem requires-vk-extension \"Requires Vulkan extension\" \"Functionality requiring specific Vulkan extension\"" \ + "vk_extension{2}= \1_\2" \ "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 index 7e8d452f7..610499c4d 100644 --- 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} \1_\2" \ + "fn_vk{1}=@m_class{m-dox-external} vk\1()" \ + "type_vk{1}=@m_class{m-dox-external} Vk\1" \ + "def_vk{2}=@m_class{m-dox-external} VK_\1" \ + "requires_vk_extension=@xrefitem requires-vk-extension \"Requires Vulkan extension\" \"Functionality requiring specific Vulkan extension\"" \ + "vk_extension{2}=@m_class{m-dox-external} \1_\2" \ "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@endxmlonly @fn_gl_extension{\1,\2,\3}" \ "def_gl_keyword{1}=@xmlonly@endxmlonly @def_gl{\1}" \ "def_gl_extension_keyword{3}=@xmlonly@endxmlonly @def_gl_extension{\1,\2,\3}" \ + "fn_vk_keyword{1}=@xmlonly@endxmlonly @fn_vk{\1}" \ + "type_vk_keyword{1}=@xmlonly@endxmlonly @type_vk{\1}" \ + "def_vk_keyword{2}=@xmlonly@endxmlonly @def_vk{\1,\2}" \ "fn_al_keyword{1}=@xmlonly@endxmlonly @fn_al{\1}" \ "fn_alc_keyword{1}=@xmlonly@endxmlonly @fn_alc{\1}" \ "def_al_keyword{1}=@xmlonly@endxmlonly @def_al{\1}" \ diff --git a/Doxyfile-public b/Doxyfile-public index 8c00d3e46..f6f552449 100644 --- 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} \1_\2" \ + "fn_vk{1}=@m_class{m-dox-external} vk\1()" \ + "type_vk{1}=@m_class{m-dox-external} Vk\1" \ + "def_vk{2}=@m_class{m-dox-external} VK_\1" \ + "requires_vk_extension=@xrefitem requires-vk-extension \"Requires Vulkan extension\" \"Functionality requiring specific Vulkan extension\"" \ + "vk_extension{2}=@m_class{m-dox-external} \1_\2" \ "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@endxmlonly @fn_gl_extension{\1,\2,\3}" \ "def_gl_keyword{1}=@xmlonly@endxmlonly @def_gl{\1}" \ "def_gl_extension_keyword{3}=@xmlonly@endxmlonly @def_gl_extension{\1,\2,\3}" \ + "fn_vk_keyword{1}=@xmlonly@endxmlonly @fn_vk{\1}" \ + "type_vk_keyword{1}=@xmlonly@endxmlonly @type_vk{\1}" \ + "def_vk_keyword{2}=@xmlonly@endxmlonly @def_vk{\1,\2}" \ "fn_al_keyword{1}=@xmlonly@endxmlonly @fn_al{\1}" \ "fn_alc_keyword{1}=@xmlonly@endxmlonly @fn_alc{\1}" \ "def_al_keyword{1}=@xmlonly@endxmlonly @def_al{\1}" \ diff --git a/doc/coding-style.dox b/doc/coding-style.dox index 739c620d0..4c7476454 100644 --- 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} +Vulkan extensions can be referenced using @c \@vk_extension. For example + +@snippet coding-style.h vk_extension + +produces this link: + +
+@vk_extension{EXT,debug_report} +
+ 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} -@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} +For Vulkan, the commands are @c \@fn_vk, @c \@type_vk and @c \@def_vk. Example: + +@snippet coding-style.h fn_vk + +Produces: + +
+- @fn_vk{CreateInstance} +- @type_vk{InstanceCreateInfo} +- @def_vk{STRUCTURE_TYPE_INSTANCE_CREATE_INFO,StructureType} +
+ 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 index aba5d43a1..7257695b9 100644 --- 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] */