From 208700ce41432ec4d7b396c82b532c48d38c4a56 Mon Sep 17 00:00:00 2001
From: Jonathan Nicholl <jonathantnicholl@gmail.com>
Date: Fri, 24 Feb 2023 15:03:35 -0500
Subject: [PATCH] Update documentation for Mesh and MeshInstance3D

Add missing descriptions for Mesh's virtual methods, and
MeshInstance3D's methods relating to blend shapes. Slight tweaks to
several MeshInstance3D method descriptions.
---
 doc/classes/Mesh.xml           | 14 ++++++++++++++
 doc/classes/MeshInstance3D.xml | 13 +++++++++----
 2 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/doc/classes/Mesh.xml b/doc/classes/Mesh.xml
index 3063e76c656..b9e6854bbf4 100644
--- a/doc/classes/Mesh.xml
+++ b/doc/classes/Mesh.xml
@@ -16,22 +16,26 @@
 		<method name="_get_aabb" qualifiers="virtual const">
 			<return type="AABB" />
 			<description>
+				Virtual method to override the [AABB] for a custom class extending [Mesh].
 			</description>
 		</method>
 		<method name="_get_blend_shape_count" qualifiers="virtual const">
 			<return type="int" />
 			<description>
+				Virtual method to override the number of blend shapes for a custom class extending [Mesh].
 			</description>
 		</method>
 		<method name="_get_blend_shape_name" qualifiers="virtual const">
 			<return type="StringName" />
 			<param index="0" name="index" type="int" />
 			<description>
+				Virtual method to override the retrieval of blend shape names for a custom class extending [Mesh].
 			</description>
 		</method>
 		<method name="_get_surface_count" qualifiers="virtual const">
 			<return type="int" />
 			<description>
+				Virtual method to override the surface count for a custom class extending [Mesh].
 			</description>
 		</method>
 		<method name="_set_blend_shape_name" qualifiers="virtual">
@@ -39,54 +43,63 @@
 			<param index="0" name="index" type="int" />
 			<param index="1" name="name" type="StringName" />
 			<description>
+				Virtual method to override the names of blend shapes for a custom class extending [Mesh].
 			</description>
 		</method>
 		<method name="_surface_get_array_index_len" qualifiers="virtual const">
 			<return type="int" />
 			<param index="0" name="index" type="int" />
 			<description>
+				Virtual method to override the surface array index length for a custom class extending [Mesh].
 			</description>
 		</method>
 		<method name="_surface_get_array_len" qualifiers="virtual const">
 			<return type="int" />
 			<param index="0" name="index" type="int" />
 			<description>
+				Virtual method to override the surface array length for a custom class extending [Mesh].
 			</description>
 		</method>
 		<method name="_surface_get_arrays" qualifiers="virtual const">
 			<return type="Array" />
 			<param index="0" name="index" type="int" />
 			<description>
+				Virtual method to override the surface arrays for a custom class extending [Mesh].
 			</description>
 		</method>
 		<method name="_surface_get_blend_shape_arrays" qualifiers="virtual const">
 			<return type="Array[]" />
 			<param index="0" name="index" type="int" />
 			<description>
+				Virtual method to override the blend shape arrays for a custom class extending [Mesh].
 			</description>
 		</method>
 		<method name="_surface_get_format" qualifiers="virtual const">
 			<return type="int" />
 			<param index="0" name="index" type="int" />
 			<description>
+				Virtual method to override the surface format for a custom class extending [Mesh].
 			</description>
 		</method>
 		<method name="_surface_get_lods" qualifiers="virtual const">
 			<return type="Dictionary" />
 			<param index="0" name="index" type="int" />
 			<description>
+				Virtual method to override the surface LODs for a custom class extending [Mesh].
 			</description>
 		</method>
 		<method name="_surface_get_material" qualifiers="virtual const">
 			<return type="Material" />
 			<param index="0" name="index" type="int" />
 			<description>
+				Virtual method to override the surface material for a custom class extending [Mesh].
 			</description>
 		</method>
 		<method name="_surface_get_primitive_type" qualifiers="virtual const">
 			<return type="int" />
 			<param index="0" name="index" type="int" />
 			<description>
+				Virtual method to override the surface primitive type for a custom class extending [Mesh].
 			</description>
 		</method>
 		<method name="_surface_set_material" qualifiers="virtual">
@@ -94,6 +107,7 @@
 			<param index="0" name="index" type="int" />
 			<param index="1" name="material" type="Material" />
 			<description>
+				Virtual method to override the setting of a [param material] at the given [param index] for a custom class extending [Mesh].
 			</description>
 		</method>
 		<method name="create_convex_shape" qualifiers="const">
diff --git a/doc/classes/MeshInstance3D.xml b/doc/classes/MeshInstance3D.xml
index 618503c8df3..2ee3b4cb0ce 100644
--- a/doc/classes/MeshInstance3D.xml
+++ b/doc/classes/MeshInstance3D.xml
@@ -45,31 +45,35 @@
 			<return type="int" />
 			<param index="0" name="name" type="StringName" />
 			<description>
+				Returns the index of the blend shape with the given [param name]. Returns [code]-1[/code] if no blend shape with this name exists, including when [member mesh] is [code]null[/code].
 			</description>
 		</method>
 		<method name="get_active_material" qualifiers="const">
 			<return type="Material" />
 			<param index="0" name="surface" type="int" />
 			<description>
-				Returns the [Material] that will be used by the [Mesh] when drawing. This can return the [member GeometryInstance3D.material_override], the surface override [Material] defined in this [MeshInstance3D], or the surface [Material] defined in the [Mesh]. For example, if [member GeometryInstance3D.material_override] is used, all surfaces will return the override material.
+				Returns the [Material] that will be used by the [Mesh] when drawing. This can return the [member GeometryInstance3D.material_override], the surface override [Material] defined in this [MeshInstance3D], or the surface [Material] defined in the [member mesh]. For example, if [member GeometryInstance3D.material_override] is used, all surfaces will return the override material.
+				Returns [code]null[/code] if no material is active, including when [member mesh] is [code]null[/code].
 			</description>
 		</method>
 		<method name="get_blend_shape_count" qualifiers="const">
 			<return type="int" />
 			<description>
+				Returns the number of blend shapes available. Produces an error if [member mesh] is [code]null[/code].
 			</description>
 		</method>
 		<method name="get_blend_shape_value" qualifiers="const">
 			<return type="float" />
 			<param index="0" name="blend_shape_idx" type="int" />
 			<description>
+				Returns the value of the blend shape at the given [param blend_shape_idx]. Returns [code]0.0[/code] and produces an error if [member mesh] is [code]null[/code] or doesn't have a blend shape at that index.
 			</description>
 		</method>
 		<method name="get_surface_override_material" qualifiers="const">
 			<return type="Material" />
 			<param index="0" name="surface" type="int" />
 			<description>
-				Returns the override [Material] for the specified surface of the [Mesh] resource.
+				Returns the override [Material] for the specified [param surface] of the [Mesh] resource.
 			</description>
 		</method>
 		<method name="get_surface_override_material_count" qualifiers="const">
@@ -83,6 +87,7 @@
 			<param index="0" name="blend_shape_idx" type="int" />
 			<param index="1" name="value" type="float" />
 			<description>
+				Sets the value of the blend shape at [param blend_shape_idx] to [param value]. Produces an error if [member mesh] is [code]null[/code] or doesn't have a blend shape at that index.
 			</description>
 		</method>
 		<method name="set_surface_override_material">
@@ -90,7 +95,7 @@
 			<param index="0" name="surface" type="int" />
 			<param index="1" name="material" type="Material" />
 			<description>
-				Sets the override [Material] for the specified surface of the [Mesh] resource. This material is associated with this [MeshInstance3D] rather than with the [Mesh] resource.
+				Sets the override [param material] for the specified [param surface] of the [Mesh] resource. This material is associated with this [MeshInstance3D] rather than with [member mesh].
 			</description>
 		</method>
 	</methods>
@@ -102,7 +107,7 @@
 			[NodePath] to the [Skeleton3D] associated with the instance.
 		</member>
 		<member name="skin" type="Skin" setter="set_skin" getter="get_skin">
-			Sets the skin to be used by this instance.
+			The [Skin] to be used by this instance.
 		</member>
 	</members>
 </class>