godotengine / godotengine/godot-docs

Improve `CodeEdit` documentation

Open
#11,402 5 comments 0 reactions 0 assignees View on GitHub
area:class reference enhancement
Dominant language
reStructuredText
Stars
5.7k
Forks
3.8k
Avg merge
1d 20h
Merged PRs (30d)
25

Description

**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.
Screenshot Godot's script editor. It shows a function call with a hint showing which arguments are expected. The parameter under the caret highlighted
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:
```gdscript
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](https://github.com/godotengine/godot/blob/0fdbf050e0c7fc7e0a9d42c2a41ee3bfdffbd8f1/scene/gui/code_edit.cpp#L3772C1-L3772C73) 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

[`CodeEdit`]: https://docs.godotengine.org/en/stable/classes/class_codeedit.html
[`_request_code_completion`]: https://docs.godotengine.org/en/stable/classes/class_codeedit.html#class-codeedit-private-method-request-code-completion
[`add_code_completion_option`]: https://docs.godotengine.org/en/stable/classes/class_codeedit.html#class-codeedit-method-add-code-completion-option
[`add_comment_delimiter`]: https://docs.godotengine.org/en/stable/classes/class_codeedit.html#class-codeedit-method-add-comment-delimiter
[`add_string_delimiter`]: https://docs.godotengine.org/en/stable/classes/class_codeedit.html#class-codeedit-method-add-string-delimiter
[`update_code_completion_options`]: https://docs.godotengine.org/en/stable/classes/class_codeedit.html#class-codeedit-method-update-code-completion-options
[`set_code_hint`]: https://docs.godotengine.org/en/stable/classes/class_codeedit.html#class-codeedit-method-set-code-hint
[`_filter_code_completion_candidates`]: https://docs.godotengine.org/en/stable/classes/class_codeedit.html#class-codeedit-private-method-filter-code-completion-candidates

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the CodeEdit class documentation page and the referenced scene/gui/code_edit.cpp sections for _request_code_completion, set_code_hint, delimiters, and candidate filtering. Confirm the documented behavior against those source references, then update the relevant method descriptions so the force checks, hint markers, delimiter matching, and default sorting are explicit; done means all four listed gaps are covered.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.