Merge pull request #61058 from Calinou/doc-performance

1 files changed, 36 insertions, 34 deletions

diff --git a/doc/classes/Performance.xml b/doc/classes/Performance.xml
index bcaf38fd06..01da9cb9a2 100644
--- a/doc/classes/Performance.xml
+++ b/doc/classes/Performance.xml
@@ -6,8 +6,8 @@
 	<description>
 		This class provides access to a number of different monitors related to performance, such as memory usage, draw calls, and FPS. These are the same as the values displayed in the [b]Monitor[/b] tab in the editor's [b]Debugger[/b] panel. By using the [method get_monitor] method of this class, you can access this data from your code.
 		You can add custom monitors using the [method add_custom_monitor] method. Custom monitors are available in [b]Monitor[/b] tab in the editor's [b]Debugger[/b] panel together with built-in monitors.
-		[b]Note:[/b] A few of these monitors are only available in debug mode and will always return 0 when used in a release build.
-		[b]Note:[/b] Many of these monitors are not updated in real-time, so there may be a short delay between changes.
+		[b]Note:[/b] Some of the built-in monitors are only available in debug mode and will always return [code]0[/code] when used in a project exported in release mode.
+		[b]Note:[/b] Some of the built-in monitors are not updated in real-time for performance reasons, so there may be a delay of up to 1 second between changes.
 		[b]Note:[/b] Custom monitors do not support negative values. Negative values are clamped to 0.
 	</description>
 	<tutorials>
@@ -19,7 +19,7 @@
 			<argument index="1" name="callable" type="Callable" />
 			<argument index="2" name="arguments" type="Array" default="[]" />
 			<description>
-				Adds a custom monitor with name same as id. You can specify the category of monitor using '/' in id. If there are more than one '/' then default category is used. Default category is "Custom".
+				Adds a custom monitor with the name [code]id[/code]. You can specify the category of the monitor using slash delimiters in [code]id[/code] (for example: [code]"Game/NumberOfNPCs"[/code]). If there is more than one slash delimiter, then the default category is used. The default category is [code]"Custom"[/code]. Prints an error if given [code]id[/code] is already present.
 				[codeblocks]
 				[gdscript]
 				func _ready():
@@ -29,11 +29,11 @@
 				    Performance.add_custom_monitor("MyCategory/MyMonitor", monitor_value)
 
 				    # Adds monitor with name "MyName" to category "Custom".
-				    # Note: "MyCategory/MyMonitor" and "MyMonitor" have same name but different ids so the code is valid.
+				    # Note: "MyCategory/MyMonitor" and "MyMonitor" have same name but different IDs, so the code is valid.
 				    Performance.add_custom_monitor("MyMonitor", monitor_value)
 
 				    # Adds monitor with name "MyName" to category "Custom".
-				    # Note: "MyMonitor" and "Custom/MyMonitor" have same name and same category but different ids so the code is valid.
+				    # Note: "MyMonitor" and "Custom/MyMonitor" have same name and same category but different IDs, so the code is valid.
 				    Performance.add_custom_monitor("Custom/MyMonitor", monitor_value)
 
 				    # Adds monitor with name "MyCategoryOne/MyCategoryTwo/MyMonitor" to category "Custom".
@@ -67,30 +67,28 @@
 				}
 				[/csharp]
 				[/codeblocks]
-				The debugger calls the callable to get the value of custom monitor. The callable must return a number.
+				The debugger calls the callable to get the value of custom monitor. The callable must return a zero or positive integer or floating-point number.
 				Callables are called with arguments supplied in argument array.
-				[b]Note:[/b] It prints an error if given id is already present.
 			</description>
 		</method>
 		<method name="get_custom_monitor">
 			<return type="Variant" />
 			<argument index="0" name="id" type="StringName" />
 			<description>
-				Returns the value of custom monitor with given id. The callable is called to get the value of custom monitor.
-				[b]Note:[/b] It prints an error if the given id is absent.
+				Returns the value of custom monitor with given [code]id[/code]. The callable is called to get the value of custom monitor. See also [method has_custom_monitor]. Prints an error if the given [code]id[/code] is absent.
 			</description>
 		</method>
 		<method name="get_custom_monitor_names">
 			<return type="Array" />
 			<description>
-				Returns the names of active custom monitors in an array.
+				Returns the names of active custom monitors in an [Array].
 			</description>
 		</method>
 		<method name="get_monitor" qualifiers="const">
 			<return type="float" />
 			<argument index="0" name="monitor" type="int" enum="Performance.Monitor" />
 			<description>
-				Returns the value of one of the available monitors. You should provide one of the [enum Monitor] constants as the argument, like this:
+				Returns the value of one of the available built-in monitors. You should provide one of the [enum Monitor] constants as the argument, like this:
 				[codeblocks]
 				[gdscript]
 				print(Performance.get_monitor(Performance.TIME_FPS)) # Prints the FPS to the console.
@@ -99,95 +97,99 @@
 				GD.Print(Performance.GetMonitor(Performance.Monitor.TimeFps)); // Prints the FPS to the console.
 				[/csharp]
 				[/codeblocks]
+				See [method get_custom_monitor] to query custom performance monitors' values.
 			</description>
 		</method>
 		<method name="get_monitor_modification_time">
 			<return type="int" />
 			<description>
-				Returns the last tick in which custom monitor was added/removed.
+				Returns the last tick in which custom monitor was added/removed (in microseconds since the engine started). This is set to [method Time.get_ticks_usec] when the monitor is updated.
 			</description>
 		</method>
 		<method name="has_custom_monitor">
 			<return type="bool" />
 			<argument index="0" name="id" type="StringName" />
 			<description>
-				Returns true if custom monitor with the given id is present otherwise returns false.
+				Returns [code]true[/code] if custom monitor with the given [code]id[/code] is present, [code]false[/code] otherwise.
 			</description>
 		</method>
 		<method name="remove_custom_monitor">
 			<return type="void" />
 			<argument index="0" name="id" type="StringName" />
 			<description>
-				Removes the custom monitor with given id.
-				[b]Note:[/b] It prints an error if the given id is already absent.
+				Removes the custom monitor with given [code]id[/code]. Prints an error if the given [code]id[/code] is already absent.
 			</description>
 		</method>
 	</methods>
 	<constants>
 		<constant name="TIME_FPS" value="0" enum="Monitor">
-			Number of frames per second.
+			The number of frames rendered in the last second. This metric is only updated once per second, even if queried more often. [i]Higher is better.[/i]
 		</constant>
 		<constant name="TIME_PROCESS" value="1" enum="Monitor">
-			Time it took to complete one frame, in seconds.
+			Time it took to complete one frame, in seconds. [i]Lower is better.[/i]
 		</constant>
 		<constant name="TIME_PHYSICS_PROCESS" value="2" enum="Monitor">
-			Time it took to complete one physics frame, in seconds.
+			Time it took to complete one physics frame, in seconds. [i]Lower is better.[/i]
 		</constant>
 		<constant name="MEMORY_STATIC" value="3" enum="Monitor">
-			Static memory currently used, in bytes. Not available in release builds.
+			Static memory currently used, in bytes. Not available in release builds. [i]Lower is better.[/i]
 		</constant>
 		<constant name="MEMORY_STATIC_MAX" value="4" enum="Monitor">
-			Available static memory. Not available in release builds.
+			Available static memory. Not available in release builds. [i]Lower is better.[/i]
 		</constant>
 		<constant name="MEMORY_MESSAGE_BUFFER_MAX" value="5" enum="Monitor">
-			Largest amount of memory the message queue buffer has used, in bytes. The message queue is used for deferred functions calls and notifications.
+			Largest amount of memory the message queue buffer has used, in bytes. The message queue is used for deferred functions calls and notifications. [i]Lower is better.[/i]
 		</constant>
 		<constant name="OBJECT_COUNT" value="6" enum="Monitor">
-			Number of objects currently instantiated (including nodes).
+			Number of objects currently instantiated (including nodes). [i]Lower is better.[/i]
 		</constant>
 		<constant name="OBJECT_RESOURCE_COUNT" value="7" enum="Monitor">
-			Number of resources currently used.
+			Number of resources currently used. [i]Lower is better.[/i]
 		</constant>
 		<constant name="OBJECT_NODE_COUNT" value="8" enum="Monitor">
-			Number of nodes currently instantiated in the scene tree. This also includes the root node.
+			Number of nodes currently instantiated in the scene tree. This also includes the root node. [i]Lower is better.[/i]
 		</constant>
 		<constant name="OBJECT_ORPHAN_NODE_COUNT" value="9" enum="Monitor">
-			Number of orphan nodes, i.e. nodes which are not parented to a node of the scene tree.
+			Number of orphan nodes, i.e. nodes which are not parented to a node of the scene tree. [i]Lower is better.[/i]
 		</constant>
 		<constant name="RENDER_TOTAL_OBJECTS_IN_FRAME" value="10" enum="Monitor">
+			The total number of objects in the last rendered frame. This metric doesn't include culled objects (either via hiding nodes, frustum culling or occlusion culling). [i]Lower is better.[/i]
 		</constant>
 		<constant name="RENDER_TOTAL_PRIMITIVES_IN_FRAME" value="11" enum="Monitor">
+			The total number of vertices or indices rendered in the last rendered frame. This metric doesn't include primitives from culled objects (either via hiding nodes, frustum culling or occlusion culling). Due to the depth prepass and shadow passes, the number of primitives is always higher than the actual number of vertices in the scene (typically double or triple the original vertex count). [i]Lower is better.[/i]
 		</constant>
 		<constant name="RENDER_TOTAL_DRAW_CALLS_IN_FRAME" value="12" enum="Monitor">
+			The total number of draw calls performed in the last rendered frame. This metric doesn't include culled objects (either via hiding nodes, frustum culling or occlusion culling), since they do not result in draw calls. [i]Lower is better.[/i]
 		</constant>
 		<constant name="RENDER_VIDEO_MEM_USED" value="13" enum="Monitor">
-			The amount of video memory used, i.e. texture and vertex memory combined.
+			The amount of video memory used (texture and vertex memory combined, in bytes). Since this metric also includes miscellaneous allocations, this value is always greater than the sum of [constant RENDER_TEXTURE_MEM_USED] and [constant RENDER_BUFFER_MEM_USED]. [i]Lower is better.[/i]
 		</constant>
 		<constant name="RENDER_TEXTURE_MEM_USED" value="14" enum="Monitor">
-			The amount of texture memory used.
+			The amount of texture memory used (in bytes). [i]Lower is better.[/i]
 		</constant>
 		<constant name="RENDER_BUFFER_MEM_USED" value="15" enum="Monitor">
+			The amount of render buffer memory used (in bytes). [i]Lower is better.[/i]
 		</constant>
 		<constant name="PHYSICS_2D_ACTIVE_OBJECTS" value="16" enum="Monitor">
-			Number of active [RigidDynamicBody2D] nodes in the game.
+			Number of active [RigidDynamicBody2D] nodes in the game. [i]Lower is better.[/i]
 		</constant>
 		<constant name="PHYSICS_2D_COLLISION_PAIRS" value="17" enum="Monitor">
-			Number of collision pairs in the 2D physics engine.
+			Number of collision pairs in the 2D physics engine. [i]Lower is better.[/i]
 		</constant>
 		<constant name="PHYSICS_2D_ISLAND_COUNT" value="18" enum="Monitor">
-			Number of islands in the 2D physics engine.
+			Number of islands in the 2D physics engine. [i]Lower is better.[/i]
 		</constant>
 		<constant name="PHYSICS_3D_ACTIVE_OBJECTS" value="19" enum="Monitor">
-			Number of active [RigidDynamicBody3D] and [VehicleBody3D] nodes in the game.
+			Number of active [RigidDynamicBody3D] and [VehicleBody3D] nodes in the game. [i]Lower is better.[/i]
 		</constant>
 		<constant name="PHYSICS_3D_COLLISION_PAIRS" value="20" enum="Monitor">
-			Number of collision pairs in the 3D physics engine.
+			Number of collision pairs in the 3D physics engine. [i]Lower is better.[/i]
 		</constant>
 		<constant name="PHYSICS_3D_ISLAND_COUNT" value="21" enum="Monitor">
-			Number of islands in the 3D physics engine.
+			Number of islands in the 3D physics engine. [i]Lower is better.[/i]
 		</constant>
 		<constant name="AUDIO_OUTPUT_LATENCY" value="22" enum="Monitor">
-			Output latency of the [AudioServer].
+			Output latency of the [AudioServer]. [i]Lower is better.[/i]
 		</constant>
 		<constant name="MONITOR_MAX" value="23" enum="Monitor">
 			Represents the size of the [enum Monitor] enum.