Merge pull request #57518 from pycbouh/docs-theme-refinement

1 files changed, 112 insertions, 88 deletions

diff --git a/doc/classes/Theme.xml b/doc/classes/Theme.xml
index d1a48fda55..b1367be263 100644
--- a/doc/classes/Theme.xml
+++ b/doc/classes/Theme.xml
@@ -1,20 +1,22 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="Theme" inherits="Resource" version="4.0">
 	<brief_description>
-		Theme for controls.
+		Theme resource for styling/skinning [Control]s and [Window]s.
 	</brief_description>
 	<description>
-		A theme for skinning controls. Controls can be skinned individually, but for complex applications, it's more practical to just create a global theme that defines everything. This theme can be applied to any [Control]; the Control and its children will automatically use it.
-		Theme resources can alternatively be loaded by writing them in a [code].theme[/code] file, see the documentation for more information.
+		A theme resource is used for styling/skinning [Control] and [Window] nodes. While individual controls can be styled using their local theme overrides (see [method Control.add_theme_color_override]), theme resources allow you to store and apply the same settings between all controls sharing the same type (e.g. style all [Button]s the same). One theme resource can be used for the entire project, but you can also set a separate theme resource to a branch of control nodes. A theme resources assigned to a control node applies to the control itself, as well as all of its direct and indirect children (as long as a chain of controls is uninterrupted).
+		Use [member ProjectSettings.gui/theme/custom] to set up a project-scope theme that will be available to every control in your project.
+		Use [member Control.theme] of any control node to set up a theme that will be available to that control and all of its direct and indirect children.
 	</description>
 	<tutorials>
 		<link title="GUI skinning">$DOCS_URL/tutorials/ui/gui_skinning.html</link>
+		<link title="Using the theme editor">$DOCS_URL/tutorials/ui/gui_using_theme_editor.html</link>
 	</tutorials>
 	<methods>
 		<method name="clear">
 			<return type="void" />
 			<description>
-				Clears all values on the theme.
+				Removes all the theme properties defined on the theme resource.
 			</description>
 		</method>
 		<method name="clear_color">
@@ -22,7 +24,8 @@
 			<argument index="0" name="name" type="StringName" />
 			<argument index="1" name="theme_type" type="StringName" />
 			<description>
-				Clears the [Color] at [code]name[/code] if the theme has [code]theme_type[/code].
+				Removes the [Color] property defined by [code]name[/code] and [code]theme_type[/code], if it exists.
+				Fails if it doesn't exist. Use [method has_color] to check for existence.
 			</description>
 		</method>
 		<method name="clear_constant">
@@ -30,7 +33,8 @@
 			<argument index="0" name="name" type="StringName" />
 			<argument index="1" name="theme_type" type="StringName" />
 			<description>
-				Clears the constant at [code]name[/code] if the theme has [code]theme_type[/code].
+				Removes the constant property defined by [code]name[/code] and [code]theme_type[/code], if it exists.
+				Fails if it doesn't exist. Use [method has_constant] to check for existence.
 			</description>
 		</method>
 		<method name="clear_font">
@@ -38,7 +42,8 @@
 			<argument index="0" name="name" type="StringName" />
 			<argument index="1" name="theme_type" type="StringName" />
 			<description>
-				Clears the [Font] at [code]name[/code] if the theme has [code]theme_type[/code].
+				Removes the [Font] property defined by [code]name[/code] and [code]theme_type[/code], if it exists.
+				Fails if it doesn't exist. Use [method has_font] to check for existence.
 			</description>
 		</method>
 		<method name="clear_font_size">
@@ -46,7 +51,8 @@
 			<argument index="0" name="name" type="StringName" />
 			<argument index="1" name="theme_type" type="StringName" />
 			<description>
-				Clears the font size [code]name[/code] if the theme has [code]theme_type[/code].
+				Removes the font size property defined by [code]name[/code] and [code]theme_type[/code], if it exists.
+				Fails if it doesn't exist. Use [method has_font_size] to check for existence.
 			</description>
 		</method>
 		<method name="clear_icon">
@@ -54,7 +60,8 @@
 			<argument index="0" name="name" type="StringName" />
 			<argument index="1" name="theme_type" type="StringName" />
 			<description>
-				Clears the icon at [code]name[/code] if the theme has [code]theme_type[/code].
+				Removes the icon property defined by [code]name[/code] and [code]theme_type[/code], if it exists.
+				Fails if it doesn't exist. Use [method has_icon] to check for existence.
 			</description>
 		</method>
 		<method name="clear_stylebox">
@@ -62,7 +69,8 @@
 			<argument index="0" name="name" type="StringName" />
 			<argument index="1" name="theme_type" type="StringName" />
 			<description>
-				Clears [StyleBox] at [code]name[/code] if the theme has [code]theme_type[/code].
+				Removes the [StyleBox] property defined by [code]name[/code] and [code]theme_type[/code], if it exists.
+				Fails if it doesn't exist. Use [method has_stylebox] to check for existence.
 			</description>
 		</method>
 		<method name="clear_theme_item">
@@ -71,14 +79,16 @@
 			<argument index="1" name="name" type="StringName" />
 			<argument index="2" name="theme_type" type="StringName" />
 			<description>
-				Clears the theme item of [code]data_type[/code] at [code]name[/code] if the theme has [code]theme_type[/code].
+				Removes the theme property of [code]data_type[/code] defined by [code]name[/code] and [code]theme_type[/code], if it exists.
+				Fails if it doesn't exist. Use [method has_theme_item] to check for existence.
+				[b]Note:[/b] This method is analogous to calling the corresponding data type specific method, but can be used for more generalized logic.
 			</description>
 		</method>
 		<method name="clear_type_variation">
 			<return type="void" />
 			<argument index="0" name="theme_type" type="StringName" />
 			<description>
-				Unmarks [code]theme_type[/code] as being a variation of any other type.
+				Unmarks [code]theme_type[/code] as being a variation of another theme type. See [method set_type_variation].
 			</description>
 		</method>
 		<method name="get_color" qualifiers="const">
@@ -86,20 +96,21 @@
 			<argument index="0" name="name" type="StringName" />
 			<argument index="1" name="theme_type" type="StringName" />
 			<description>
-				Returns the [Color] at [code]name[/code] if the theme has [code]theme_type[/code].
+				Returns the [Color] property defined by [code]name[/code] and [code]theme_type[/code], if it exists.
+				Returns the default color value if the property doesn't exist. Use [method has_color] to check for existence.
 			</description>
 		</method>
 		<method name="get_color_list" qualifiers="const">
 			<return type="PackedStringArray" />
 			<argument index="0" name="theme_type" type="String" />
 			<description>
-				Returns all the [Color]s as a [PackedStringArray] filled with each [Color]'s name, for use in [method get_color], if the theme has [code]theme_type[/code].
+				Returns a list of names for [Color] properties defined with [code]theme_type[/code]. Use [method get_color_type_list] to get a list of possible theme type names.
 			</description>
 		</method>
 		<method name="get_color_type_list" qualifiers="const">
 			<return type="PackedStringArray" />
 			<description>
-				Returns all the [Color] types as a [PackedStringArray] filled with unique type names, for use in [method get_color] and/or [method get_color_list].
+				Returns a list of all unique theme type names for [Color] properties. Use [method get_type_list] to get a list of all unique theme types.
 			</description>
 		</method>
 		<method name="get_constant" qualifiers="const">
@@ -107,20 +118,21 @@
 			<argument index="0" name="name" type="StringName" />
 			<argument index="1" name="theme_type" type="StringName" />
 			<description>
-				Returns the constant at [code]name[/code] if the theme has [code]theme_type[/code].
+				Returns the constant property defined by [code]name[/code] and [code]theme_type[/code], if it exists.
+				Returns [code]0[/code] if the property doesn't exist. Use [method has_constant] to check for existence.
 			</description>
 		</method>
 		<method name="get_constant_list" qualifiers="const">
 			<return type="PackedStringArray" />
 			<argument index="0" name="theme_type" type="String" />
 			<description>
-				Returns all the constants as a [PackedStringArray] filled with each constant's name, for use in [method get_constant], if the theme has [code]theme_type[/code].
+				Returns a list of names for constant properties defined with [code]theme_type[/code]. Use [method get_constant_type_list] to get a list of possible theme type names.
 			</description>
 		</method>
 		<method name="get_constant_type_list" qualifiers="const">
 			<return type="PackedStringArray" />
 			<description>
-				Returns all the constant types as a [PackedStringArray] filled with unique type names, for use in [method get_constant] and/or [method get_constant_list].
+				Returns a list of all unique theme type names for constant properties. Use [method get_type_list] to get a list of all unique theme types.
 			</description>
 		</method>
 		<method name="get_font" qualifiers="const">
@@ -128,14 +140,16 @@
 			<argument index="0" name="name" type="StringName" />
 			<argument index="1" name="theme_type" type="StringName" />
 			<description>
-				Returns the [Font] at [code]name[/code] if the theme has [code]theme_type[/code].
+				Returns the [Font] property defined by [code]name[/code] and [code]theme_type[/code], if it exists.
+				Returns the default theme font if the property doesn't exist and the default theme font is set up (see [member default_font]). Use [method has_font] to check for existence of the property and [method has_default_font] to check for existence of the default theme font.
+				Returns the engine fallback font value, if neither exist.
 			</description>
 		</method>
 		<method name="get_font_list" qualifiers="const">
 			<return type="PackedStringArray" />
 			<argument index="0" name="theme_type" type="String" />
 			<description>
-				Returns all the [Font]s as a [PackedStringArray] filled with each [Font]'s name, for use in [method get_font], if the theme has [code]theme_type[/code].
+				Returns a list of names for [Font] properties defined with [code]theme_type[/code]. Use [method get_font_type_list] to get a list of possible theme type names.
 			</description>
 		</method>
 		<method name="get_font_size" qualifiers="const">
@@ -143,26 +157,28 @@
 			<argument index="0" name="name" type="StringName" />
 			<argument index="1" name="theme_type" type="StringName" />
 			<description>
-				Returns the font size at [code]name[/code] if the theme has [code]theme_type[/code].
+				Returns the font size property defined by [code]name[/code] and [code]theme_type[/code], if it exists.
+				Returns the default theme font size if the property doesn't exist and the default theme font size is set up (see [member default_font_size]). Use [method has_font_size] to check for existence of the property and [method has_default_font_size] to check for existence of the default theme font.
+				Returns the engine fallback font size value, if neither exist.
 			</description>
 		</method>
 		<method name="get_font_size_list" qualifiers="const">
 			<return type="PackedStringArray" />
 			<argument index="0" name="theme_type" type="String" />
 			<description>
-				Returns all the font sizes as a [PackedStringArray] filled with each font size name, for use in [method get_font_size], if the theme has [code]theme_type[/code].
+				Returns a list of names for font size properties defined with [code]theme_type[/code]. Use [method get_font_size_type_list] to get a list of possible theme type names.
 			</description>
 		</method>
 		<method name="get_font_size_type_list" qualifiers="const">
 			<return type="PackedStringArray" />
 			<description>
-				Returns all the font size types as a [PackedStringArray] filled with unique type names, for use in [method get_font_size] and/or [method get_font_size_list].
+				Returns a list of all unique theme type names for font size properties. Use [method get_type_list] to get a list of all unique theme types.
 			</description>
 		</method>
 		<method name="get_font_type_list" qualifiers="const">
 			<return type="PackedStringArray" />
 			<description>
-				Returns all the [Font] types as a [PackedStringArray] filled with unique type names, for use in [method get_font] and/or [method get_font_list].
+				Returns a list of all unique theme type names for [Font] properties. Use [method get_type_list] to get a list of all unique theme types.
 			</description>
 		</method>
 		<method name="get_icon" qualifiers="const">
@@ -170,20 +186,21 @@
 			<argument index="0" name="name" type="StringName" />
 			<argument index="1" name="theme_type" type="StringName" />
 			<description>
-				Returns the icon [Texture2D] at [code]name[/code] if the theme has [code]theme_type[/code].
+				Returns the icon property defined by [code]name[/code] and [code]theme_type[/code], if it exists.
+				Returns the engine fallback icon value if the property doesn't exist. Use [method has_icon] to check for existence.
 			</description>
 		</method>
 		<method name="get_icon_list" qualifiers="const">
 			<return type="PackedStringArray" />
 			<argument index="0" name="theme_type" type="String" />
 			<description>
-				Returns all the icons as a [PackedStringArray] filled with each [Texture2D]'s name, for use in [method get_icon], if the theme has [code]theme_type[/code].
+				Returns a list of names for icon properties defined with [code]theme_type[/code]. Use [method get_icon_type_list] to get a list of possible theme type names.
 			</description>
 		</method>
 		<method name="get_icon_type_list" qualifiers="const">
 			<return type="PackedStringArray" />
 			<description>
-				Returns all the icon types as a [PackedStringArray] filled with unique type names, for use in [method get_icon] and/or [method get_icon_list].
+				Returns a list of all unique theme type names for icon properties. Use [method get_type_list] to get a list of all unique theme types.
 			</description>
 		</method>
 		<method name="get_stylebox" qualifiers="const">
@@ -191,22 +208,21 @@
 			<argument index="0" name="name" type="StringName" />
 			<argument index="1" name="theme_type" type="StringName" />
 			<description>
-				Returns the [StyleBox] at [code]name[/code] if the theme has [code]theme_type[/code].
-				Valid [code]name[/code]s may be found using [method get_stylebox_list]. Valid [code]theme_type[/code]s may be found using [method get_stylebox_type_list].
+				Returns the [StyleBox] property defined by [code]name[/code] and [code]theme_type[/code], if it exists.
+				Returns the engine fallback stylebox value if the property doesn't exist. Use [method has_stylebox] to check for existence.
 			</description>
 		</method>
 		<method name="get_stylebox_list" qualifiers="const">
 			<return type="PackedStringArray" />
 			<argument index="0" name="theme_type" type="String" />
 			<description>
-				Returns all the [StyleBox]s as a [PackedStringArray] filled with each [StyleBox]'s name, for use in [method get_stylebox], if the theme has [code]theme_type[/code].
-				Valid [code]theme_type[/code]s may be found using [method get_stylebox_type_list].
+				Returns a list of names for [StyleBox] properties defined with [code]theme_type[/code]. Use [method get_stylebox_type_list] to get a list of possible theme type names.
 			</description>
 		</method>
 		<method name="get_stylebox_type_list" qualifiers="const">
 			<return type="PackedStringArray" />
 			<description>
-				Returns all the [StyleBox] types as a [PackedStringArray] filled with unique type names, for use in [method get_stylebox] and/or [method get_stylebox_list].
+				Returns a list of all unique theme type names for [StyleBox] properties. Use [method get_type_list] to get a list of all unique theme types.
 			</description>
 		</method>
 		<method name="get_theme_item" qualifiers="const">
@@ -215,8 +231,9 @@
 			<argument index="1" name="name" type="StringName" />
 			<argument index="2" name="theme_type" type="StringName" />
 			<description>
-				Returns the theme item of [code]data_type[/code] at [code]name[/code] if the theme has [code]theme_type[/code].
-				Valid [code]name[/code]s may be found using [method get_theme_item_list] or a data type specific method. Valid [code]theme_type[/code]s may be found using [method get_theme_item_type_list] or a data type specific method.
+				Returns the theme property of [code]data_type[/code] defined by [code]name[/code] and [code]theme_type[/code], if it exists.
+				Returns the engine fallback icon value if the property doesn't exist. Use [method has_theme_item] to check for existence.
+				[b]Note:[/b] This method is analogous to calling the corresponding data type specific method, but can be used for more generalized logic.
 			</description>
 		</method>
 		<method name="get_theme_item_list" qualifiers="const">
@@ -224,35 +241,36 @@
 			<argument index="0" name="data_type" type="int" enum="Theme.DataType" />
 			<argument index="1" name="theme_type" type="String" />
 			<description>
-				Returns all the theme items of [code]data_type[/code] as a [PackedStringArray] filled with each theme items's name, for use in [method get_theme_item] or a data type specific method, if the theme has [code]theme_type[/code].
-				Valid [code]theme_type[/code]s may be found using [method get_theme_item_type_list] or a data type specific method.
+				Returns a list of names for properties of [code]data_type[/code] defined with [code]theme_type[/code]. Use [method get_theme_item_type_list] to get a list of possible theme type names.
+				[b]Note:[/b] This method is analogous to calling the corresponding data type specific method, but can be used for more generalized logic.
 			</description>
 		</method>
 		<method name="get_theme_item_type_list" qualifiers="const">
 			<return type="PackedStringArray" />
 			<argument index="0" name="data_type" type="int" enum="Theme.DataType" />
 			<description>
-				Returns all the theme items of [code]data_type[/code] types as a [PackedStringArray] filled with unique type names, for use in [method get_theme_item], [method get_theme_item_list] or data type specific methods.
+				Returns a list of all unique theme type names for [code]data_type[/code] properties. Use [method get_type_list] to get a list of all unique theme types.
+				[b]Note:[/b] This method is analogous to calling the corresponding data type specific method, but can be used for more generalized logic.
 			</description>
 		</method>
 		<method name="get_type_list" qualifiers="const">
 			<return type="PackedStringArray" />
 			<description>
-				Returns all the theme types as a [PackedStringArray] filled with unique type names, for use in other [code]get_*[/code] functions of this theme.
+				Returns a list of all unique theme type names. Use the appropriate [code]get_*_type_list[/code] method to get a list of unique theme types for a single data type.
 			</description>
 		</method>
 		<method name="get_type_variation_base" qualifiers="const">
 			<return type="StringName" />
 			<argument index="0" name="theme_type" type="StringName" />
 			<description>
-				Returns the base theme type if [code]theme_type[/code] is a valid variation type. Returns an empty string otherwise.
+				Returns the name of the base theme type if [code]theme_type[/code] is a valid variation type. Returns an empty string otherwise.
 			</description>
 		</method>
 		<method name="get_type_variation_list" qualifiers="const">
 			<return type="PackedStringArray" />
 			<argument index="0" name="base_type" type="StringName" />
 			<description>
-				Returns a list of all variation for the given [code]base_type[/code].
+				Returns a list of all type variations for the given [code]base_type[/code].
 			</description>
 		</method>
 		<method name="has_color" qualifiers="const">
@@ -260,8 +278,8 @@
 			<argument index="0" name="name" type="StringName" />
 			<argument index="1" name="theme_type" type="StringName" />
 			<description>
-				Returns [code]true[/code] if [Color] with [code]name[/code] is in [code]theme_type[/code].
-				Returns [code]false[/code] if the theme does not have [code]theme_type[/code].
+				Returns [code]true[/code] if the [Color] property defined by [code]name[/code] and [code]theme_type[/code] exists.
+				Returns [code]false[/code] if it doesn't exist. Use [method set_color] to define it.
 			</description>
 		</method>
 		<method name="has_constant" qualifiers="const">
@@ -269,26 +287,29 @@
 			<argument index="0" name="name" type="StringName" />
 			<argument index="1" name="theme_type" type="StringName" />
 			<description>
-				Returns [code]true[/code] if constant with [code]name[/code] is in [code]theme_type[/code].
-				Returns [code]false[/code] if the theme does not have [code]theme_type[/code].
+				Returns [code]true[/code] if the constant property defined by [code]name[/code] and [code]theme_type[/code] exists.
+				Returns [code]false[/code] if it doesn't exist. Use [method set_constant] to define it.
 			</description>
 		</method>
 		<method name="has_default_base_scale" qualifiers="const">
 			<return type="bool" />
 			<description>
-				Returns [code]true[/code] if this theme has a valid [member default_base_scale] value.
+				Returns [code]true[/code] if [member default_base_scale] has a valid value.
+				Returns [code]false[/code] if it doesn't. The value must be greater than [code]0.0[/code] to be considered valid.
 			</description>
 		</method>
 		<method name="has_default_font" qualifiers="const">
 			<return type="bool" />
 			<description>
-				Returns [code]true[/code] if this theme has a valid [member default_font] value.
+				Returns [code]true[/code] if [member default_font] has a valid value.
+				Returns [code]false[/code] if it doesn't.
 			</description>
 		</method>
 		<method name="has_default_font_size" qualifiers="const">
 			<return type="bool" />
 			<description>
-				Returns [code]true[/code] if this theme has a valid [member default_font_size] value.
+				Returns [code]true[/code] if [member default_font_size] has a valid value.
+				Returns [code]false[/code] if it doesn't. The value must be greater than [code]0[/code] to be considered valid.
 			</description>
 		</method>
 		<method name="has_font" qualifiers="const">
@@ -296,8 +317,8 @@
 			<argument index="0" name="name" type="StringName" />
 			<argument index="1" name="theme_type" type="StringName" />
 			<description>
-				Returns [code]true[/code] if [Font] with [code]name[/code] is in [code]theme_type[/code].
-				Returns [code]false[/code] if the theme does not have [code]theme_type[/code].
+				Returns [code]true[/code] if the [Font] property defined by [code]name[/code] and [code]theme_type[/code] exists, or if the default theme font is set up (see [method has_default_font]).
+				Returns [code]false[/code] if neither exist. Use [method set_font] to define the property.
 			</description>
 		</method>
 		<method name="has_font_size" qualifiers="const">
@@ -305,8 +326,8 @@
 			<argument index="0" name="name" type="StringName" />
 			<argument index="1" name="theme_type" type="StringName" />
 			<description>
-				Returns [code]true[/code] if font size with [code]name[/code] is in [code]theme_type[/code].
-				Returns [code]false[/code] if the theme does not have [code]theme_type[/code].
+				Returns [code]true[/code] if the font size property defined by [code]name[/code] and [code]theme_type[/code] exists, or if the default theme font size is set up (see [method has_default_font_size]).
+				Returns [code]false[/code] if neither exist. Use [method set_font_size] to define the property.
 			</description>
 		</method>
 		<method name="has_icon" qualifiers="const">
@@ -314,8 +335,8 @@
 			<argument index="0" name="name" type="StringName" />
 			<argument index="1" name="theme_type" type="StringName" />
 			<description>
-				Returns [code]true[/code] if icon [Texture2D] with [code]name[/code] is in [code]theme_type[/code].
-				Returns [code]false[/code] if the theme does not have [code]theme_type[/code].
+				Returns [code]true[/code] if the icon property defined by [code]name[/code] and [code]theme_type[/code] exists.
+				Returns [code]false[/code] if it doesn't exist. Use [method set_icon] to define it.
 			</description>
 		</method>
 		<method name="has_stylebox" qualifiers="const">
@@ -323,8 +344,8 @@
 			<argument index="0" name="name" type="StringName" />
 			<argument index="1" name="theme_type" type="StringName" />
 			<description>
-				Returns [code]true[/code] if [StyleBox] with [code]name[/code] is in [code]theme_type[/code].
-				Returns [code]false[/code] if the theme does not have [code]theme_type[/code].
+				Returns [code]true[/code] if the [StyleBox] property defined by [code]name[/code] and [code]theme_type[/code] exists.
+				Returns [code]false[/code] if it doesn't exist. Use [method set_stylebox] to define it.
 			</description>
 		</method>
 		<method name="has_theme_item" qualifiers="const">
@@ -333,8 +354,9 @@
 			<argument index="1" name="name" type="StringName" />
 			<argument index="2" name="theme_type" type="StringName" />
 			<description>
-				Returns [code]true[/code] if a theme item of [code]data_type[/code] with [code]name[/code] is in [code]theme_type[/code].
-				Returns [code]false[/code] if the theme does not have [code]theme_type[/code].
+				Returns [code]true[/code] if the theme property of [code]data_type[/code] defined by [code]name[/code] and [code]theme_type[/code] exists.
+				Returns [code]false[/code] if it doesn't exist. Use [method set_theme_item] to define it.
+				[b]Note:[/b] This method is analogous to calling the corresponding data type specific method, but can be used for more generalized logic.
 			</description>
 		</method>
 		<method name="is_type_variation" qualifiers="const">
@@ -342,14 +364,14 @@
 			<argument index="0" name="theme_type" type="StringName" />
 			<argument index="1" name="base_type" type="StringName" />
 			<description>
-				Returns [code]true[/code] if [code]theme_type[/code] is marked as a variation of [code]base_type[/code] in this theme.
+				Returns [code]true[/code] if [code]theme_type[/code] is marked as a variation of [code]base_type[/code].
 			</description>
 		</method>
 		<method name="merge_with">
 			<return type="void" />
 			<argument index="0" name="other" type="Theme" />
 			<description>
-				Adds missing and overrides existing definitions with values from the [code]other[/code] [Theme].
+				Adds missing and overrides existing definitions with values from the [code]other[/code] theme resource.
 				[b]Note:[/b] This modifies the current theme. If you want to merge two themes together without modifying either one, create a new empty theme and merge the other two into it one after another.
 			</description>
 		</method>
@@ -359,7 +381,8 @@
 			<argument index="1" name="name" type="StringName" />
 			<argument index="2" name="theme_type" type="StringName" />
 			<description>
-				Renames the [Color] at [code]old_name[/code] to [code]name[/code] if the theme has [code]theme_type[/code]. If [code]name[/code] is already taken, this method fails.
+				Renames the [Color] property defined by [code]old_name[/code] and [code]theme_type[/code] to [code]name[/code], if it exists.
+				Fails if it doesn't exist, or if a similar property with the new name already exists. Use [method has_color] to check for existence, and [method clear_color] to remove the existing property.
 			</description>
 		</method>
 		<method name="rename_constant">
@@ -368,7 +391,8 @@
 			<argument index="1" name="name" type="StringName" />
 			<argument index="2" name="theme_type" type="StringName" />
 			<description>
-				Renames the constant at [code]old_name[/code] to [code]name[/code] if the theme has [code]theme_type[/code]. If [code]name[/code] is already taken, this method fails.
+				Renames the constant property defined by [code]old_name[/code] and [code]theme_type[/code] to [code]name[/code], if it exists.
+				Fails if it doesn't exist, or if a similar property with the new name already exists. Use [method has_constant] to check for existence, and [method clear_constant] to remove the existing property.
 			</description>
 		</method>
 		<method name="rename_font">
@@ -377,7 +401,8 @@
 			<argument index="1" name="name" type="StringName" />
 			<argument index="2" name="theme_type" type="StringName" />
 			<description>
-				Renames the [Font] at [code]old_name[/code] to [code]name[/code] if the theme has [code]theme_type[/code]. If [code]name[/code] is already taken, this method fails.
+				Renames the [Font] property defined by [code]old_name[/code] and [code]theme_type[/code] to [code]name[/code], if it exists.
+				Fails if it doesn't exist, or if a similar property with the new name already exists. Use [method has_font] to check for existence, and [method clear_font] to remove the existing property.
 			</description>
 		</method>
 		<method name="rename_font_size">
@@ -386,7 +411,8 @@
 			<argument index="1" name="name" type="StringName" />
 			<argument index="2" name="theme_type" type="StringName" />
 			<description>
-				Renames the font size [code]old_name[/code] to [code]name[/code] if the theme has [code]theme_type[/code]. If [code]name[/code] is already taken, this method fails.
+				Renames the font size property defined by [code]old_name[/code] and [code]theme_type[/code] to [code]name[/code], if it exists.
+				Fails if it doesn't exist, or if a similar property with the new name already exists. Use [method has_font_size] to check for existence, and [method clear_font_size] to remove the existing property.
 			</description>
 		</method>
 		<method name="rename_icon">
@@ -395,7 +421,8 @@
 			<argument index="1" name="name" type="StringName" />
 			<argument index="2" name="theme_type" type="StringName" />
 			<description>
-				Renames the icon at [code]old_name[/code] to [code]name[/code] if the theme has [code]theme_type[/code]. If [code]name[/code] is already taken, this method fails.
+				Renames the icon property defined by [code]old_name[/code] and [code]theme_type[/code] to [code]name[/code], if it exists.
+				Fails if it doesn't exist, or if a similar property with the new name already exists. Use [method has_icon] to check for existence, and [method clear_icon] to remove the existing property.
 			</description>
 		</method>
 		<method name="rename_stylebox">
@@ -404,7 +431,8 @@
 			<argument index="1" name="name" type="StringName" />
 			<argument index="2" name="theme_type" type="StringName" />
 			<description>
-				Renames [StyleBox] at [code]old_name[/code] to [code]name[/code] if the theme has [code]theme_type[/code]. If [code]name[/code] is already taken, this method fails.
+				Renames the [StyleBox] property defined by [code]old_name[/code] and [code]theme_type[/code] to [code]name[/code], if it exists.
+				Fails if it doesn't exist, or if a similar property with the new name already exists. Use [method has_stylebox] to check for existence, and [method clear_stylebox] to remove the existing property.
 			</description>
 		</method>
 		<method name="rename_theme_item">
@@ -414,7 +442,9 @@
 			<argument index="2" name="name" type="StringName" />
 			<argument index="3" name="theme_type" type="StringName" />
 			<description>
-				Renames the theme item of [code]data_type[/code] at [code]old_name[/code] to [code]name[/code] if the theme has [code]theme_type[/code]. If [code]name[/code] is already taken, this method fails.
+				Renames the theme property of [code]data_type[/code] defined by [code]old_name[/code] and [code]theme_type[/code] to [code]name[/code], if it exists.
+				Fails if it doesn't exist, or if a similar property with the new name already exists. Use [method has_theme_item] to check for existence, and [method clear_theme_item] to remove the existing property.
+				[b]Note:[/b] This method is analogous to calling the corresponding data type specific method, but can be used for more generalized logic.
 			</description>
 		</method>
 		<method name="set_color">
@@ -423,8 +453,7 @@
 			<argument index="1" name="theme_type" type="StringName" />
 			<argument index="2" name="color" type="Color" />
 			<description>
-				Sets the theme's [Color] to [code]color[/code] at [code]name[/code] in [code]theme_type[/code].
-				Creates [code]theme_type[/code] if the theme does not have it.
+				Creates or changes the value of the [Color] property defined by [code]name[/code] and [code]theme_type[/code]. Use [method clear_color] to remove the property.
 			</description>
 		</method>
 		<method name="set_constant">
@@ -433,8 +462,7 @@
 			<argument index="1" name="theme_type" type="StringName" />
 			<argument index="2" name="constant" type="int" />
 			<description>
-				Sets the theme's constant to [code]constant[/code] at [code]name[/code] in [code]theme_type[/code].
-				Creates [code]theme_type[/code] if the theme does not have it.
+				Creates or changes the value of the constant property defined by [code]name[/code] and [code]theme_type[/code]. Use [method clear_constant] to remove the property.
 			</description>
 		</method>
 		<method name="set_font">
@@ -443,8 +471,7 @@
 			<argument index="1" name="theme_type" type="StringName" />
 			<argument index="2" name="font" type="Font" />
 			<description>
-				Sets the theme's [Font] to [code]font[/code] at [code]name[/code] in [code]theme_type[/code].
-				Creates [code]theme_type[/code] if the theme does not have it.
+				Creates or changes the value of the [Font] property defined by [code]name[/code] and [code]theme_type[/code]. Use [method clear_font] to remove the property.
 			</description>
 		</method>
 		<method name="set_font_size">
@@ -453,8 +480,7 @@
 			<argument index="1" name="theme_type" type="StringName" />
 			<argument index="2" name="font_size" type="int" />
 			<description>
-				Sets the theme's font size to [code]font_size[/code] at [code]name[/code] in [code]theme_type[/code].
-				Creates [code]theme_type[/code] if the theme does not have it.
+				Creates or changes the value of the font size property defined by [code]name[/code] and [code]theme_type[/code]. Use [method clear_font_size] to remove the property.
 			</description>
 		</method>
 		<method name="set_icon">
@@ -463,8 +489,7 @@
 			<argument index="1" name="theme_type" type="StringName" />
 			<argument index="2" name="texture" type="Texture2D" />
 			<description>
-				Sets the theme's icon [Texture2D] to [code]texture[/code] at [code]name[/code] in [code]theme_type[/code].
-				Creates [code]theme_type[/code] if the theme does not have it.
+				Creates or changes the value of the icon property defined by [code]name[/code] and [code]theme_type[/code]. Use [method clear_icon] to remove the property.
 			</description>
 		</method>
 		<method name="set_stylebox">
@@ -473,8 +498,7 @@
 			<argument index="1" name="theme_type" type="StringName" />
 			<argument index="2" name="texture" type="StyleBox" />
 			<description>
-				Sets theme's [StyleBox] to [code]stylebox[/code] at [code]name[/code] in [code]theme_type[/code].
-				Creates [code]theme_type[/code] if the theme does not have it.
+				Creates or changes the value of the [StyleBox] property defined by [code]name[/code] and [code]theme_type[/code]. Use [method clear_stylebox] to remove the property.
 			</description>
 		</method>
 		<method name="set_theme_item">
@@ -484,9 +508,9 @@
 			<argument index="2" name="theme_type" type="StringName" />
 			<argument index="3" name="value" type="Variant" />
 			<description>
-				Sets the theme item of [code]data_type[/code] to [code]value[/code] at [code]name[/code] in [code]theme_type[/code].
-				Does nothing if the [code]value[/code] type does not match [code]data_type[/code].
-				Creates [code]theme_type[/code] if the theme does not have it.
+				Creates or changes the value of the theme property of [code]data_type[/code] defined by [code]name[/code] and [code]theme_type[/code]. Use [method clear_theme_item] to remove the property.
+				Fails if the [code]value[/code] type is not accepted by [code]data_type[/code].
+				[b]Note:[/b] This method is analogous to calling the corresponding data type specific method, but can be used for more generalized logic.
 			</description>
 		</method>
 		<method name="set_type_variation">
@@ -494,25 +518,25 @@
 			<argument index="0" name="theme_type" type="StringName" />
 			<argument index="1" name="base_type" type="StringName" />
 			<description>
-				Marks [code]theme_type[/code] as being a variation of [code]base_type[/code].
+				Marks [code]theme_type[/code] as a variation of [code]base_type[/code].
 				This adds [code]theme_type[/code] as a suggested option for [member Control.theme_type_variation] on a [Control] that is of the [code]base_type[/code] class.
-				Variations can also be nested, i.e. [code]base_type[/code] can be another variation. If a chain of variations ends with a [code]base_type[/code] matching a class of a [Control], the whole chain is going to be suggested as options.
-				[b]Note:[/b] Suggestions only show up if this [Theme] is set as the project default theme. See [member ProjectSettings.gui/theme/custom].
+				Variations can also be nested, i.e. [code]base_type[/code] can be another variation. If a chain of variations ends with a [code]base_type[/code] matching the class of the [Control], the whole chain is going to be suggested as options.
+				[b]Note:[/b] Suggestions only show up if this theme resource is set as the project default theme. See [member ProjectSettings.gui/theme/custom].
 			</description>
 		</method>
 	</methods>
 	<members>
 		<member name="default_base_scale" type="float" setter="set_default_base_scale" getter="get_default_base_scale" default="0.0">
-			The default base scale factor of this [Theme] resource. Used by some controls to scale their visual properties based on a global scale factor. If this value is set to [code]0.0[/code], the global scale factor is used.
+			The default base scale factor of this theme resource. Used by some controls to scale their visual properties based on the global scale factor. If this value is set to [code]0.0[/code], the global scale factor is used.
 			Use [method has_default_base_scale] to check if this value is valid.
 		</member>
 		<member name="default_font" type="Font" setter="set_default_font" getter="get_default_font">
-			The default font of this [Theme] resource. Used as a fallback value for font items defined in this theme, but having invalid values. If this value is also invalid, the global default value is used.
+			The default font of this theme resource. Used as the default value when trying to fetch a font resource that doesn't exist in this theme or is in invalid state. If the default font is also missing or invalid, the engine fallback value is used.
 			Use [method has_default_font] to check if this value is valid.
 		</member>
 		<member name="default_font_size" type="int" setter="set_default_font_size" getter="get_default_font_size" default="-1">
-			The default font size of this [Theme] resource. Used as a fallback value for font size items defined in this theme, but having invalid values. If this value is set to [code]-1[/code], the global default value is used.
-			Use [method has_default_font_size] to check if this value is valid.
+			The default font size of this theme resource. Used as the default value when trying to fetch a font size value that doesn't exist in this theme or is in invalid state. If the default font size is also missing or invalid, the engine fallback value is used.
+			Values below [code]0[/code] are invalid and can be used to unset the property. Use [method has_default_font_size] to check if this value is valid.
 		</member>
 	</members>
 	<constants>