Improve `range_lerp()` and related methods documentation

3 files changed, 8 insertions, 5 deletions

diff --git a/doc/classes/@GlobalScope.xml b/doc/classes/@GlobalScope.xml
index d647621362..4a16244235 100644
--- a/doc/classes/@GlobalScope.xml
+++ b/doc/classes/@GlobalScope.xml
@@ -380,7 +380,7 @@
 			<argument index="1" name="to" type="float" />
 			<argument index="2" name="weight" type="float" />
 			<description>
-				Returns an interpolation or extrapolation factor considering the range specified in [code]from[/code] and [code]to[/code], and the interpolated value specified in [code]weight[/code]. The returned value will be between [code]0.0[/code] and [code]1.0[/code] if [code]weight[/code] is between [code]from[/code] and [code]to[/code] (inclusive). If [code]weight[/code] is located outside this range, then an extrapolation factor will be returned (return value lower than [code]0.0[/code] or greater than [code]1.0[/code]).
+				Returns an interpolation or extrapolation factor considering the range specified in [code]from[/code] and [code]to[/code], and the interpolated value specified in [code]weight[/code]. The returned value will be between [code]0.0[/code] and [code]1.0[/code] if [code]weight[/code] is between [code]from[/code] and [code]to[/code] (inclusive). If [code]weight[/code] is located outside this range, then an extrapolation factor will be returned (return value lower than [code]0.0[/code] or greater than [code]1.0[/code]). Use [method clamp] on the result of [method inverse_lerp] if this is not desired.
 				[codeblock]
 				# The interpolation ratio in the `lerp()` call below is 0.75.
 				var middle = lerp(20, 30, 0.75)
@@ -389,7 +389,7 @@
 				var ratio = inverse_lerp(20, 30, 27.5)
 				# `ratio` is now 0.75.
 				[/codeblock]
-				See also [method lerp] which performs the reverse of this operation.
+				See also [method lerp] which performs the reverse of this operation, and [method range_lerp] to map a continuous series of values to another.
 			</description>
 		</method>
 		<method name="is_equal_approx">
@@ -444,11 +444,11 @@
 			<argument index="1" name="to" type="float" />
 			<argument index="2" name="weight" type="float" />
 			<description>
-				Linearly interpolates between two values by the factor defined in [code]weight[/code]. To perform interpolation, [code]weight[/code] should be between [code]0.0[/code] and [code]1.0[/code] (inclusive). However, values outside this range are allowed and can be used to perform [i]extrapolation[/i].
+				Linearly interpolates between two values by the factor defined in [code]weight[/code]. To perform interpolation, [code]weight[/code] should be between [code]0.0[/code] and [code]1.0[/code] (inclusive). However, values outside this range are allowed and can be used to perform [i]extrapolation[/i]. Use [method clamp] on the result of [method lerp] if this is not desired.
 				[codeblock]
 				lerp(0, 4, 0.75) # Returns 3.0
 				[/codeblock]
-				See also [method inverse_lerp] which performs the reverse of this operation. To perform eased interpolation with [method lerp], combine it with [method ease] or [method smoothstep].
+				See also [method inverse_lerp] which performs the reverse of this operation. To perform eased interpolation with [method lerp], combine it with [method ease] or [method smoothstep]. See also [method range_lerp] to map a continuous series of values to another.
 			</description>
 		</method>
 		<method name="lerp_angle">
@@ -807,10 +807,11 @@
 			<argument index="3" name="ostart" type="float" />
 			<argument index="4" name="ostop" type="float" />
 			<description>
-				Maps a [code]value[/code] from range [code][istart, istop][/code] to [code][ostart, ostop][/code].
+				Maps a [code]value[/code] from range [code][istart, istop][/code] to [code][ostart, ostop][/code]. See also [method lerp] and [method inverse_lerp]. If [code]value[/code] is outside [code][istart, istop][/code], then the resulting value will also be outside [code][ostart, ostop][/code]. Use [method clamp] on the result of [method range_lerp] if this is not desired.
 				[codeblock]
 				range_lerp(75, 0, 100, -1, 1) # Returns 0.5
 				[/codeblock]
+				For complex use cases where you need multiple ranges, consider using [Curve] or [Gradient] instead.
 			</description>
 		</method>
 		<method name="rid_allocate_id">
diff --git a/doc/classes/Curve.xml b/doc/classes/Curve.xml
index 383d33532b..179b0344c2 100644
--- a/doc/classes/Curve.xml
+++ b/doc/classes/Curve.xml
@@ -5,6 +5,7 @@
 	</brief_description>
 	<description>
 		A curve that can be saved and re-used for other objects. By default, it ranges between [code]0[/code] and [code]1[/code] on the Y axis and positions points relative to the [code]0.5[/code] Y position.
+		See also [Gradient] which is designed for color interpolation. See also [Curve2D] and [Curve3D].
 	</description>
 	<tutorials>
 	</tutorials>
diff --git a/doc/classes/Gradient.xml b/doc/classes/Gradient.xml
index 89c968cc9e..8c5373216a 100644
--- a/doc/classes/Gradient.xml
+++ b/doc/classes/Gradient.xml
@@ -5,6 +5,7 @@
 	</brief_description>
 	<description>
 		Given a set of colors, this resource will interpolate them in order. This means that if you have color 1, color 2 and color 3, the gradient will interpolate from color 1 to color 2 and from color 2 to color 3. The gradient will initially have 2 colors (black and white), one (black) at gradient lower offset 0 and the other (white) at the gradient higher offset 1.
+		See also [Curve] which supports more complex easing methods, but does not support colors.
 	</description>
 	<tutorials>
 	</tutorials>