From 35bdd8eae412deee5cbb2366d37435b089a6f06b Mon Sep 17 00:00:00 2001
From: Danil Alexeev <danil@alexeev.xyz>
Date: Tue, 10 Jan 2023 09:50:48 +0300
Subject: [PATCH] Improve `SpriteFrames` docs

---
 doc/classes/AnimatedSprite2D.xml |  1 -
 doc/classes/SpriteFrames.xml     | 21 ++++++++++-----------
 2 files changed, 10 insertions(+), 12 deletions(-)

diff --git a/doc/classes/AnimatedSprite2D.xml b/doc/classes/AnimatedSprite2D.xml
index e20fb71c7ea..cd9c0cee98b 100644
--- a/doc/classes/AnimatedSprite2D.xml
+++ b/doc/classes/AnimatedSprite2D.xml
@@ -7,7 +7,6 @@
 		[AnimatedSprite2D] is similar to the [Sprite2D] node, except it carries multiple textures as animation frames. Animations are created using a [SpriteFrames] resource, which allows you to import image files (or a folder containing said files) to provide the animation frames for the sprite. The [SpriteFrames] resource can be configured in the editor via the SpriteFrames bottom panel.
 		After setting up [member frames], [method play] may be called. It's also possible to select an [member animation] and toggle [member playing], even within the editor.
 		To pause the current animation, set [member playing] to [code]false[/code]. Alternatively, setting [member speed_scale] to [code]0[/code] also preserves the current frame's elapsed time.
-		[b]Note:[/b] You can associate a set of normal or specular maps by creating additional [SpriteFrames] resources with a [code]_normal[/code] or [code]_specular[/code] suffix. For example, having 3 [SpriteFrames] resources [code]run[/code], [code]run_normal[/code], and [code]run_specular[/code] will make it so the [code]run[/code] animation uses normal and specular maps.
 	</description>
 	<tutorials>
 		<link title="2D Sprite animation">$DOCS_URL/tutorials/2d/2d_sprite_animation.html</link>
diff --git a/doc/classes/SpriteFrames.xml b/doc/classes/SpriteFrames.xml
index 87b823bd2a7..195f3598d53 100644
--- a/doc/classes/SpriteFrames.xml
+++ b/doc/classes/SpriteFrames.xml
@@ -5,7 +5,6 @@
 	</brief_description>
 	<description>
 		Sprite frame library for an [AnimatedSprite2D] or [AnimatedSprite3D] node. Contains frames and animation data for playback.
-		[b]Note:[/b] You can associate a set of normal or specular maps by creating additional [SpriteFrames] resources with a [code]_normal[/code] or [code]_specular[/code] suffix. For example, having 3 [SpriteFrames] resources [code]run[/code], [code]run_normal[/code], and [code]run_specular[/code] will make it so the [code]run[/code] animation uses normal and specular maps.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -14,7 +13,7 @@
 			<return type="void" />
 			<param index="0" name="anim" type="StringName" />
 			<description>
-				Adds a new animation to the library.
+				Adds a new [param anim] animation to the library.
 			</description>
 		</method>
 		<method name="add_frame">
@@ -24,20 +23,20 @@
 			<param index="2" name="duration" type="float" default="1.0" />
 			<param index="3" name="at_position" type="int" default="-1" />
 			<description>
-				Adds a frame to the given animation.
+				Adds a frame to the [param anim] animation. If [param at_position] is [code]-1[/code], the frame will be added to the end of the animation.
 			</description>
 		</method>
 		<method name="clear">
 			<return type="void" />
 			<param index="0" name="anim" type="StringName" />
 			<description>
-				Removes all frames from the given animation.
+				Removes all frames from the [param anim] animation.
 			</description>
 		</method>
 		<method name="clear_all">
 			<return type="void" />
 			<description>
-				Removes all animations. A "default" animation will be created.
+				Removes all animations. An empty [code]default[/code] animation will be created.
 			</description>
 		</method>
 		<method name="get_animation_loop" qualifiers="const">
@@ -91,14 +90,14 @@
 			<return type="bool" />
 			<param index="0" name="anim" type="StringName" />
 			<description>
-				If [code]true[/code], the named animation exists.
+				Returns [code]true[/code] if the [param anim] animation exists.
 			</description>
 		</method>
 		<method name="remove_animation">
 			<return type="void" />
 			<param index="0" name="anim" type="StringName" />
 			<description>
-				Removes the given animation.
+				Removes the [param anim] animation.
 			</description>
 		</method>
 		<method name="remove_frame">
@@ -106,7 +105,7 @@
 			<param index="0" name="anim" type="StringName" />
 			<param index="1" name="idx" type="int" />
 			<description>
-				Removes the animation's selected frame.
+				Removes the [param anim] animation's frame [param idx].
 			</description>
 		</method>
 		<method name="rename_animation">
@@ -114,7 +113,7 @@
 			<param index="0" name="anim" type="StringName" />
 			<param index="1" name="newname" type="StringName" />
 			<description>
-				Changes the animation's name to [param newname].
+				Changes the [param anim] animation's name to [param newname].
 			</description>
 		</method>
 		<method name="set_animation_loop">
@@ -122,7 +121,7 @@
 			<param index="0" name="anim" type="StringName" />
 			<param index="1" name="loop" type="bool" />
 			<description>
-				If [code]true[/code], the animation will loop.
+				If [param loop] is [code]true[/code], the [param anim] animation will loop when it reaches the end, or the start if it is played in reverse.
 			</description>
 		</method>
 		<method name="set_animation_speed">
@@ -140,7 +139,7 @@
 			<param index="2" name="texture" type="Texture2D" />
 			<param index="3" name="duration" type="float" default="1.0" />
 			<description>
-				Sets the texture and the duration of the frame [param idx] in the [param anim] animation.
+				Sets the [param texture] and the [param duration] of the frame [param idx] in the [param anim] animation.
 			</description>
 		</method>
 	</methods>