Add documentation and improvements for BTTask

Fixed: BTTask chidren property, setter and getter are exposed in editor

bt/bt_task.cpp

@@ -276,8 +276,8 @@ void BTTask::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("get_agent"), &BTTask::get_agent);
 	ClassDB::bind_method(D_METHOD("set_agent", "p_agent"), &BTTask::set_agent);
 
-	ClassDB::bind_method(D_METHOD("get_children"), &BTTask::_get_children);
+	ClassDB::bind_method(D_METHOD("_get_children"), &BTTask::_get_children);
-	ClassDB::bind_method(D_METHOD("set_children", "p_children"), &BTTask::_set_children);
+	ClassDB::bind_method(D_METHOD("_set_children", "p_children"), &BTTask::_set_children);
 
 	ClassDB::bind_method(D_METHOD("get_blackboard"), &BTTask::get_blackboard);
 	ClassDB::bind_method(D_METHOD("get_parent"), &BTTask::get_parent);
@@ -287,7 +287,7 @@ void BTTask::_bind_methods() {
 	ADD_PROPERTY(PropertyInfo(Variant::OBJECT, "agent", PROPERTY_HINT_RESOURCE_TYPE, "Object", 0), "set_agent", "get_agent");
 	ADD_PROPERTY(PropertyInfo(Variant::OBJECT, "blackboard", PROPERTY_HINT_RESOURCE_TYPE, "Blackboard", 0), "", "get_blackboard");
 	ADD_PROPERTY(PropertyInfo(Variant::OBJECT, "parent", PROPERTY_HINT_RESOURCE_TYPE, "BTTask", 0), "", "get_parent");
-	ADD_PROPERTY(PropertyInfo(Variant::ARRAY, "children", PROPERTY_HINT_NONE, "", PROPERTY_USAGE_NOEDITOR), "set_children", "get_children");
+	ADD_PROPERTY(PropertyInfo(Variant::ARRAY, "children", PROPERTY_HINT_NONE, "", PROPERTY_USAGE_NOEDITOR | PROPERTY_USAGE_INTERNAL), "_set_children", "_get_children");
 	ADD_PROPERTY(PropertyInfo(Variant::INT, "status", PROPERTY_HINT_NONE, "", 0), "", "get_status");
 
 	// Virtual methods.
@@ -344,4 +344,4 @@ BTTask::~BTTask() {
 		get_child(i)->parent = nullptr;
 		get_child(i).unref();
 	}
-}
+}

doc_classes/BTTask.xml

@@ -1,8 +1,13 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="BTTask" inherits="Resource" version="3.5" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../doc/class.xsd">
 	<brief_description>
+		Base class for BT tasks.
 	</brief_description>
 	<description>
+		Base class for all behavior tree tasks. Tasks are arranged in a tree-like structure called behavior tree (BT).
+		Tasks perform work and return their status with [method _tick]. See [enum TaskStatus]. 
+		There are several types of tasks: actions, conditions, decorators, and composites. Each type of task has its own corresponding subclass: [BTAction], [BTCondition], [BTDecorator], [BTComposite].
+		[b]Note:[/b] Do not inherint [BTTask] directly for your own tasks, instead inherit one of the subtypes above.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -10,38 +15,48 @@
 		<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 RUNNING] [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.
 			</description>
 		</method>
 		<method name="_exit" qualifiers="virtual">
 			<return type="void" />
 			<description>
+				Called when task is "exited", i.e. after [method _tick] returns [constant SUCCESS] or [constant FAILURE] status.
 			</description>
 		</method>
 		<method name="_generate_name" qualifiers="virtual">
 			<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].
 			</description>
 		</method>
 		<method name="_get_configuration_warning" qualifiers="virtual">
 			<return type="String" />
 			<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.
 			</description>
 		</method>
 		<method name="_setup" qualifiers="virtual">
 			<return type="void" />
 			<description>
+				Called when task is initialized during behavior tree initialization.
 			</description>
 		</method>
 		<method name="_tick" qualifiers="virtual">
 			<return type="int" />
 			<argument index="0" name="p_delta" type="float" />
 			<description>
+				Called when task is "ticked", i.e. executed by [BTPlayer] or [BTState] during update.
+				Returns [member TaskStatus].
+				*Note:* Tasks perform their main function by implementing this method.
 			</description>
 		</method>
 		<method name="add_child">
 			<return type="void" />
 			<argument index="0" name="p_child" type="BTTask" />
 			<description>
+				Adds a child task. The [code]p_child[/code] is placed at the end of the children list.
 			</description>
 		</method>
 		<method name="add_child_at_index">
@@ -49,50 +64,60 @@
 			<argument index="0" name="p_child" type="BTTask" />
 			<argument index="1" name="p_idx" type="int" />
 			<description>
+				Adds a child task. The [code]p_child[/code] is placed at [code]p_idx[/code] position in the children list.
 			</description>
 		</method>
 		<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.
 			</description>
 		</method>
 		<method name="execute">
 			<return type="int" />
 			<argument 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 SUCCESS] or [constant FAILURE] status is returned by [method _tick], [method _exit] will be called next.
 			</description>
 		</method>
 		<method name="get_child" qualifiers="const">
 			<return type="BTTask" />
 			<argument index="0" name="p_idx" type="int" />
 			<description>
+				Returns a child task by its index.
 			</description>
 		</method>
 		<method name="get_child_count" qualifiers="const">
 			<return type="int" />
 			<description>
+				Returns the number of child tasks.
 			</description>
 		</method>
 		<method name="get_child_index" qualifiers="const">
 			<return type="int" />
 			<argument index="0" name="p_child" type="BTTask" />
 			<description>
+				Returns the child task's index. If [code]p_child[/code] is not a child of the task, [code]-1[/code] is returned instead.
 			</description>
 		</method>
 		<method name="get_root" qualifiers="const">
 			<return type="BTTask" />
 			<description>
+				Returns the root task of the behavior tree.
 			</description>
 		</method>
 		<method name="get_task_name" qualifiers="const">
 			<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.
 			</description>
 		</method>
 		<method name="has_child" qualifiers="const">
 			<return type="bool" />
 			<argument index="0" name="p_child" type="BTTask" />
 			<description>
+				Returns [code]true[/code] if [code]p_child[/code] is a child of this task.
 			</description>
 		</method>
 		<method name="initialize">
@@ -100,65 +125,82 @@
 			<argument index="0" name="p_agent" type="Object" />
 			<argument index="1" name="p_blackboard" type="Blackboard" />
 			<description>
+				Initilizes the task. Assigns [member agent] and [member blackboard], and calls [method _setup] for the task and its children. 
+				The method is called recursively for each child task.
 			</description>
 		</method>
 		<method name="is_descendant_of" qualifiers="const">
 			<return type="bool" />
 			<argument 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.
 			</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.
 			</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 [member parent]. 
+				Returns [code]null[/code] if this task has no parent or it is the last child in the parent's children list.
 			</description>
 		</method>
 		<method name="print_tree" qualifiers="const">
 			<return type="void" />
 			<argument index="0" name="p_initial_tabs" type="int" default="0" />
 			<description>
+				Prints the subtree that starts with this task to console.
 			</description>
 		</method>
 		<method name="remove_child">
 			<return type="void" />
 			<argument index="0" name="p_child" type="BTTask" />
 			<description>
+				Removes [code]p_child[/code] task from children.
 			</description>
 		</method>
 		<method name="remove_child_at_index">
 			<return type="void" />
 			<argument index="0" name="p_idx" type="int" />
 			<description>
+				Removes a child task by index.
 			</description>
 		</method>
 	</methods>
 	<members>
 		<member name="agent" type="Object" setter="set_agent" getter="get_agent">
+			The agent is a contextual object for the task's behavior tree instance. Usually, the agent is an owner of the node with the behavior tree instance.
 		</member>
 		<member name="blackboard" type="Blackboard" setter="" getter="get_blackboard">
-		</member>
+			Provides access to the blackboard for this task and behavior tree. Blackboard is used to share data among tasks of the associated behavior tree.
-		<member name="children" type="Array" setter="set_children" getter="get_children" default="[  ]">
+			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].
 		</member>
 		<member name="parent" type="BTTask" setter="" getter="get_parent">
+			The task's parent.
 		</member>
 		<member name="status" type="int" setter="" getter="get_status">
+			Last execution [enum TaskStatus] returned by [method _tick].
 		</member>
 	</members>
 	<constants>
 		<constant name="FRESH" value="0" enum="TaskStatus">
+			Task wasn't executed yet or execution was cancelled.
 		</constant>
 		<constant name="RUNNING" value="1" enum="TaskStatus">
+			Task is being performed and hasn't finished yet.
 		</constant>
 		<constant name="FAILURE" value="2" enum="TaskStatus">
+			Task has finished with failure.
 		</constant>
 		<constant name="SUCCESS" value="3" enum="TaskStatus">
+			Task has finished with success.
 		</constant>
 	</constants>
 </class>