From 509cf611bc1735fd640f81fa00c3366fc799f258 Mon Sep 17 00:00:00 2001
From: Paul Marechal <paul.marechal.0@gmail.com>
Date: Thu, 9 Oct 2025 14:50:38 -0400
Subject: [PATCH] Add note for some usages of Plane in APIs

Some old APIs that may expect a Vector4 instead require a Plane: this
is pretty confusing especially with tangents as one could interpret
the API as wanting a value directly representing the tangent plane when
in reality the Plane type is just used to carry one Vector3 and one
extra sign component.

This commit attempts to clear any potential confusion by adding a note
to the APIs using Planes in such a way.
---
 doc/classes/ImmediateMesh.xml | 1 +
 doc/classes/MeshDataTool.xml  | 1 +
 doc/classes/SurfaceTool.xml   | 1 +
 3 files changed, 3 insertions(+)

diff --git a/doc/classes/ImmediateMesh.xml b/doc/classes/ImmediateMesh.xml
index 7e40d0b4c53..d5228b54e6c 100644
--- a/doc/classes/ImmediateMesh.xml
+++ b/doc/classes/ImmediateMesh.xml
@@ -83,6 +83,7 @@
 			<param index="0" name="tangent" type="Plane" />
 			<description>
 				Set the tangent attribute that will be pushed with the next vertex.
+				[b]Note:[/b] Even though [param tangent] is a [Plane], it does not directly represent the tangent plane. Its [member Plane.x], [member Plane.y], and [member Plane.z] represent the tangent vector and [member Plane.d] should be either [code]-1[/code] or [code]1[/code]. See also [constant Mesh.ARRAY_TANGENT].
 			</description>
 		</method>
 		<method name="surface_set_uv">
diff --git a/doc/classes/MeshDataTool.xml b/doc/classes/MeshDataTool.xml
index cdcbd528fd1..83c88eaee5f 100644
--- a/doc/classes/MeshDataTool.xml
+++ b/doc/classes/MeshDataTool.xml
@@ -318,6 +318,7 @@
 			<param index="1" name="tangent" type="Plane" />
 			<description>
 				Sets the tangent of the given vertex.
+				[b]Note:[/b] Even though [param tangent] is a [Plane], it does not directly represent the tangent plane. Its [member Plane.x], [member Plane.y], and [member Plane.z] represent the tangent vector and [member Plane.d] should be either [code]-1[/code] or [code]1[/code]. See also [constant Mesh.ARRAY_TANGENT].
 			</description>
 		</method>
 		<method name="set_vertex_uv">
diff --git a/doc/classes/SurfaceTool.xml b/doc/classes/SurfaceTool.xml
index 0fdc7e77236..7952898d4e2 100644
--- a/doc/classes/SurfaceTool.xml
+++ b/doc/classes/SurfaceTool.xml
@@ -258,6 +258,7 @@
 			<param index="0" name="tangent" type="Plane" />
 			<description>
 				Specifies a tangent to use for the [i]next[/i] vertex. If every vertex needs to have this information set and you fail to submit it for the first vertex, this information may not be used at all.
+				[b]Note:[/b] Even though [param tangent] is a [Plane], it does not directly represent the tangent plane. Its [member Plane.x], [member Plane.y], and [member Plane.z] represent the tangent vector and [member Plane.d] should be either [code]-1[/code] or [code]1[/code]. See also [constant Mesh.ARRAY_TANGENT].
 			</description>
 		</method>
 		<method name="set_uv">