godotengine / godotengine/godot-docs
Improve `CodeEdit` documentation
- 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.
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