Merge pull request #42721 from Paulb23/update_syntax_highlighting_docs

Update SyntaxHighlighter documentation

doc/classes/CodeHighlighter.xml

@@ -1,8 +1,10 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="CodeHighlighter" inherits="SyntaxHighlighter" version="4.0">
 	<brief_description>
+		A syntax highlighter for code.
 	</brief_description>
 	<description>
+		A syntax highlighter for code.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -19,6 +21,9 @@
 			<argument index="3" name="p_line_only" type="bool" default="false">
 			</argument>
 			<description>
+				Adds a color region such as comments or strings.
+				Both the start and end keys must be symbols. Only the start key has to be unique.
+				Line only denotes if the region should continue until the end of the line or carry over on to the next line. If the end key is blank this is automatically set to [code]true[/code].
 			</description>
 		</method>
 		<method name="add_keyword_color">
@@ -29,6 +34,8 @@
 			<argument index="1" name="color" type="Color">
 			</argument>
 			<description>
+				Sets the color for a keyword.
+				The keyword cannot contain any symbols except '_'.
 			</description>
 		</method>
 		<method name="add_member_keyword_color">
@@ -39,24 +46,30 @@
 			<argument index="1" name="color" type="Color">
 			</argument>
 			<description>
+				Sets the color for a member keyword.
+				The member keyword cannot contain any symbols except '_'.
+				It will not be highlighted if preceded by a '.'.
 			</description>
 		</method>
 		<method name="clear_color_regions">
 			<return type="void">
 			</return>
 			<description>
+				Removes all color regions.
 			</description>
 		</method>
 		<method name="clear_keyword_colors">
 			<return type="void">
 			</return>
 			<description>
+				Removes all keywords.
 			</description>
 		</method>
 		<method name="clear_member_keyword_colors">
 			<return type="void">
 			</return>
 			<description>
+				Removes all member keywords.
 			</description>
 		</method>
 		<method name="get_keyword_color" qualifiers="const">
@@ -65,6 +78,7 @@
 			<argument index="0" name="keyword" type="String">
 			</argument>
 			<description>
+				Returns the color for a keyword.
 			</description>
 		</method>
 		<method name="get_member_keyword_color" qualifiers="const">
@@ -73,6 +87,7 @@
 			<argument index="0" name="member_keyword" type="String">
 			</argument>
 			<description>
+				Returns the color for a member keyword.
 			</description>
 		</method>
 		<method name="has_color_region" qualifiers="const">
@@ -81,6 +96,7 @@
 			<argument index="0" name="p_start_key" type="String">
 			</argument>
 			<description>
+				Return [code]true[/code] if the start key exists, else [code]false[/code].
 			</description>
 		</method>
 		<method name="has_keyword_color" qualifiers="const">
@@ -89,6 +105,7 @@
 			<argument index="0" name="keyword" type="String">
 			</argument>
 			<description>
+				Return [code]true[/code] if the keyword exists, else [code]false[/code].
 			</description>
 		</method>
 		<method name="has_member_keyword_color" qualifiers="const">
@@ -97,6 +114,7 @@
 			<argument index="0" name="member_keyword" type="String">
 			</argument>
 			<description>
+				Return [code]true[/code] if the member keyword exists, else [code]false[/code].
 			</description>
 		</method>
 		<method name="remove_color_region">
@@ -105,6 +123,7 @@
 			<argument index="0" name="p_start_key" type="String">
 			</argument>
 			<description>
+				Removes the color region that uses that start key.
 			</description>
 		</method>
 		<method name="remove_keyword_color">
@@ -113,6 +132,7 @@
 			<argument index="0" name="keyword" type="String">
 			</argument>
 			<description>
+				Removes the keyword.
 			</description>
 		</method>
 		<method name="remove_member_keyword_color">
@@ -121,23 +141,31 @@
 			<argument index="0" name="member_keyword" type="String">
 			</argument>
 			<description>
+				Removes the member keyword.
 			</description>
 		</method>
 	</methods>
 	<members>
 		<member name="color_regions" type="Dictionary" setter="set_color_regions" getter="get_color_regions" default="{}">
+			Sets the color regions. All existing regions will be removed. The [Dictionary] key is the region start and end key, separated by a space. The value is the region color.
 		</member>
 		<member name="function_color" type="Color" setter="set_function_color" getter="get_function_color" default="Color( 0, 0, 0, 1 )">
+			Sets color for functions. A function is a non-keyword string followed by a '('.
 		</member>
 		<member name="keyword_colors" type="Dictionary" setter="set_keyword_colors" getter="get_keyword_colors" default="{}">
+			Sets the keyword colors. All existing keywords will be removed. The [Dictionary] key is the keyword. The value is the keyword color.
 		</member>
 		<member name="member_keyword_colors" type="Dictionary" setter="set_member_keyword_colors" getter="get_member_keyword_colors" default="{}">
+			Sets the member keyword colors. All existing member keyword will be removed. The [Dictionary] key is the member keyword. The value is the member keyword color.
 		</member>
 		<member name="member_variable_color" type="Color" setter="set_member_variable_color" getter="get_member_variable_color" default="Color( 0, 0, 0, 1 )">
+			Sets color for member variables. A member variable is non-keyword, non-function string proceeded with a '.'.
 		</member>
 		<member name="number_color" type="Color" setter="set_number_color" getter="get_number_color" default="Color( 0, 0, 0, 1 )">
+			Sets the color for numbers.
 		</member>
 		<member name="symbol_color" type="Color" setter="set_symbol_color" getter="get_symbol_color" default="Color( 0, 0, 0, 1 )">
+			Sets the color for symbols.
 		</member>
 	</members>
 	<constants>

doc/classes/EditorSyntaxHighlighter.xml

@@ -1,8 +1,11 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="EditorSyntaxHighlighter" inherits="SyntaxHighlighter" version="4.0">
 	<brief_description>
+		Base Syntax highlighter resource for the [ScriptEditor].
 	</brief_description>
 	<description>
+		Base syntax highlighter resource all editor syntax highlighters extend from, it is used in the [ScriptEditor].
+		Add a syntax highlighter to an individual script by calling [method ScriptEditorBase.add_syntax_highlighter]. To apply to all scripts on open, call [method ScriptEditor.register_syntax_highlighter]
 	</description>
 	<tutorials>
 	</tutorials>
@@ -11,18 +14,21 @@
 			<return type="String">
 			</return>
 			<description>
+				Virtual method which can be overridden to return the syntax highlighter name.
 			</description>
 		</method>
 		<method name="_get_supported_extentions" qualifiers="virtual">
 			<return type="Array">
 			</return>
 			<description>
+				Virtual method which can be overridden to return the supported file extensions.
 			</description>
 		</method>
 		<method name="_get_supported_languages" qualifiers="virtual">
 			<return type="Array">
 			</return>
 			<description>
+				Virtual method which can be overridden to return the supported language names.
 			</description>
 		</method>
 	</methods>

doc/classes/ScriptEditor.xml

@@ -37,6 +37,7 @@
 			<return type="ScriptEditorBase">
 			</return>
 			<description>
+				Returns the [ScriptEditorBase] object that the user is currently editing.
 			</description>
 		</method>
 		<method name="get_current_script">
@@ -60,6 +61,7 @@
 			<return type="Array">
 			</return>
 			<description>
+				Returns an array with all [ScriptEditorBase] objects which are currently open in editor.
 			</description>
 		</method>
 		<method name="get_open_scripts" qualifiers="const">
@@ -95,6 +97,8 @@
 			<argument index="0" name="syntax_highlighter" type="EditorSyntaxHighlighter">
 			</argument>
 			<description>
+				Registers the [EditorSyntaxHighlighter] to the editor, the [EditorSyntaxHighlighter] will be available on all open scripts.
+				[b]Note:[/b] Does not apply to scripts that are already opened.
 			</description>
 		</method>
 		<method name="unregister_syntax_highlighter">
@@ -103,6 +107,8 @@
 			<argument index="0" name="syntax_highlighter" type="EditorSyntaxHighlighter">
 			</argument>
 			<description>
+				Unregisters the [EditorSyntaxHighlighter] from the editor.
+				[b]Note:[/b] The [EditorSyntaxHighlighter] will still be applied to scripts that are already opened.
 			</description>
 		</method>
 	</methods>

doc/classes/ScriptEditorBase.xml

@@ -1,8 +1,10 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="ScriptEditorBase" inherits="VBoxContainer" version="4.0">
 	<brief_description>
+		Base editor for editing scripts in the [ScriptEditor].
 	</brief_description>
 	<description>
+		Base editor for editing scripts in the [ScriptEditor], this does not include documentation items.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -13,34 +15,40 @@
 			<argument index="0" name="highlighter" type="Object">
 			</argument>
 			<description>
+				Adds a [EditorSyntaxHighlighter] to the open script.
 			</description>
 		</method>
 	</methods>
 	<signals>
 		<signal name="edited_script_changed">
 			<description>
+				Emitted after script validation. For visual scripts on modification.
 			</description>
 		</signal>
 		<signal name="go_to_help">
 			<argument index="0" name="what" type="String">
 			</argument>
 			<description>
+				Emitted when the user requests a specific documentation page.
 			</description>
 		</signal>
 		<signal name="name_changed">
 			<description>
+				Emitted after script validation or when the edited resource has changed. Not used by visual scripts.
 			</description>
 		</signal>
 		<signal name="replace_in_files_requested">
 			<argument index="0" name="text" type="String">
 			</argument>
 			<description>
+				Emitted when the user request to find and replace text in the file system. Not used by visual scripts.
 			</description>
 		</signal>
 		<signal name="request_help">
 			<argument index="0" name="topic" type="String">
 			</argument>
 			<description>
+				Emitted when the user requests contextual help.
 			</description>
 		</signal>
 		<signal name="request_open_script_at_line">
@@ -49,16 +57,19 @@
 			<argument index="1" name="line" type="int">
 			</argument>
 			<description>
+				Emitted when the user requests a script.
 			</description>
 		</signal>
 		<signal name="request_save_history">
 			<description>
+				Emitted when the user contextual goto and the item is in the same script.
 			</description>
 		</signal>
 		<signal name="search_in_files_requested">
 			<argument index="0" name="text" type="String">
 			</argument>
 			<description>
+				Emitted when the user request to search text in the file system. Not used by visual scripts.
 			</description>
 		</signal>
 	</signals>

doc/classes/SyntaxHighlighter.xml

@@ -1,30 +1,46 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="SyntaxHighlighter" inherits="Resource" version="4.0">
 	<brief_description>
+		Base Syntax highlighter resource for [TextEdit].
 	</brief_description>
 	<description>
+		Base syntax highlighter resource all syntax highlighters extend from, provides syntax highlighting data to [TextEdit].
+		The associated [TextEdit] node will call into the [SyntaxHighlighter] on a as needed basis.
+		[b]Note:[/b] Each Syntax highlighter instance should not be shared across multiple [TextEdit] nodes.
 	</description>
 	<tutorials>
 	</tutorials>
 	<methods>
+		<method name="_clear_highlighting_cache" qualifiers="virtual">
+			<return type="void">
+			</return>
+			<description>
+			    Virtual method which can be overridden to clear any local caches.
+			</description>
+		</method>
 		<method name="_get_line_syntax_highlighting" qualifiers="virtual">
 			<return type="Dictionary">
 			</return>
 			<argument index="0" name="p_line" type="int">
 			</argument>
 			<description>
+				Virtual method which can be overridden to return syntax highlighting data.
+				See [method get_line_syntax_highlighting] for more details.
 			</description>
 		</method>
 		<method name="_update_cache" qualifiers="virtual">
 			<return type="void">
 			</return>
 			<description>
+			    Virtual method which can be overridden to update any local caches.
 			</description>
 		</method>
 		<method name="clear_highlighting_cache">
 			<return type="void">
 			</return>
 			<description>
+				Clears all cached syntax highlighting data.
+				Then calls overridable method [method _clear_highlighting_cache].
 			</description>
 		</method>
 		<method name="get_line_syntax_highlighting">
@@ -33,18 +49,35 @@
 			<argument index="0" name="p_line" type="int">
 			</argument>
 			<description>
+				Returns syntax highlighting data for a single line. If the line is not cached, calls [method _get_line_syntax_highlighting] to calculate the data.
+				The return [Dictionary] is column number to [Dictionary]. The column number notes the start of a region, the region will end if another region is found, or at the end of the line. The nested [Dictionary] contains the data for that region, currently only the key "color" is supported.
+				[b]Example return:[/b]
+				[codeblock]
+				var color_map = {
+				    0: {
+				        "color": Color(1, 0, 0)
+				    },
+				    5: {
+				        "color": Color(0, 1, 0)
+				    }
+				}
+				[/codeblock]
+				This will color columns 0-4 red, and columns 5-eol in green.
 			</description>
 		</method>
 		<method name="get_text_edit">
 			<return type="TextEdit">
 			</return>
 			<description>
+				Returns the associated [TextEdit] node.
 			</description>
 		</method>
 		<method name="update_cache">
 			<return type="void">
 			</return>
 			<description>
+				Clears then updates the [SyntaxHighlighter] caches. Override [method _update_cache] for a callback.
+				[b]Note:[/b] This is called automatically when the associated [TextEdit] node, updates its own cache.
 			</description>
 		</method>
 	</methods>

doc/classes/TextEdit.xml

@@ -725,6 +725,7 @@
 			Set additional options for BiDi override.
 		</member>
 		<member name="syntax_highlighter" type="SyntaxHighlighter" setter="set_syntax_highlighter" getter="get_syntax_highlighter">
+			Sets the [SyntaxHighlighter] to use.
 		</member>
 		<member name="text" type="String" setter="set_text" getter="get_text" default="&quot;&quot;">
 			String value of the [TextEdit].
@@ -914,7 +915,7 @@
 	</constants>
 	<theme_items>
 		<theme_item name="background_color" type="Color" default="Color( 0, 0, 0, 0 )">
-			Sets the background [Color] of this [TextEdit]. [member syntax_highlighting] has to be enabled.
+			Sets the background [Color] of this [TextEdit].
 		</theme_item>
 		<theme_item name="brace_mismatch_color" type="Color" default="Color( 1, 0.2, 0.2, 1 )">
 		</theme_item>