IDL: Improve docs. (#3614)

docs/bgfx.rst

@@ -15,6 +15,8 @@ API Reference
 General
 -------
 
+General API for initialization, shutdown, frame management, debug, and querying renderer information.
+
 Initialization and Shutdown
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -42,6 +44,8 @@ Updating
 Reset
 *****
 
+Reset flags control back-buffer resolution, MSAA, vsync, and other global rendering settings.
+
 .. doxygendefine:: BGFX_RESET_NONE
 .. doxygendefine:: BGFX_RESET_FULLSCREEN
 .. doxygendefine:: BGFX_RESET_VSYNC
@@ -61,6 +65,8 @@ Reset
 Frame
 *****
 
+Frame flags and the ``bgfx::frame`` call to advance to the next frame.
+
 .. doxygendefine:: BGFX_FRAME_NONE
 .. doxygendefine:: BGFX_FRAME_DEBUG_CAPTURE
 .. doxygendefine:: BGFX_FRAME_DISCARD
@@ -73,11 +79,15 @@ Debug
 Debug Features
 **************
 
+Enable or disable debug features.
+
 .. doxygenfunction:: bgfx::setDebug
 
 Debug Flags
 ***********
 
+Flags for ``bgfx::setDebug``.
+
 .. doxygendefine:: BGFX_DEBUG_NONE
 .. doxygendefine:: BGFX_DEBUG_WIREFRAME
 .. doxygendefine:: BGFX_DEBUG_IFH
@@ -88,6 +98,8 @@ Debug Flags
 Debug Text Display
 ******************
 
+Functions for printing debug text on screen.
+
 .. doxygenfunction:: bgfx::dbgTextClear
 .. doxygenfunction:: bgfx::dbgTextPrintf
 .. doxygenfunction:: bgfx::dbgTextPrintfVargs
@@ -99,6 +111,8 @@ Querying information
 Renderer
 ********
 
+Query the active rendering backend.
+
 .. doxygenstruct:: bgfx::RendererType
     :members:
 
@@ -108,9 +122,13 @@ Renderer
 Capabilities
 ************
 
+Query GPU capabilities and limits.
+
 Available Caps
 """"""""""""""
 
+Individual capability flags.
+
 .. doxygendefine:: BGFX_CAPS_ALPHA_TO_COVERAGE
 .. doxygendefine:: BGFX_CAPS_BLEND_INDEPENDENT
 .. doxygendefine:: BGFX_CAPS_COMPUTE
@@ -150,6 +168,8 @@ Available Caps
 Statistics
 **********
 
+Per-frame rendering statistics.
+
 .. doxygenstruct:: bgfx::ViewStats
     :members:
 
@@ -265,6 +285,8 @@ All state is cleared after calling ``bgfx::submit``.
 Debug
 *****
 
+Debug markers for grouping draw calls in graphics debugging tools.
+
 .. doxygenfunction:: bgfx::setName(ShaderHandle _handle, const char* _name, int32_t _len = INT32_MAX)
 .. doxygenfunction:: bgfx::setName(TextureHandle _handle, const char* _name, int32_t _len = INT32_MAX)
 .. doxygenfunction:: bgfx::setMarker
@@ -272,11 +294,15 @@ Debug
 State
 *****
 
+Configure render state for draw calls.
+
 .. doxygenfunction:: bgfx::setState
 
 State Flags
 ***********
 
+Render state flags for depth test, blending, culling, etc.
+
 **Write**
 
 .. doxygendefine:: BGFX_STATE_WRITE_R
@@ -348,11 +374,15 @@ State Flags
 Stencil
 *******
 
+Configure stencil test for draw calls.
+
 .. doxygenfunction:: bgfx::setStencil
 
 Stencil Flags
 *************
 
+Stencil test configuration flags.
+
 .. doxygendefine:: BGFX_STENCIL_TEST_LESS
 .. doxygendefine:: BGFX_STENCIL_TEST_LEQUAL
 .. doxygendefine:: BGFX_STENCIL_TEST_EQUAL
@@ -375,6 +405,8 @@ Otherwise, use ``bgfx::setViewScissor``.
 Transform
 *********
 
+Set model transform matrices for draw calls.
+
 .. doxygenfunction:: bgfx::setTransform(const void* _mtx, uint16_t _num = 1)
 .. doxygenfunction:: bgfx::setTransform(uint32_t _cache, uint16_t _num = 1)
 .. doxygenfunction:: bgfx::allocTransform
@@ -382,11 +414,15 @@ Transform
 Conditional Rendering
 *********************
 
+Conditionally render based on occlusion query results.
+
 .. doxygenfunction:: bgfx::setCondition
 
 Buffers
 *******
 
+Set vertex, index, and instance data buffers for draw calls.
+
 .. doxygenstruct:: bgfx::TransientIndexBuffer
     :members:
 
@@ -415,11 +451,15 @@ Buffers
 Textures
 ********
 
+Bind textures to texture stages for draw calls.
+
 .. doxygenfunction:: bgfx::setTexture
 
 Uniforms
 ********
 
+Set shader uniform parameters for draw calls.
+
 .. doxygenfunction:: bgfx::setViewUniform
 .. doxygenfunction:: bgfx::setFrameUniform
 .. doxygenfunction:: bgfx::setUniform
@@ -442,6 +482,8 @@ Compute state is not preserved between compute dispatches; all state is cleared
 Buffers
 *******
 
+Bind buffers to compute stages.
+
 .. doxygenstruct:: bgfx::Access
     :members:
 
@@ -454,6 +496,8 @@ Buffers
 Images
 ******
 
+Bind texture images to compute stages.
+
 .. doxygenfunction:: bgfx::setImage
 
 Dispatch
@@ -480,7 +524,7 @@ Shaders and Programs
 
 .. note::
 
-    Shaders must be compiled with offline command line too shaderc.
+    Shaders must be compiled with offline command line tool shaderc.
 
 .. doxygenfunction:: bgfx::createShader
 .. doxygenfunction:: bgfx::getShaderUniforms

scripts/bgfx.idl

@@ -1150,7 +1150,7 @@ func.vertexConvert { section = "Miscellaneous" }
 	.num       "uint32_t"             --- Number of vertices to convert from source to destination.
 	 { default = 1 }
 
---- Weld vertices.
+--- Weld vertices. Returns number of unique vertices after welding.
 func.weldVertices { section = "Miscellaneous" }
 	"uint32_t"                              --- Number of unique vertices after vertex welding.
 	.output          "void*"                --- Welded vertices remapping table. The size of buffer
@@ -1402,7 +1402,7 @@ func.destroy { cname = "destroy_index_buffer", section = "Index Buffers" }
 	"void"
 	.handle "IndexBufferHandle" --- Static index buffer handle.
 
---- Create vertex layout.
+--- Create vertex layout. Vertex layouts are used to describe the format of vertex data.
 func.createVertexLayout { section = "Vertex Buffers" }
 	"VertexLayoutHandle"
 	.layout  "const VertexLayout &" --- Vertex layout.
@@ -2063,7 +2063,8 @@ func.destroy { cname = "destroy_uniform", section = "Uniforms" }
 	"void"
 	.handle "UniformHandle" --- Handle to uniform object.
 
---- Create occlusion query.
+--- Create occlusion query. Occlusion queries allow the GPU to determine
+--- if any pixels passed the depth test.
 func.createOcclusionQuery { section = "Occlusion Query" }
 	"OcclusionQueryHandle" --- Handle to occlusion query object.
 
@@ -2467,6 +2468,7 @@ func.Encoder.setVertexBuffer { conly, cname = "set_dynamic_vertex_buffer" }
 	.startVertex  "uint32_t"                  --- First vertex to render.
 	.numVertices  "uint32_t"                  --- Number of vertices to render.
 
+--- Set vertex buffer for draw primitive.
 func.Encoder.setVertexBuffer { cname = "set_dynamic_vertex_buffer_with_layout", section = "Draw/Buffers" }
 	"void"
 	.stream       "uint8_t"                   --- Vertex stream.
@@ -3346,6 +3348,7 @@ func.blit { section = "Blit" }
 -- Documentation sections for RST generation
 --------------------------------------------------------------------------------
 
+--- General API for initialization, shutdown, frame management, debug, and querying renderer information.
 section("General", 1)
 
 --- Initialization and Shutdown
@@ -3354,28 +3357,37 @@ section("Initialization and Shutdown", 2)
 --- Updating
 section("Updating", 2)
 
+--- Reset flags control back-buffer resolution, MSAA, vsync, and other global rendering settings.
 section("Reset", 3)
 
+--- Frame flags and the ``bgfx::frame`` call to advance to the next frame.
 section("Frame", 3)
 
 --- Debug
 section("Debug", 2)
 
+--- Enable or disable debug features.
 section("Debug Features", 3)
 
+--- Flags for ``bgfx::setDebug``.
 section("Debug Flags", 3)
 
+--- Functions for printing debug text on screen.
 section("Debug Text Display", 3)
 
 --- Querying information
 section("Querying information", 2)
 
+--- Query the active rendering backend.
 section("Renderer", 3)
 
+--- Query GPU capabilities and limits.
 section("Capabilities", 3)
 
+--- Individual capability flags.
 section("Available Caps", 4)
 
+--- Per-frame rendering statistics.
 section("Statistics", 3)
 
 --- Platform specific
@@ -3417,14 +3429,19 @@ section("Encoder", 2)
 --- All state is cleared after calling ``bgfx::submit``.
 section("Draw", 2)
 
+--- Debug markers for grouping draw calls in graphics debugging tools.
 section("Debug", 3)
 
+--- Configure render state for draw calls.
 section("State", 3)
 
+--- Render state flags for depth test, blending, culling, etc.
 section("State Flags", 3)
 
+--- Configure stencil test for draw calls.
 section("Stencil", 3)
 
+--- Stencil test configuration flags.
 section("Stencil Flags", 3)
 
 --- Scissor
@@ -3434,14 +3451,19 @@ section("Stencil Flags", 3)
 --- Otherwise, use ``bgfx::setViewScissor``.
 section("Scissor", 3)
 
+--- Set model transform matrices for draw calls.
 section("Transform", 3)
 
+--- Conditionally render based on occlusion query results.
 section("Conditional Rendering", 3)
 
+--- Set vertex, index, and instance data buffers for draw calls.
 section("Buffers", 3)
 
+--- Bind textures to texture stages for draw calls.
 section("Textures", 3)
 
+--- Set shader uniform parameters for draw calls.
 section("Uniforms", 3)
 
 --- Submit
@@ -3454,8 +3476,10 @@ section("Submit", 3)
 --- Compute state is not preserved between compute dispatches; all state is cleared after calling ``bgfx::dispatch``.
 section("Compute", 2)
 
+--- Bind buffers to compute stages.
 section("Buffers", 3)
 
+--- Bind texture images to compute stages.
 section("Images", 3)
 
 --- Dispatch
@@ -3473,7 +3497,7 @@ section("Resources", 1)
 
 --- Shaders and Programs
 ---
---- @remarks Shaders must be compiled with offline command line too shaderc.
+--- @remarks Shaders must be compiled with offline command line tool shaderc.
 section("Shaders and Programs", 2)
 
 --- Uniforms

scripts/codegen.lua

@@ -708,7 +708,19 @@ function codegen.doxygen_type(doxygen, func, cname)
 		end
 	end
 	result[#result+1] = "///"
-	return table.concat(result, "\n")
+
+	-- Collapse consecutive empty comment lines (///) into at most one.
+	local collapsed = {}
+	for _, line in ipairs(result) do
+		local is_empty = (line == "///" or line == "/// ")
+		local prev_empty = #collapsed > 0 and (collapsed[#collapsed] == "///" or collapsed[#collapsed] == "/// ")
+		if is_empty and prev_empty then
+			-- skip duplicate empty comment line
+		else
+			collapsed[#collapsed+1] = line
+		end
+	end
+	return table.concat(collapsed, "\n")
 end
 
 function codegen.doxygen_ctype(doxygen, func)
@@ -728,7 +740,19 @@ function codegen.doxygen_ctype(doxygen, func)
 	end
 	result[#result+1] = " *"
 	result[#result+1] = " */"
-	return table.concat(result, "\n")
+
+	-- Collapse consecutive empty comment lines ( *) into at most one.
+	local collapsed = {}
+	for _, line in ipairs(result) do
+		local is_empty = (line == " *" or line == " * ")
+		local prev_empty = #collapsed > 0 and (collapsed[#collapsed] == " *" or collapsed[#collapsed] == " * ")
+		if is_empty and prev_empty then
+			-- skip duplicate empty comment line
+		else
+			collapsed[#collapsed+1] = line
+		end
+	end
+	return table.concat(collapsed, "\n")
 end
 
 local enum_temp = [[

scripts/doxygen.lua

@@ -10,6 +10,8 @@ function doxygen.load(filename)
 			else
 				line = string.format("%s [[%s]]", code, comment)
 			end
+		elseif line:match "^%-%-%-$" then
+			line = "comment [[]]"
 		end
 		lines[#lines+1] = line
 	end