From 393a3c3122ac3b54044190ba7bdd081d6703db64 Mon Sep 17 00:00:00 2001
From: Hugo Locurcio <hugo.locurcio@hugo.pro>
Date: Wed, 26 Feb 2020 23:37:55 +0100
Subject: [PATCH] Improve the `Node.add_child_below_node()` documentation

This closes https://github.com/godotengine/godot-docs/issues/2730.
---
 doc/classes/Node.xml | 8 +++++---
 scene/main/node.cpp  | 2 +-
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/doc/classes/Node.xml b/doc/classes/Node.xml
index 3ddc3af200d..eb15bc2ad95 100644
--- a/doc/classes/Node.xml
+++ b/doc/classes/Node.xml
@@ -129,21 +129,23 @@
 				    child_node.get_parent().remove_child(child_node)
 				add_child(child_node)
 				[/codeblock]
+				If you need the child node to be added below a specific node in the list of children, use [method add_child_below_node] instead of this method.
 				[b]Note:[/b] If you want a child to be persisted to a [PackedScene], you must set [member owner] in addition to calling [method add_child]. This is typically relevant for [url=https://godot.readthedocs.io/en/latest/tutorials/misc/running_code_in_the_editor.html]tool scripts[/url] and [url=https://godot.readthedocs.io/en/latest/tutorials/plugins/editor/index.html]editor plugins[/url]. If [method add_child] is called without setting [member owner], the newly added [Node] will not be visible in the scene tree, though it will be visible in the 2D/3D view.
 			</description>
 		</method>
 		<method name="add_child_below_node">
 			<return type="void">
 			</return>
-			<argument index="0" name="node" type="Node">
+			<argument index="0" name="preceding_node" type="Node">
 			</argument>
-			<argument index="1" name="child_node" type="Node">
+			<argument index="1" name="node" type="Node">
 			</argument>
 			<argument index="2" name="legible_unique_name" type="bool" default="false">
 			</argument>
 			<description>
-				Adds a child node. The child is placed below the given node in the list of children.
+				Adds a child node below the [code]preceding_node[/code].
 				If [code]legible_unique_name[/code] is [code]true[/code], the child node will have an human-readable name based on the name of the node being instanced instead of its type.
+				Use [method add_child] instead of this method if you don't need the child node to be added below a specific node in the list of children.
 			</description>
 		</method>
 		<method name="add_to_group">
diff --git a/scene/main/node.cpp b/scene/main/node.cpp
index 5baa59fe7c7..a0159c38582 100644
--- a/scene/main/node.cpp
+++ b/scene/main/node.cpp
@@ -2800,7 +2800,7 @@ void Node::_bind_methods() {
 	GLOBAL_DEF("node/name_casing", NAME_CASING_PASCAL_CASE);
 	ProjectSettings::get_singleton()->set_custom_property_info("node/name_casing", PropertyInfo(Variant::INT, "node/name_casing", PROPERTY_HINT_ENUM, "PascalCase,camelCase,snake_case"));
 
-	ClassDB::bind_method(D_METHOD("add_child_below_node", "node", "child_node", "legible_unique_name"), &Node::add_child_below_node, DEFVAL(false));
+	ClassDB::bind_method(D_METHOD("add_child_below_node", "preceding_node", "node", "legible_unique_name"), &Node::add_child_below_node, DEFVAL(false));
 
 	ClassDB::bind_method(D_METHOD("set_name", "name"), &Node::set_name);
 	ClassDB::bind_method(D_METHOD("get_name"), &Node::get_name);