From 1de9118c5fee6201ea1e9eb4be9b00867f536520 Mon Sep 17 00:00:00 2001
From: Hugo Locurcio <hugo.locurcio@hugo.pro>
Date: Fri, 31 Jan 2020 21:19:17 +0100
Subject: [PATCH] doc: Add an example for `Array.sort()`

This may help people understand the difference between alphabetical
and natural order more quickly.
---
 doc/classes/Array.xml | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/doc/classes/Array.xml b/doc/classes/Array.xml
index 5f100d918e1..89ad8e17db0 100644
--- a/doc/classes/Array.xml
+++ b/doc/classes/Array.xml
@@ -322,7 +322,12 @@
 		<method name="sort">
 			<description>
 				Sorts the array.
-				[b]Note:[/b] strings are sorted in alphabetical, not natural order.
+				[b]Note:[/b] Strings are sorted in alphabetical order (as opposed to natural order). This may lead to unexpected behavior when sorting an array of strings ending with a sequence of numbers. Consider the following example:
+				[codeblock]
+				var strings = ["string1", "string2", "string10", "string11"]
+				strings.sort()
+				print(strings) # Prints [string1, string10, string11, string2]
+				[/codeblock]
 			</description>
 		</method>
 		<method name="sort_custom">