Improve documentation/error on Array.sort_custom() function comparison
#104944
+6
−4
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Calinou
added
enhancement
cherrypick:4.3
Calinou
force-pushed
the
doc-array-sort-function-equal
branch
from
e0f4624 to
8bf20eb
Compare
Mickeon
reviewed
Apr 9, 2025
Comment on lines
291
to
+292
| Similar to [method sort_custom], [param func] is called as many times as necessary, receiving one array element and [param value] as arguments. The function should return [code]true[/code] if the array element should be [i]behind[/i] [param value], otherwise it should return [code]false[/code]. | ||
| If the order of the two elements does not matter (e.g. they are equal), it should return [code]false[/code]. This means that for comparisons, [code]<[/code] or [code]>[/code] should always be used instead of [code]<=[/code] or [code]>=[/code]. If this rule is not followed, an error is printed as sorting will be broken. |
There was a problem hiding this comment.
I personally feel like this is an overcorrection. The current PR adds a tip smacked right in the middle of the details, which is a bit noisy to the reader.
Suggested change
| Similar to [method sort_custom], [param func] is called as many times as necessary, receiving one array element and [param value] as arguments. The function should return [code]true[/code] if the array element should be [i]behind[/i] [param value], otherwise it should return [code]false[/code]. | |
| If the order of the two elements does not matter (e.g. they are equal), it should return [code]false[/code]. This means that for comparisons, [code]<[/code] or [code]>[/code] should always be used instead of [code]<=[/code] or [code]>=[/code]. If this rule is not followed, an error is printed as sorting will be broken. | |
| Similar to [method sort_custom], [param func] is called as many times as necessary, receiving one array element and [param value] as arguments. The function should return [code]true[/code] if the array element should be [i]behind[/i] [param value], otherwise it should return [code]false[/code]. If the two elements are considered equivalent, it should also return [code]false[/code]. |
If absolutely necessary, the additional explanation should be a note below. Although, it is my opinion that, while correct, it may be an oversimplification to address the error.
Comment also applies to sort_custom's description below.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Array.sort_customcallable requirements more explicit for thea == bcase godot-docs#10816.