Improve `CodeEdit` documentation

[MatthijsMud]

Your Godot version:
4.4

Issue description:

While working on a plugin that uses a CodeEdit I found the documentation of it to be a bit sparse.

• _request_code_completion takes a boolean argument (force), but the description for it isn't particularly helpful

  If force is true, any checks should be bypassed.

  It does not specify what those checks entail:

  • Are those checks internal, with the parameter as an implementation detail?
  • Should the list of suggestions be populated with options that make no sense in the current context? (for example suggesting keywords like class_name and var as parameters for a function call)
  • Is it only intended to be passed to update_code_completion_options which also expects a parameter named force?

• set_code_hint has an undocumented feature for aligning the hint to the caret and highlighting a part of it, similar to how the current parameter is highlighted in Godot's script editor.
  
  It aligns the first occurrence of char(0xFFFF) in the hint with the caret (only on the first line). For each line it highlights all text between the first and last occurrence of char(0xFFFFF) on that line. The following code would replicate the hint in the screenshot:

  set_code_hint("type_convert(" + char(0xFFFF) + "variant: Variant" + char(0xFFFF) + ",  type: int)")

  Relevant Godot source code implementing this feature

  https://github.com/godotengine/godot/blob/9cd297b6f2a0ee660b8f1a6b385582cccf3a9d10/scene/gui/code_edit.cpp#L95-L134

• add_comment_delimiter and add_string_delimiter might cause some confusion about whether a similar start_key is allowed. For example: Godot uses quotes ('/") to denote the start (and end) of a string; three consecutive quotes are used for multi-line strings. This would indicate that only exact matches are considered.

  start_key must not be shared with other delimiters.

• _filter_code_completion_candidates also sorts the options if no custom implementation has been provided. Users might be able to figure this out, but I feel it is worth pointing it out in the documentation. A different method (or Callable property) might be a more suitable location when changing the API.

URL to the documentation page (if already existing):
https://docs.godotengine.org/en/stable/classes/class_codeedit.html

[Calinou]

cc @dalexeev @kitbdev

[dalexeev]

• set_code_hint has an undocumented feature for aligning the hint to the caret and highlighting a part of it, similar to how the current parameter is highlighted in Godot's script editor.

Yes, it is not properly documented, but a similar use of the 0xFFFF character is mentioned:

String get_text_for_code_completion() const
    Returns the full text with char 0xFFFF at the caret location.

String get_text_for_symbol_lookup() const
    Returns the full text with char 0xFFFF at the cursor location.

String get_text_with_cursor_char(line: int, column: int) const
    Returns the full text with char 0xFFFF at the specified location.

CC @HolonProduction Since you are more familiar with autocompletion.

[HolonProduction]

First of all I did make some bulletpoints on the current behaviour regarding completion in godotengine/godot-proposals#10550 (not exhaustive though and mainly focuses on request_code_completion signal vs _request_code_completion virtual method.

• The force parameter to _request_code_completion is simply forwarded from request_code_completion which you are calling manually, it's somewhat documented there. The documented checks are only applied when not having the virtual method though. Internally it is used to indicate whether the user explicitly requested completion using a shortcut, or whether the request originates from a more "soft" source like simply typing. When not using the virtual method, Godot does bypass the code completion prefix checks before emitting the signal, when it is true. -> Due to the very limited scope of completion prefixes it might be totally possible that those checks are not relevant for the GDScript editor anymore and could be removed.
  For user code, I would recommend using the virtual method and ignoring it completely. Having completion behave differently when explicitly requested can lead to bad UX. In the long run we should deprecate it IMO. -> for an IMO better structured triggering API see the above proposal
• The force parameter to update_code_completion_options is only used for one very arbitrary check (when false you can't display options after an opened brace (), that probably dates back to when CodeEdit and GDScript were more tightly coupled. For user code I would recommend to always set it to true. I also suspect that the check isn't relevant for GDScript functionality anymore and it could be removed completely.

[MatthijsMud]

The opening post has been updated to point out that, by default, _filter_code_completion_candidates also reorders the list. Though a point could be made not to document it, in favor of implementing a custom sorting method with a more appropriate name (such that it is not considered a "breaking" change).

---

First of all I did make some bulletpoints on the current behaviour regarding completion in godotengine/godot-proposals#10550 (not exhaustive though and mainly focuses on request_code_completion signal vs _request_code_completion virtual method.

Missed that point when looking through existing issues as I only checked the documentation repository for mentions of CodeEdit. The need for expanding on documentation of the force parameter becomes less pressing if the intention is to remove it.

[HolonProduction]

The need for expanding on documentation of the force parameter becomes less pressing if the intention is to remove it.

I have no say on this part of the code, it's just my very personal opinion. Also I don't think force can be removed.

I just think that it would make sense to clearly split the API into a triggering part and an listing options part. force should only be relevant to triggering e.g. when using braces (|) you should get completion when requesting completion, but triggering completion when typing ( might get in the way.
But giving force an influence on the option listing should be avoided IMO.