From 69617a893e739dde933490e2e78e3fe304b62184 Mon Sep 17 00:00:00 2001
From: Hugo Locurcio <hugo.locurcio@hugo.pro>
Date: Fri, 21 Jan 2022 19:57:52 +0100
Subject: [PATCH] Improve CSGPolygon3D documentation

- Describe why polygon triangulation usually fails in the error message.
---
 modules/csg/csg_shape.cpp                | 2 +-
 modules/csg/doc_classes/CSGMesh3D.xml    | 2 +-
 modules/csg/doc_classes/CSGPolygon3D.xml | 5 +++--
 3 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/modules/csg/csg_shape.cpp b/modules/csg/csg_shape.cpp
index 41b4682c842..4b36bca02ac 100644
--- a/modules/csg/csg_shape.cpp
+++ b/modules/csg/csg_shape.cpp
@@ -1694,7 +1694,7 @@ CSGBrush *CSGPolygon3D::_build_brush() {
 	}
 	int shape_sides = shape_polygon.size();
 	Vector<int> shape_faces = Geometry2D::triangulate_polygon(shape_polygon);
-	ERR_FAIL_COND_V_MSG(shape_faces.size() < 3, brush, "Failed to triangulate CSGPolygon");
+	ERR_FAIL_COND_V_MSG(shape_faces.size() < 3, brush, "Failed to triangulate CSGPolygon. Make sure the polygon doesn't have any intersecting edges.");
 
 	// Get polygon enclosing Rect2.
 	Rect2 shape_rect(shape_polygon[0], Vector2());
diff --git a/modules/csg/doc_classes/CSGMesh3D.xml b/modules/csg/doc_classes/CSGMesh3D.xml
index 28103431396..42fcb7bd2bd 100644
--- a/modules/csg/doc_classes/CSGMesh3D.xml
+++ b/modules/csg/doc_classes/CSGMesh3D.xml
@@ -4,7 +4,7 @@
 		A CSG Mesh shape that uses a mesh resource.
 	</brief_description>
 	<description>
-		This CSG node allows you to use any mesh resource as a CSG shape, provided it is closed, does not self-intersect, does not contain internal faces and has no edges that connect to more than two faces.
+		This CSG node allows you to use any mesh resource as a CSG shape, provided it is closed, does not self-intersect, does not contain internal faces and has no edges that connect to more than two faces. See also [CSGPolygon3D] for drawing 2D extruded polygons to be used as CSG nodes.
 	</description>
 	<tutorials>
 	</tutorials>
diff --git a/modules/csg/doc_classes/CSGPolygon3D.xml b/modules/csg/doc_classes/CSGPolygon3D.xml
index ecbb7962d1d..5a49eebc7bb 100644
--- a/modules/csg/doc_classes/CSGPolygon3D.xml
+++ b/modules/csg/doc_classes/CSGPolygon3D.xml
@@ -4,7 +4,7 @@
 		Extrudes a 2D polygon shape to create a 3D mesh.
 	</brief_description>
 	<description>
-		An array of 2D points is extruded to quickly and easily create a variety of 3D meshes.
+		An array of 2D points is extruded to quickly and easily create a variety of 3D meshes. See also [CSGMesh3D] for using 3D meshes as CSG nodes.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -46,7 +46,8 @@
 			When [member mode] is [constant MODE_PATH], this is the distance along the path, in meters, the texture coordinates will tile. When set to 0, texture coordinates will match geometry exactly with no tiling.
 		</member>
 		<member name="polygon" type="PackedVector2Array" setter="set_polygon" getter="get_polygon" default="PackedVector2Array(0, 0, 0, 1, 1, 1, 1, 0)">
-			The point array that defines the 2D polygon that is extruded.
+			The point array that defines the 2D polygon that is extruded. This can be a convex or concave polygon with 3 or more points. The polygon must [i]not[/i] have any intersecting edges. Otherwise, triangulation will fail and no mesh will be generated.
+			[b]Note:[/b] If only 1 or 2 points are defined in [member polygon], no mesh will be generated.
 		</member>
 		<member name="smooth_faces" type="bool" setter="set_smooth_faces" getter="get_smooth_faces" default="false">
 			If [code]true[/code], applies smooth shading to the extrusions.