Merge pull request #40493 from Calinou/doc-editor-plugins-interfaces

Document several editor-related classes to 100% completion

8 files changed, 62 insertions, 19 deletions

diff --git a/doc/classes/EditorFileSystem.xml b/doc/classes/EditorFileSystem.xml
index 9bb51af2d0..5461dccd27 100644
--- a/doc/classes/EditorFileSystem.xml
+++ b/doc/classes/EditorFileSystem.xml
@@ -97,6 +97,7 @@
 			<argument index="0" name="resources" type="PackedStringArray">
 			</argument>
 			<description>
+				Emitted if at least one resource is reloaded when the filesystem is scanned.
 			</description>
 		</signal>
 		<signal name="sources_changed">
diff --git a/doc/classes/EditorFileSystemDirectory.xml b/doc/classes/EditorFileSystemDirectory.xml
index 096fe5df8f..b852ae1063 100644
--- a/doc/classes/EditorFileSystemDirectory.xml
+++ b/doc/classes/EditorFileSystemDirectory.xml
@@ -67,6 +67,7 @@
 			<argument index="0" name="idx" type="int">
 			</argument>
 			<description>
+				Returns the base class of the script class defined in the file at index [code]idx[/code]. If the file doesn't define a script class using the [code]class_name[/code] syntax, this will return an empty string.
 			</description>
 		</method>
 		<method name="get_file_script_class_name" qualifiers="const">
@@ -75,6 +76,7 @@
 			<argument index="0" name="idx" type="int">
 			</argument>
 			<description>
+				Returns the name of the script class defined in the file at index [code]idx[/code]. If the file doesn't define a script class using the [code]class_name[/code] syntax, this will return an empty string.
 			</description>
 		</method>
 		<method name="get_file_type" qualifiers="const">
diff --git a/doc/classes/EditorImportPlugin.xml b/doc/classes/EditorImportPlugin.xml
index 0aac59c727..ea2dfae9a5 100644
--- a/doc/classes/EditorImportPlugin.xml
+++ b/doc/classes/EditorImportPlugin.xml
@@ -83,6 +83,16 @@
 			<argument index="1" name="options" type="Dictionary">
 			</argument>
 			<description>
+				This method can be overridden to hide specific import options if conditions are met. This is mainly useful for hiding options that depend on others if one of them is disabled. For example:
+				[codeblock]
+				func get_option_visibility(option, options):
+				    # Only show the lossy quality setting if the compression mode is set to "Lossy".
+				    if option == "compress/lossy_quality" and options.has("compress/mode"):
+				        return int(options["compress/mode"]) == COMPRESS_LOSSY
+
+				    return true
+				[/codeblock]
+				Return [code]true[/code] to make all options always visible.
 			</description>
 		</method>
 		<method name="get_preset_count" qualifiers="virtual">
@@ -150,6 +160,8 @@
 			<argument index="4" name="gen_files" type="Array">
 			</argument>
 			<description>
+				Imports [code]source_file[/code] into [code]save_path[/code] with the import [code]options[/code] specified. The [code]platform_variants[/code] and [code]gen_files[/code] arrays will be modified by this function.
+				This method must be overridden to do the actual importing work. See this class' description for an example of overriding this method.
 			</description>
 		</method>
 	</methods>
diff --git a/doc/classes/EditorInspector.xml b/doc/classes/EditorInspector.xml
index 2f62fe9e40..5fbe427f67 100644
--- a/doc/classes/EditorInspector.xml
+++ b/doc/classes/EditorInspector.xml
@@ -14,41 +14,50 @@
 			<return type="void">
 			</return>
 			<description>
+				Refreshes the inspector.
+				[b]Note:[/b] To save on CPU resources, calling this method will do nothing if the time specified in [code]docks/property_editor/auto_refresh_interval[/code] editor setting hasn't passed yet since this method was last called. (By default, this interval is set to 0.3 seconds.)
 			</description>
 		</method>
 	</methods>
 	<members>
-		<member name="scroll_horizontal_enabled" type="bool" setter="set_enable_h_scroll" getter="is_h_scroll_enabled" override="true" default="false" />
+		<member name="scroll_horizontal_enabled" type="bool" setter="set_enable_h_scroll" getter="is_h_scroll_enabled" override="true" default="false">
+			If [code]true[/code], horizontal scrolling is enabled. An horizontal scroll bar will display at the bottom of the inspector.
+		</member>
 	</members>
 	<signals>
 		<signal name="object_id_selected">
 			<argument index="0" name="id" type="int">
 			</argument>
 			<description>
+				Emitted when the Edit button of an [Object] has been pressed in the inspector. This is mainly used in the remote scene tree inspector.
 			</description>
 		</signal>
 		<signal name="property_deleted">
 			<argument index="0" name="property" type="String">
 			</argument>
 			<description>
+				Emitted when a property is removed from the inspector.
 			</description>
 		</signal>
 		<signal name="property_edited">
 			<argument index="0" name="property" type="String">
 			</argument>
 			<description>
+				Emitted when a property is edited in the inspector.
 			</description>
 		</signal>
 		<signal name="property_keyed">
 			<argument index="0" name="property" type="String">
 			</argument>
 			<description>
+				Emitted when a property is keyed in the inspector. Properties can be keyed by clicking the "key" icon next to a property when the Animation panel is toggled.
 			</description>
 		</signal>
 		<signal name="property_selected">
 			<argument index="0" name="property" type="String">
 			</argument>
 			<description>
+				Emitted when a property is selected in the inspector.
 			</description>
 		</signal>
 		<signal name="property_toggled">
@@ -57,6 +66,8 @@
 			<argument index="1" name="checked" type="bool">
 			</argument>
 			<description>
+				Emitted when a boolean property is toggled in the inspector.
+				[b]Note:[/b] This signal is never emitted if the internal [code]autoclear[/code] property enabled. Since this property is always enabled in the editor inspector, this signal is never emitted by the editor itself.
 			</description>
 		</signal>
 		<signal name="resource_selected">
@@ -65,10 +76,12 @@
 			<argument index="1" name="prop" type="String">
 			</argument>
 			<description>
+				Emitted when a resource is selected in the inspector.
 			</description>
 		</signal>
 		<signal name="restart_requested">
 			<description>
+				Emitted when a property that requires a restart to be applied is edited in the inspector. This is only used in the Project Settings and Editor Settings.
 			</description>
 		</signal>
 	</signals>
diff --git a/doc/classes/EditorInterface.xml b/doc/classes/EditorInterface.xml
index 1d877e632e..8b2b9c9350 100644
--- a/doc/classes/EditorInterface.xml
+++ b/doc/classes/EditorInterface.xml
@@ -23,13 +23,14 @@
 			<return type="Control">
 			</return>
 			<description>
-				Returns the main container of Godot editor's window. You can use it, for example, to retrieve the size of the container and place your controls accordingly.
+				Returns the main container of Godot editor's window. For example, you can use it to retrieve the size of the container and place your controls accordingly.
 			</description>
 		</method>
 		<method name="get_current_path" qualifiers="const">
 			<return type="String">
 			</return>
 			<description>
+				Returns the current path being viewed in the [FileSystemDock].
 			</description>
 		</method>
 		<method name="get_edited_scene_root">
@@ -43,26 +44,29 @@
 			<return type="EditorSettings">
 			</return>
 			<description>
-				Returns the [EditorSettings].
+				Returns the editor's [EditorSettings] instance.
 			</description>
 		</method>
 		<method name="get_editor_viewport">
 			<return type="Control">
 			</return>
 			<description>
-				Returns the editor [Viewport].
+				Returns the editor's [Viewport] instance.
+				[b]Note:[/b] This returns the main editor viewport containing the whole editor, not the 2D or 3D viewports specifically.
 			</description>
 		</method>
 		<method name="get_file_system_dock">
 			<return type="FileSystemDock">
 			</return>
 			<description>
+				Returns the editor's [FileSystemDock] instance.
 			</description>
 		</method>
 		<method name="get_inspector" qualifiers="const">
 			<return type="EditorInspector">
 			</return>
 			<description>
+				Returns the editor's [EditorInspector] instance.
 			</description>
 		</method>
 		<method name="get_open_scenes" qualifiers="const">
@@ -83,34 +87,35 @@
 			<return type="EditorFileSystem">
 			</return>
 			<description>
-				Returns the [EditorFileSystem].
+				Returns the editor's [EditorFileSystem] instance.
 			</description>
 		</method>
 		<method name="get_resource_previewer">
 			<return type="EditorResourcePreview">
 			</return>
 			<description>
-				Returns the [EditorResourcePreview].
+				Returns the editor's [EditorResourcePreview] instance.
 			</description>
 		</method>
 		<method name="get_script_editor">
 			<return type="ScriptEditor">
 			</return>
 			<description>
-				Returns the [ScriptEditor].
+				Returns the editor's [ScriptEditor] instance.
 			</description>
 		</method>
 		<method name="get_selected_path" qualifiers="const">
 			<return type="String">
 			</return>
 			<description>
+				Returns the path of the directory currently selected in the [FileSystemDock]. If a file is selected, its base directory will be returned using [method String.get_base_dir] instead.
 			</description>
 		</method>
 		<method name="get_selection">
 			<return type="EditorSelection">
 			</return>
 			<description>
-				Returns the [EditorSelection].
+				Returns the editor's [EditorSelection] instance.
 			</description>
 		</method>
 		<method name="inspect_object">
@@ -121,14 +126,14 @@
 			<argument index="1" name="for_property" type="String" default="&quot;&quot;">
 			</argument>
 			<description>
-				Shows the given property on the given [code]object[/code] in the Editor's Inspector dock.
+				Shows the given property on the given [code]object[/code] in the editor's Inspector dock.
 			</description>
 		</method>
 		<method name="is_playing_scene" qualifiers="const">
 			<return type="bool">
 			</return>
 			<description>
-				Returns [code]true[/code], if a scene is currently being played; [code]false[/code] otherwise. Paused scenes are considered as being played.
+				Returns [code]true[/code] if a scene is currently being played, [code]false[/code] otherwise. Paused scenes are considered as being played.
 			</description>
 		</method>
 		<method name="is_plugin_enabled" qualifiers="const">
@@ -137,7 +142,7 @@
 			<argument index="0" name="plugin" type="String">
 			</argument>
 			<description>
-				Returns the enabled status of a plugin. The plugin name is the same as its directory name.
+				Returns [code]true[/code] if the specified [code]plugin[/code] is enabled. The plugin name is the same as its directory name.
 			</description>
 		</method>
 		<method name="make_mesh_previews">
@@ -225,6 +230,7 @@
 			<argument index="0" name="name" type="String">
 			</argument>
 			<description>
+				Sets the editor's current main screen to the one specified in [code]name[/code]. [code]name[/code] must match the text of the tab in question exactly ([code]2D[/code], [code]3D[/code], [code]Script[/code], [code]AssetLib[/code]).
 			</description>
 		</method>
 		<method name="set_plugin_enabled">
diff --git a/doc/classes/EditorNode3DGizmo.xml b/doc/classes/EditorNode3DGizmo.xml
index 6d695ddeea..45541b9263 100644
--- a/doc/classes/EditorNode3DGizmo.xml
+++ b/doc/classes/EditorNode3DGizmo.xml
@@ -15,6 +15,7 @@
 			<argument index="0" name="segments" type="PackedVector3Array">
 			</argument>
 			<description>
+				Adds the specified [code]segments[/code] to the gizmo's collision shape for picking. Call this function during [method redraw].
 			</description>
 		</method>
 		<method name="add_collision_triangles">
@@ -69,6 +70,7 @@
 			<argument index="3" name="material" type="Material" default="null">
 			</argument>
 			<description>
+				Adds a mesh to the gizmo with the specified [code]billboard[/code] state, [code]skeleton[/code] and [code]material[/code]. If [code]billboard[/code] is [code]true[/code], the mesh will rotate to always face the camera. Call this function during [method redraw].
 			</description>
 		</method>
 		<method name="add_unscaled_billboard">
@@ -88,6 +90,7 @@
 			<return type="void">
 			</return>
 			<description>
+				Removes everything in the gizmo including meshes, collisions and handles.
 			</description>
 		</method>
 		<method name="commit_handle" qualifiers="virtual">
@@ -143,14 +146,14 @@
 			<argument index="0" name="index" type="int">
 			</argument>
 			<description>
-				Gets whether a handle is highlighted or not.
+				Returns [code]true[/code] if the handle at index [code]index[/code] is highlighted by being hovered with the mouse.
 			</description>
 		</method>
 		<method name="redraw" qualifiers="virtual">
 			<return type="void">
 			</return>
 			<description>
-				This function is called when the Node3D this gizmo refers to changes (the [method Node3D.update_gizmo] is called).
+				This function is called when the [Node3D] this gizmo refers to changes (the [method Node3D.update_gizmo] is called).
 			</description>
 		</method>
 		<method name="set_handle" qualifiers="virtual">
@@ -173,6 +176,7 @@
 			<argument index="0" name="hidden" type="bool">
 			</argument>
 			<description>
+				Sets the gizmo's hidden state. If [code]true[/code], the gizmo will be hidden. If [code]false[/code], it will be shown.
 			</description>
 		</method>
 		<method name="set_spatial_node">
@@ -181,6 +185,7 @@
 			<argument index="0" name="node" type="Node">
 			</argument>
 			<description>
+				Sets the reference [Node3D] node for the gizmo. [code]node[/code] must inherit from [Node3D].
 			</description>
 		</method>
 	</methods>
diff --git a/doc/classes/EditorNode3DGizmoPlugin.xml b/doc/classes/EditorNode3DGizmoPlugin.xml
index ca75b47fbf..b81281b5b6 100644
--- a/doc/classes/EditorNode3DGizmoPlugin.xml
+++ b/doc/classes/EditorNode3DGizmoPlugin.xml
@@ -139,6 +139,8 @@
 			<return type="String">
 			</return>
 			<description>
+				Override this method to set the gizmo's priority. Higher values correspond to higher priority. If a gizmo with higher priority conflicts with another gizmo, only the gizmo with higher priority will be used.
+				All built-in editor gizmos return a priority of [code]-1[/code]. If not overridden, this method will return [code]0[/code], which means custom gizmos will automatically override built-in gizmos.
 			</description>
 		</method>
 		<method name="has_gizmo" qualifiers="virtual">
diff --git a/doc/classes/EditorProperty.xml b/doc/classes/EditorProperty.xml
index 4da3b58b94..f568263ff8 100644
--- a/doc/classes/EditorProperty.xml
+++ b/doc/classes/EditorProperty.xml
@@ -73,24 +73,25 @@
 	</methods>
 	<members>
 		<member name="checkable" type="bool" setter="set_checkable" getter="is_checkable" default="false">
-			Used by the inspector, set when property is checkable.
+			Used by the inspector, set to [code]true[/code] when the property is checkable.
 		</member>
 		<member name="checked" type="bool" setter="set_checked" getter="is_checked" default="false">
-			Used by the inspector, when the property is checked.
+			Used by the inspector, set to [code]true[/code] when the property is checked.
 		</member>
 		<member name="deletable" type="bool" setter="set_deletable" getter="is_deletable" default="false">
+			Used by the inspector, set to [code]true[/code] when the property can be deleted by the user.
 		</member>
 		<member name="draw_red" type="bool" setter="set_draw_red" getter="is_draw_red" default="false">
-			Used by the inspector, when the property must draw with error color.
+			Used by the inspector, set to [code]true[/code] when the property must draw with error color. This is used for editable children's properties.
 		</member>
 		<member name="keying" type="bool" setter="set_keying" getter="is_keying" default="false">
-			Used by the inspector, when the property can add keys for animation.
+			Used by the inspector, set to [code]true[/code] when the property can add keys for animation.
 		</member>
 		<member name="label" type="String" setter="set_label" getter="get_label" default="&quot;&quot;">
-			Sets this property to change the label (if you want to show one).
+			Set this property to change the label (if you want to show one).
 		</member>
 		<member name="read_only" type="bool" setter="set_read_only" getter="is_read_only" default="false">
-			Used by the inspector, when the property is read-only.
+			Used by the inspector, set to [code]true[/code] when the property is read-only.
 		</member>
 	</members>
 	<signals>
@@ -134,6 +135,7 @@
 			<argument index="0" name="property" type="StringName">
 			</argument>
 			<description>
+				Emitted when a property was deleted. Used internally.
 			</description>
 		</signal>
 		<signal name="property_keyed">