improve documentation of SurfaceTool (#6405)

* improve documentation of SurfaceTool

* add suggestion from @clayjohn

Author: pseidemann

tutorials/3d/procedural_geometry/surfacetool.rst

@@ -15,6 +15,10 @@ Attributes are added before each vertex is added:
 .. tabs::
  .. code-tab:: gdscript GDScript
 
+    var st = SurfaceTool.new()
+
+    st.begin(Mesh.PRIMITIVE_TRIANGLES)
+
     st.set_normal() # Overwritten by normal below.
     st.set_normal() # Added to next vertex.
     st.set_color() # Added to next vertex.
@@ -29,16 +33,20 @@ Attributes are added before each vertex is added:
     st.AddVertex(); // Captures normal and color above.
     st.SetNormal(); // Normal never added to a vertex.
 
-When finished generating your geometry with the :ref:`SurfaceTool <class_surfacetool>`
+When finished generating your geometry with the :ref:`SurfaceTool <class_surfacetool>`,
 call ``commit()`` to finish generating the mesh. If an :ref:`ArrayMesh <class_ArrayMesh>` is passed
-to ``commit()`` then it appends a new surface to the end of the ArrayMesh. While if nothing is passed
+to ``commit()``, then it appends a new surface to the end of the ArrayMesh. While if nothing is passed
 in, ``commit()`` returns an ArrayMesh.
 
 .. tabs::
  .. code-tab:: gdscript GDScript
 
+    # Add surface to existing ArrayMesh.
     st.commit(mesh)
-    # Or:
+
+    # -- Or Alternatively --
+
+    # Create new ArrayMesh.
     var mesh = st.commit()
 
  .. code-tab:: csharp
@@ -47,7 +55,7 @@ in, ``commit()`` returns an ArrayMesh.
     // Or:
     var mesh = st.Commit();
 
-Code creates a triangle with indices
+The code below creates a triangle without indices.
 
 .. tabs::
  .. code-tab:: gdscript GDScript
@@ -97,14 +105,37 @@ Code creates a triangle with indices
     var mesh = st.Commit();
 
 You can optionally add an index array, either by calling ``add_index()`` and adding
-vertices to the index array or by calling ``index()`` which shrinks the vertex array
-to remove duplicate vertices.
+vertices to the index array manually, or by calling ``index()`` once,
+which generates the index array automatically and
+shrinks the vertex array to remove duplicate vertices.
 
 .. tabs::
  .. code-tab:: gdscript GDScript
+    # Suppose we have a quad defined by 6 vertices as follows
+    st.add_vertex(Vector3(-1, 1, 0))
+    st.add_vertex(Vector3(1, 1, 0))
+    st.add_vertex(Vector3(-1, -1, 0))
+
+    st.add_vertex(Vector3(1, 1, 0))
+    st.add_vertex(Vector3(1, -1, 0))
+    st.add_vertex(Vector3(-1, -1, 0))
+
+    # We can make the quad more efficient by using an index array and only utilizing 4 vertices
+
+    # Suppose we have a quad defined by 6 vertices as follows
+    st.add_vertex(Vector3(-1, 1, 0))
+    st.add_vertex(Vector3(1, 1, 0))
+    st.add_vertex(Vector3(-1, -1, 0))
+
+    st.add_vertex(Vector3(1, 1, 0))
+    st.add_vertex(Vector3(1, -1, 0))
+    st.add_vertex(Vector3(-1, -1, 0))
+
+    # We can make the quad more efficient by using an index array and only utilizing 4 vertices
 
     # Creates a quad from four corner vertices.
-    # add_index does not need to be called before add_vertex.
+    # add_index() can be called before or after add_vertex()
+    # since it's not an attribute of a vertex itself.
     st.add_index(0)
     st.add_index(1)
     st.add_index(2)
@@ -113,7 +144,7 @@ to remove duplicate vertices.
     st.add_index(3)
     st.add_index(2)
 
-    # Alternatively:
+    # Alternatively we can use ``st.index()`` which will create the quad for us and remove the duplicate vertices
     st.index()
 
  .. code-tab:: csharp
@@ -161,12 +192,15 @@ normals set already.
     st.generate_normals()
     st.generate_tangents()
 
+    st.commit(mesh)
+
  .. code-tab:: csharp
 
     st.GenerateNormals();
     st.GenerateTangents();
 
-By default, when generating normals, they will be calculated on a per-face basis. If you want
-smooth vertex normals, when adding vertices, call ``add_smooth_group()``. ``add_smooth_group()``
-needs to be called while building the geometry, e.g. before the call to ``add_vertex()``
-(if non-indexed) or ``add_index()`` (if indexed).
+By default, when generating normals, they will be calculated on a per-vertex basis (i.e. they will
+be "smooth normals"). If you want flat vertex normals (i.e. a single normal vector per face), when
+adding vertices, call ``add_smooth_group(i)`` where ``i`` is a unique number per vertex.
+``add_smooth_group()`` needs to be called while building the geometry, e.g. before the call to
+``add_vertex()``.