Improve docs for BTDecorator & BTTask

doc_classes/BT.xml

@@ -9,7 +9,7 @@
 	</tutorials>
 	<constants>
 		<constant name="FRESH" value="0" enum="Status">
-			Task wasn't executed yet or execution was cancelled.
+			Task wasn't executed yet or it was aborted and reset.
 		</constant>
 		<constant name="RUNNING" value="1" enum="Status">
 			Task is being performed and hasn't finished yet.

doc_classes/BTDecorator.xml

@@ -4,9 +4,9 @@
 		Base class for BT decorators.
 	</brief_description>
 	<description>
-		Base class for all behavior tree decorators. Extend [code]BTDecorator[/code] to create your own decorators.
+		Base class for all [BehaviorTree] decorators. You can create your own decorators by extending the BTDecorator class.
-		Decorator is a task in a [BehaviorTree] that alters the behavior of its child task. Can only have a single child.
+		A decorator is a task within a [BehaviorTree] that alters the behavior of its child task. Decorators can have only one child task.
-		It can be used to add conditions, limits, or other constraints to the execution of a task. Examples of [BehaviorTree] decorators include [BTInvert], [BTRepeat], and [BTCooldown]. The use of [BehaviorTree] decorators can help to simplify the design and implementation of complex behaviors by adding additional logic to existing tasks.
+		Decorators can be used to add conditions, limits, or other constraints to the execution of a task. Examples of [BehaviorTree] decorators include [BTInvert], [BTRepeat], and [BTCooldown]. The use of [BehaviorTree] decorators can simplify the design and implementation of complex behaviors by adding additional logic to existing tasks.
 	</description>
 	<tutorials>
 	</tutorials>

doc_classes/BTTask.xml

@@ -1,13 +1,13 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="BTTask" inherits="BT" version="4.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../doc/class.xsd">
 	<brief_description>
-		Base class for [BehaviorTree] tasks.
+		Base class for all [BehaviorTree] tasks.
 	</brief_description>
 	<description>
-		Base class for all [BehaviorTree] tasks. A task is a building block in a [BehaviorTree] that represents a specific behavior or control flow. It is the basic unit of the Behavior Tree (BT) and is used to create complex behaviors by combining and nesting tasks in a hierarchy.
+		Base class for all [BehaviorTree] tasks. A task is a basic building block in a [BehaviorTree] that represents a specific behavior or control flow. Tasks are used to create complex behaviors by combining and nesting them in a hierarchy.
-		Tasks perform work and return their status with [method _tick]. See [enum BT.Status].
+		A task can be one of the following types: action, condition, composite, or decorator. Each type of task has its own corresponding subclass: [BTAction], [BTCondition], [BTDecorator], [BTComposite].
-		A Task can be an action, a condition, a composite, or a decorator. Each type of task has its own corresponding subclass: [BTAction], [BTCondition], [BTDecorator], [BTComposite].
+		Tasks perform their work and return their status using the [method _tick] method. Status values are defined in [enum BT.Status]. Tasks can be initialized using the [method _setup] method. See also [method _enter] & [method _exit].
-		[b]Note:[/b] Do not extend [code]BTTask[/code] directly for your own tasks, instead extend one of the subtypes above.
+		[b]Note:[/b] Do not extend [code]BTTask[/code] directly for your own tasks. Instead, extend one of the subtypes mentioned above.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -15,41 +15,41 @@
 		<method name="_enter" qualifiers="virtual">
 			<return type="void" />
 			<description>
-				Called when task is "entered", i.e. when task is executed while not having a [constant BT.RUNNING] [member status].
+				Called when task is "entered", i.e. when task is executed while not having a [code]RUNNING[/code] [member status].
-				It is called before [method _tick] in the execution order. This method is used when preparation is needed before main work begins, usually when it takes more than one tick to finish the task.
+				It is called before [method _tick] in the execution order. This method is used when preparation is needed before main work begins, usually when it takes more than one tick to finish the task. See also [method execute].
 			</description>
 		</method>
 		<method name="_exit" qualifiers="virtual">
 			<return type="void" />
 			<description>
-				Called when task is "exited", i.e. after [method _tick] returns [constant BT.SUCCESS] or [constant BT.FAILURE] status.
+				Called when task is "exited", i.e. after [method _tick] returns [code]SUCCESS[/code] or [code]FAILURE[/code] status. See also [method execute].
 			</description>
 		</method>
 		<method name="_generate_name" qualifiers="virtual const">
 			<return type="String" />
 			<description>
-				When [member custom_name] is empty, the string returned by this method is used to display the task by the editor. See [method get_task_name].
+				Called to generate a display name for the task unless [member custom_name] is set. See [method get_task_name].
 			</description>
 		</method>
 		<method name="_get_configuration_warning" qualifiers="virtual const">
 			<return type="PackedStringArray" />
 			<description>
-				The string returned by this method is displayed as a warning in the BT editor if the script that overrides it is a [code]tool[/code] script.
+				The string returned by this method is shown as a warning message in the behavior tree editor. Any task script that overrides this method must include [code]@tool[/code] annotation at the top of the file.
 			</description>
 		</method>
 		<method name="_setup" qualifiers="virtual">
 			<return type="void" />
 			<description>
-				Called when task is initialized during behavior tree initialization.
+				Called to initialize a task during initialization step. It is called only once before the task's first execution tick. This method allows you to set up any necessary state or configurations for the task before it begins executing.
 			</description>
 		</method>
 		<method name="_tick" qualifiers="virtual">
 			<return type="int" enum="BT.Status" />
 			<param index="0" name="p_delta" type="float" />
 			<description>
-				Called when task is "ticked", i.e. executed by [BTPlayer] or [BTState] during update.
+				Called when task is "ticked", i.e. executed by [BTPlayer] or [BTState] during an update.
-				Returns [enum BT.Status].
+				Returns execution status as defined in [enum BT.Status].
-				*Note:* Tasks perform their main function by implementing this method.
+				[b]Note:[/b] Tasks perform their main function by implementing this method.
 			</description>
 		</method>
 		<method name="add_child">
@@ -70,21 +70,24 @@
 		<method name="clone" qualifiers="const">
 			<return type="BTTask" />
 			<description>
-				Clones the task and its children with the exported members copied. Sub-resources are shared for efficiency, except for [BBParam] subtypes, which are always copied.
+				Duplicates the task and its children, copying the exported members. Sub-resources are shared for efficiency, except for [BBParam] subtypes, which are always copied. Used by the editor to instantiate [BehaviorTree] and copy-paste tasks.
 			</description>
 		</method>
 		<method name="execute">
 			<return type="int" enum="BT.Status" />
 			<param index="0" name="p_delta" type="float" />
 			<description>
-				Performs task's execution. During execution [method _enter] is called first, unless current task [member status] is [code]RUNNING[/code]. [method _tick] is called next to perform task's main function. If [constant BT.SUCCESS] or [constant BT.FAILURE] status is returned by [method _tick], [method _exit] will be called next.
+				Performs task's execution. The execution follows a specific sequence:
+				- If task's current [member status] is not [code]RUNNING[/code], the [method _enter] method is called first.
+				- Next, the [method _tick] method is called next to perform the task's work.
+				- If the [method _tick] method returns [code]SUCCESS[/code] or [code]FAILURE[/code] status, the [method _exit] method will be called next as part of the execution cleanup.
 			</description>
 		</method>
 		<method name="get_child" qualifiers="const">
 			<return type="BTTask" />
 			<param index="0" name="p_idx" type="int" />
 			<description>
-				Returns a child task by its index.
+				Returns a child task by specifying its index.
 			</description>
 		</method>
 		<method name="get_child_count" qualifiers="const">
@@ -109,7 +112,7 @@
 		<method name="get_parent" qualifiers="const">
 			<return type="BTTask" />
 			<description>
-				Returns task's parent.
+				Returns the task's parent.
 			</description>
 		</method>
 		<method name="get_root" qualifiers="const">
@@ -122,7 +125,7 @@
 			<return type="String" />
 			<description>
 				The string returned by this method is used to represent the task in the editor.
-				[member custom_name] value is returned when it is not empty. Otherwise, the string constructed by [method _generate_name] is returned instead.
+				Method [method _generate_name] is called to generate a display name for the task unless [member custom_name] is set.
 			</description>
 		</method>
 		<method name="has_child" qualifiers="const">
@@ -145,19 +148,19 @@
 			<return type="bool" />
 			<param index="0" name="p_task" type="BTTask" />
 			<description>
-				Returns [code]true[/code] if this task is descendant of [code]p_task[/code]. I.e. this task must be a child of [code]p_task[/code] or one of its children or grandchildren.
+				Returns [code]true[/code] if this task is a descendant of [code]p_task[/code]. In other words, this task must be a child of [code]p_task[/code] or one of its children or grandchildren.
 			</description>
 		</method>
 		<method name="is_root" qualifiers="const">
 			<return type="bool" />
 			<description>
-				Returns [code]true[/code] if this task is the root task of the tree. A behavior tree can have only one root task.
+				Returns [code]true[/code] if this task is the root task of its behavior tree. A behavior tree can have only one root task.
 			</description>
 		</method>
 		<method name="next_sibling" qualifiers="const">
 			<return type="BTTask" />
 			<description>
-				Returns the next task after this task in the children list of the parent.
+				Returns the next task after this task in the parent's children list.
 				Returns [code]null[/code] if this task has no parent or it is the last child in the parent's children list.
 			</description>
 		</method>
@@ -165,7 +168,7 @@
 			<return type="void" />
 			<param index="0" name="p_initial_tabs" type="int" default="0" />
 			<description>
-				Prints the subtree that starts with this task to console.
+				Prints the subtree that starts with this task to the console.
 			</description>
 		</method>
 		<method name="remove_child">
@@ -179,24 +182,24 @@
 			<return type="void" />
 			<param index="0" name="p_idx" type="int" />
 			<description>
-				Removes a child task by index.
+				Removes a child task at a specified index from children.
 			</description>
 		</method>
 	</methods>
 	<members>
 		<member name="agent" type="Node" setter="set_agent" getter="get_agent">
-			The agent is a contextual object for the task's behavior tree instance. Usually, agent is the owner of a node with the [BehaviorTree] resource.
+			The agent is a contextual object for the task's [BehaviorTree] instance. Usually, agent is the owner of the [BTPlayer] node containing the [BehaviorTree] resource.
 		</member>
 		<member name="blackboard" type="Blackboard" setter="" getter="get_blackboard">
-			Provides access to the blackboard for this task and behavior tree. Blackboard is used to share data among tasks of the associated behavior tree.
+			Provides access to the [Blackboard]. Blackboard is used to share data among tasks of the associated [BehaviorTree].
 			See [Blackboard] for additional info.
 		</member>
 		<member name="custom_name" type="String" setter="set_custom_name" getter="get_custom_name" default="&quot;&quot;">
-			User provided name for the task. If not empty, [code]custom_name[/code] is used by the editor to display the task. See [method get_task_name].
+			User-provided name for the task. If not empty, [code]custom_name[/code] is used by the editor to represent the task. See [method get_task_name].
 		</member>
 		<member name="elapsed_time" type="float" setter="" getter="get_elapsed_time">
-			Elapsed time since the task was entered.
+			Elapsed time since the task was "entered". See [method _enter].
-			Returns 0 when task is not [code]RUNNING[/code].
+			Returns [code]0[/code] when task is not [code]RUNNING[/code].
 		</member>
 		<member name="status" type="int" setter="" getter="get_status" enum="BT.Status">
 			Last execution [enum BT.Status] returned by [method _tick].