From 10469c1962172db954d02a3912053a99e2a0dfa3 Mon Sep 17 00:00:00 2001
From: Bojidar Marinov <bojidar.marinov.bg@gmail.com>
Date: Thu, 28 Sep 2017 13:07:20 +0300
Subject: Document some of the VisualScript classes.

---
 doc/classes/VisualScriptCustomNode.xml | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

(limited to 'doc/classes/VisualScriptCustomNode.xml')

diff --git a/doc/classes/VisualScriptCustomNode.xml b/doc/classes/VisualScriptCustomNode.xml
index ec442e993c..e321c8854a 100644
--- a/doc/classes/VisualScriptCustomNode.xml
+++ b/doc/classes/VisualScriptCustomNode.xml
@@ -1,8 +1,10 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="VisualScriptCustomNode" inherits="VisualScriptNode" category="Core" version="3.0.alpha.custom_build">
 	<brief_description>
+		A scripted Visual Script node.
 	</brief_description>
 	<description>
+		A custom Visual Script node which can be scripted in powerful ways.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -13,18 +15,21 @@
 			<return type="String">
 			</return>
 			<description>
+				Return the node's title.
 			</description>
 		</method>
 		<method name="_get_category" qualifiers="virtual">
 			<return type="String">
 			</return>
 			<description>
+				Return the node's category.
 			</description>
 		</method>
 		<method name="_get_input_value_port_count" qualifiers="virtual">
 			<return type="int">
 			</return>
 			<description>
+				Return the count of input value ports.
 			</description>
 		</method>
 		<method name="_get_input_value_port_name" qualifiers="virtual">
@@ -33,6 +38,7 @@
 			<argument index="0" name="idx" type="int">
 			</argument>
 			<description>
+				Return the specified input port's name.
 			</description>
 		</method>
 		<method name="_get_input_value_port_type" qualifiers="virtual">
@@ -41,12 +47,14 @@
 			<argument index="0" name="idx" type="int">
 			</argument>
 			<description>
+				Return the specified input port's type. See the TYPE_* enum in [@GlobalScope].
 			</description>
 		</method>
 		<method name="_get_output_sequence_port_count" qualifiers="virtual">
 			<return type="int">
 			</return>
 			<description>
+				Return the amount of output [b]sequence[/b] ports.
 			</description>
 		</method>
 		<method name="_get_output_sequence_port_text" qualifiers="virtual">
@@ -55,12 +63,14 @@
 			<argument index="0" name="idx" type="int">
 			</argument>
 			<description>
+				Return the specified [b]sequence[/b] output's name.
 			</description>
 		</method>
 		<method name="_get_output_value_port_count" qualifiers="virtual">
 			<return type="int">
 			</return>
 			<description>
+				Return the amount of output value ports.
 			</description>
 		</method>
 		<method name="_get_output_value_port_name" qualifiers="virtual">
@@ -69,6 +79,7 @@
 			<argument index="0" name="idx" type="int">
 			</argument>
 			<description>
+				Return the specified output's name.
 			</description>
 		</method>
 		<method name="_get_output_value_port_type" qualifiers="virtual">
@@ -77,24 +88,28 @@
 			<argument index="0" name="idx" type="int">
 			</argument>
 			<description>
+				Return the specified output's type. See the TYPE_* enum in [@GlobalScope].
 			</description>
 		</method>
 		<method name="_get_text" qualifiers="virtual">
 			<return type="String">
 			</return>
 			<description>
+				Return the custom node's text, which is shown right next to the input [b]sequence[/b] port (if there is none, on the place that is usually taken by it).
 			</description>
 		</method>
 		<method name="_get_working_memory_size" qualifiers="virtual">
 			<return type="int">
 			</return>
 			<description>
+				Return the size of the custom node's working memory. See [method _step] for more details.
 			</description>
 		</method>
 		<method name="_has_input_sequence_port" qualifiers="virtual">
 			<return type="bool">
 			</return>
 			<description>
+				Return whether the custom node has an input [b]sequence[/b] port.
 			</description>
 		</method>
 		<method name="_step" qualifiers="virtual">
@@ -109,25 +124,42 @@
 			<argument index="3" name="working_mem" type="Array">
 			</argument>
 			<description>
+				Execute the custom node's logic, returning the index of the output sequence port to use or a [String] when there is an error.
+				
+				The [code]inputs[/code] array contains the values of the input ports.
+				[code]outputs[/code] is an array whose indices should be set to the respective outputs.
+				The [code]start_mode[/code] is usually [code]START_MODE_BEGIN_SEQUENCE[/code], unless you have used the STEP_* constants.
+				[code]working_mem[/code] is an array which can be used to persist information between runs of the custom node.
+				
+				When returning, you can mask the returned value with one of the STEP_* constants.
 			</description>
 		</method>
 	</methods>
 	<constants>
 		<constant name="START_MODE_BEGIN_SEQUENCE" value="0">
+			The start mode used the first time when [method _step] is called.
 		</constant>
 		<constant name="START_MODE_CONTINUE_SEQUENCE" value="1">
+			The start mode used when [method _step] is called after coming back from a STEP_PUSH_STACK_BIT.
 		</constant>
 		<constant name="START_MODE_RESUME_YIELD" value="2">
+			The start mode used when [method _step] is called after resuming from STEP_YIELD_BIT.
 		</constant>
 		<constant name="STEP_PUSH_STACK_BIT" value="16777216" enum="">
+			Hint used by [method _step] to tell that control should return to it when there is no other node left to execute.
+			This is used by [VisualScriptCondition] to redirect the sequence to the "Done" port after the true/false branch has finished execution.
 		</constant>
 		<constant name="STEP_GO_BACK_BIT" value="33554432" enum="">
+			Hint used by [method _step] to tell that control should return back, either hitting a previous STEP_PUSH_STACK_BIT or exiting the function.
 		</constant>
 		<constant name="STEP_NO_ADVANCE_BIT" value="67108864" enum="">
 		</constant>
 		<constant name="STEP_EXIT_FUNCTION_BIT" value="134217728" enum="">
+			Hint used by [method _step] to tell that control should stop and exit the function.
 		</constant>
 		<constant name="STEP_YIELD_BIT" value="268435456" enum="">
+			Hint used by [method _step] to tell that the function should be yielded.
+			Using this requires you to have at least one working memory slot, which is used for the [VisualScriptFunctionState].
 		</constant>
 	</constants>
 </class>
-- 
cgit v1.2.3