Godot引擎中Array.sort_custom()方法文档描述修正说明

在Godot游戏引擎4.3版本的文档中，Array类的sort_custom()方法存在一个描述上的不一致问题。该方法用于通过自定义比较函数对数组进行排序，但在引擎内置帮助文档和在线文档中对比较函数返回值的解释存在差异。

问题描述

在Godot 4.3稳定版(v4.3.stable.official.77dcf97d8)的内置帮助文档中，sort_custom()方法的描述为：

"func被调用多次，接收两个数组元素作为参数。当函数返回true时，表示第一个元素应该移动到第二个元素的后面，否则返回false。"

而在官方在线文档中，同一方法的描述为：

"func被调用多次，接收两个数组元素作为参数。当函数返回true时，表示第一个元素应该移动到第二个元素的前面，否则返回false。"

技术分析

这种描述上的差异主要源于对"behind"(后面)和"before"(前面)这两个术语在数组排序上下文中的不同理解。在数组排序的上下文中：

1. "前面"(before)通常指数组中较小的索引位置(更靠前)
2. "后面"(behind)通常指数组中较大的索引位置(更靠后)

使用"before"术语更加符合编程社区对排序算法的常规理解，也更容易被开发者直观理解。而"behind"则相对容易引起混淆，特别是在处理升序/降序排序时。

影响范围

这个文档问题会影响开发者在使用自定义排序时的预期行为理解，可能导致排序结果与预期不符。不过值得注意的是，这只是一个文档描述问题，实际的排序算法实现是正确的。

解决方案

Godot开发团队已经注意到这个问题并在后续版本中进行了修正，统一采用"before"这一更清晰明确的术语来描述该方法的行为。这个修正将被回溯应用到较早的版本中。

对于开发者而言，建议参考在线文档的描述来理解和使用sort_custom()方法，因为在线文档会保持最新的修正内容。在编写自定义排序函数时，记住返回true表示第一个参数应该排在第二个参数之前(更小的索引位置)。