summaryrefslogtreecommitdiff
path: root/ted.h
diff options
context:
space:
mode:
Diffstat (limited to 'ted.h')
-rw-r--r--ted.h191
1 files changed, 114 insertions, 77 deletions
diff --git a/ted.h b/ted.h
index c8aaf71..c7bb45b 100644
--- a/ted.h
+++ b/ted.h
@@ -97,6 +97,7 @@ enum SyntaxCharType {
/// Type of syntax highlighting.
typedef u8 SyntaxCharType;
/// Function for syntax highlighting.
+///
/// If you want to add a language to `ted`, you will need to implement this function.
///
/// `state` is used to keep track of state between lines (e.g. whether or not we are in a multiline comment)\n
@@ -116,7 +117,7 @@ typedef void (*SyntaxHighlightFunction)(SyntaxState *state, const char32_t *line
/// for markdown
#define SYNTAX_LINK SYNTAX_CONSTANT
-/// Settings
+/// All of ted's settings
typedef struct Settings Settings;
/// A buffer - this includes line buffers, unnamed buffers, the build buffer, etc.
@@ -318,12 +319,14 @@ typedef u64 EditNotifyID;
// === buffer.c ===
/// Returns `true` if the buffer is in view-only mode.
bool buffer_is_view_only(TextBuffer *buffer);
-/// Set whether the buffer should be in view only mode.
+/// Set whether the buffer should be in view-only mode.
void buffer_set_view_only(TextBuffer *buffer, bool view_only);
/// amount scrolled horizontally, in terms of the width of a space character
double buffer_get_scroll_columns(TextBuffer *buffer);
-///n number of lines scrolled vertically
+/// number of lines scrolled vertically
double buffer_get_scroll_lines(TextBuffer *buffer);
+/// set scroll position
+void buffer_scroll_to(TextBuffer *buffer, double cols, double lines);
/// get last time buffer was written to, in the format of \ref time_get_seconds
double buffer_last_write_time(TextBuffer *buffer);
/// get position of the cursor
@@ -375,7 +378,7 @@ void line_buffer_clear_submitted(TextBuffer *buffer);
char32_t buffer_char_at_pos(TextBuffer *buffer, BufferPos pos);
/// returns the character after the cursor, or 0 if the cursor is at the end of a line
char32_t buffer_char_at_cursor(TextBuffer *buffer);
-/// returns the character before position `pos`, or 0 if pos is invalid or at the start of a line
+/// returns the character before position `pos`, or 0 if `pos` is invalid or at the start of a line
char32_t buffer_char_before_pos(TextBuffer *buffer, BufferPos pos);
/// returns the character to the left of the cursor, or 0 if the cursor at the start of the line.
char32_t buffer_char_before_cursor(TextBuffer *buffer);
@@ -383,9 +386,13 @@ char32_t buffer_char_before_cursor(TextBuffer *buffer);
BufferPos buffer_pos_start_of_file(TextBuffer *buffer);
/// buffer position of end of file
BufferPos buffer_pos_end_of_file(TextBuffer *buffer);
-/// move position to matching bracket. returns the matching bracket character if there is one, otherwise returns 0 and does nothing.
+/// move position to matching bracket.
+///
+/// \returns the matching bracket character if there is one, or 0 otherwise.
char32_t buffer_pos_move_to_matching_bracket(TextBuffer *buffer, BufferPos *pos);
-/// move cursor to matching bracket. returns true if cursor was to the right of a bracket.
+/// move cursor to matching bracket.
+///
+/// \returns `true` if cursor was to the right of a bracket.
bool buffer_cursor_move_to_matching_bracket(TextBuffer *buffer);
/// ensures that `p` refers to a valid position, moving it if needed.
void buffer_pos_validate(TextBuffer *buffer, BufferPos *p);
@@ -393,7 +400,9 @@ void buffer_pos_validate(TextBuffer *buffer, BufferPos *p);
bool buffer_pos_valid(TextBuffer *buffer, BufferPos p);
/// get programming language of buffer contents
Language buffer_language(TextBuffer *buffer);
-/// clip the rectangle so it's all inside the buffer. returns true if there's any rectangle left.
+/// clip the rectangle so it's all inside the buffer.
+///
+/// \returns `true` if there's any rectangle left.
bool buffer_clip_rect(TextBuffer *buffer, Rect *r);
/// Get the font used for this buffer.
Font *buffer_font(TextBuffer *buffer);
@@ -407,30 +416,38 @@ u8 buffer_tab_width(TextBuffer *buffer);
bool buffer_indent_with_spaces(TextBuffer *buffer);
/// returns the number of lines in the buffer.
u32 buffer_line_count(TextBuffer *buffer);
-/// get line contents. does not include a newline character.
+/// get line contents.
+///
+/// does not include a newline character.
+///
/// NOTE: this string will be invalidated when the line is edited!!!
/// only use it briefly!!
///
/// returns an empty string if `line_number` is out of range.
String32 buffer_get_line(TextBuffer *buffer, u32 line_number);
-/// get line contents. does not include a newline character.
+/// get line contents as UTF-8.
+///
+/// does not include a newline character.
///
/// string must be freed by caller.
/// returns an empty string if `line_number` is out of range.
char *buffer_get_line_utf8(TextBuffer *buffer, u32 line_number);
/// get at most `nchars` characters starting from position `pos`.
+///
/// returns the number of characters actually available.
-/// you can pass NULL for text if you just want to know how many
+///
+/// you can pass `NULL` for `text` if you just want to know how many
/// characters *could* be accessed before the end of the file.
size_t buffer_get_text_at_pos(TextBuffer *buffer, BufferPos pos, char32_t *text, size_t nchars);
/// returns a UTF-32 string of at most `nchars` code points from `buffer` starting at `pos`
+///
/// the string should be passed to str32_free.
String32 buffer_get_str32_text_at_pos(TextBuffer *buffer, BufferPos pos, size_t nchars);
/// get UTF-8 string at position, up to `nchars` code points (NOT bytes).
///
/// the resulting string should be freed.
char *buffer_get_utf8_text_at_pos(TextBuffer *buffer, BufferPos pos, size_t nchars);
-/// Puts a UTF-8 string containing the contents of the buffer into out.
+/// Puts a UTF-8 string containing the contents of the buffer into `out`.
///
/// Returns the number of bytes, including a null terminator.
/// To use this function, first pass NULL for out to get the number of bytes you need to allocate.
@@ -441,30 +458,30 @@ size_t buffer_contents_utf8(TextBuffer *buffer, char *out);
char *buffer_contents_utf8_alloc(TextBuffer *buffer);
/// clear contents, undo history, etc. of a buffer
void buffer_clear(TextBuffer *buffer);
-/// returns the length of the `line_number`th line (0-indexed),
+/// returns the number of characters in the `line_number`th line (0-indexed),
/// or 0 if `line_number` is out of range.
u32 buffer_line_len(TextBuffer *buffer, u32 line_number);
-/// returns the number of lines of text in the buffer into *lines (if not NULL),
-/// and the number of columns of text, i.e. the width of the longest column divided by the width of the space character, into *cols (if not NULL)
-void buffer_text_dimensions(TextBuffer *buffer, u32 *lines, u32 *columns);
-/// returns the number of rows of text that can fit in the buffer
+/// returns the length of the longest on-screen line in space widths.
+u32 buffer_column_count(TextBuffer *buffer);
+/// returns the number of lines of text that can fit on screen in the buffer
float buffer_display_lines(TextBuffer *buffer);
-/// returns the number of columns of text that can fit in the buffer
+/// returns the number of columns of text that can fit on screen in the buffer
float buffer_display_cols(TextBuffer *buffer);
/// scroll by deltas (measured in lines and columns)
void buffer_scroll(TextBuffer *buffer, double dx, double dy);
/// returns the screen position of the character at the given position in the buffer.
vec2 buffer_pos_to_pixels(TextBuffer *buffer, BufferPos pos);
/// convert pixel coordinates to a position in the buffer, selecting the closest character.
-/// returns false if the position is not inside the buffer, but still sets *pos to the closest character.
+///
+/// returns false if the position is not inside the buffer, but still sets `*pos` to the closest character.
bool buffer_pixels_to_pos(TextBuffer *buffer, vec2 pixel_coords, BufferPos *pos);
/// scroll to `pos`, scrolling as little as possible while maintaining scrolloff.
void buffer_scroll_to_pos(TextBuffer *buffer, BufferPos pos);
-/// scroll in such a way that this position is in the center of the screen
+/// scroll in such a way that `pos` is in the center of the buffer's screen rectangle.
void buffer_scroll_center_pos(TextBuffer *buffer, BufferPos pos);
/// scroll so that the cursor is on screen
void buffer_scroll_to_cursor(TextBuffer *buffer);
-/// scroll so that the cursor is in the center of the buffer's rectangle.
+/// scroll so that the cursor is in the center of the buffer's screen rectangle.
void buffer_center_cursor(TextBuffer *buffer);
/// returns the number of characters successfully moved by.
i64 buffer_pos_move_left(TextBuffer *buffer, BufferPos *pos, i64 by);
@@ -506,16 +523,20 @@ i64 buffer_cursor_move_right_words(TextBuffer *buffer, i64 nwords);
void buffer_cursor_move_to_prev_pos(TextBuffer *buffer);
/// Get the start and end index of the word at the given position.
void buffer_word_span_at_pos(TextBuffer *buffer, BufferPos pos, u32 *word_start, u32 *word_end);
-/// Returns a string of word characters (see is32_word) around the position,
-/// or an empty string if neither of the characters to the left and right of the cursor are word characters.
+/// returns a string of word characters (see \ref is32_word) around the position.
+///
+/// returns an empty string if neither of the characters to the left and right of the cursor are word characters.
+//
/// NOTE: The string is invalidated when the buffer is changed!!!
/// The return value should NOT be freed.
String32 buffer_word_at_pos(TextBuffer *buffer, BufferPos pos);
/// Get the word at the cursor.
+///
/// NOTE: The string is invalidated when the buffer is changed!!!
/// The return value should NOT be freed.
String32 buffer_word_at_cursor(TextBuffer *buffer);
/// Get a UTF-8 string consisting of the word at the cursor.
+///
/// The return value should be freed.
char *buffer_word_at_cursor_utf8(TextBuffer *buffer);
/// Used for \ref CMD_INCREMENT_NUMBER and \ref CMD_DECREMENT_NUMBER
@@ -603,28 +624,34 @@ void buffer_insert_utf8_at_pos(TextBuffer *buffer, BufferPos pos, const char *ut
/// Insert UTF-8 text at the cursor, and move the cursor to the end of it.
void buffer_insert_utf8_at_cursor(TextBuffer *buffer, const char *utf8);
/// Insert a "tab" at the cursor position, and move the cursor past it.
+///
/// This inserts spaces if ted is configured to indent with spaces.
void buffer_insert_tab_at_cursor(TextBuffer *buffer);
/// Insert a newline at the cursor position.
+///
/// If `buffer` is a line buffer, this "submits" the buffer.
/// If not, this auto-indents the next line, and moves the cursor to it.
void buffer_newline(TextBuffer *buffer);
/// Delete `nchars` characters after the cursor.
void buffer_delete_chars_at_cursor(TextBuffer *buffer, i64 nchars);
-/// Delete `nchars` characters before *pos, and set *pos to just before the deleted characters.
-/// Returns the number of characters actually deleted.
+/// Delete `nchars` characters before `*pos`, and set `*pos` to just before the deleted characters.
+///
+/// \returns the number of characters actually deleted.
i64 buffer_backspace_at_pos(TextBuffer *buffer, BufferPos *pos, i64 nchars);
/// Delete `nchars` characters before the cursor position, and set the cursor position accordingly.
-/// Returns the number of characters actually deleted.
+///
+/// \returns the number of characters actually deleted.
i64 buffer_backspace_at_cursor(TextBuffer *buffer, i64 nchars);
/// Delete `nwords` words after the position.
void buffer_delete_words_at_pos(TextBuffer *buffer, BufferPos pos, i64 nwords);
/// Delete `nwords` words after the cursor.
void buffer_delete_words_at_cursor(TextBuffer *buffer, i64 nwords);
-/// Delete `nwords` words before *pos, and set *pos to just before the deleted words.
+/// Delete `nwords` words before `*pos`, and set `*pos` to just before the deleted words.
+///
/// Returns the number of words actually deleted.
void buffer_backspace_words_at_pos(TextBuffer *buffer, BufferPos *pos, i64 nwords);
/// Delete `nwords` words before the cursor position, and set the cursor position accordingly.
+///
/// Returns the number of words actually deleted.
void buffer_backspace_words_at_cursor(TextBuffer *buffer, i64 nwords);
/// Undo `ntimes` times
@@ -643,17 +670,19 @@ void buffer_copy(TextBuffer *buffer);
void buffer_cut(TextBuffer *buffer);
/// Insert the clipboard contents at the cursor position.
void buffer_paste(TextBuffer *buffer);
-/// Load the file `path`. If `path` is not an absolute path,
-/// this function will fail.
+/// Load the file at absolute path `path`.
bool buffer_load_file(TextBuffer *buffer, const char *path);
/// Reloads the file loaded in the buffer.
void buffer_reload(TextBuffer *buffer);
/// has this buffer been changed by another program since last save?
bool buffer_externally_changed(TextBuffer *buffer);
/// Clear `buffer`, and set its path to `path`.
+///
/// if `path` is NULL, this will turn `buffer` into an untitled buffer.
void buffer_new_file(TextBuffer *buffer, const char *path);
-/// Save the buffer to its current filename. This will rewrite the entire file,
+/// Save the buffer to its current filename.
+///
+/// This will rewrite the entire file,
/// even if there are no unsaved changes.
bool buffer_save(TextBuffer *buffer);
/// Save, but with a different path.
@@ -698,7 +727,7 @@ bool buffer_pos_eq(BufferPos p1, BufferPos p2);
///
/// faster than \ref buffer_pos_diff (constant time)
int buffer_pos_cmp(BufferPos p1, BufferPos p2);
-/// returns "`p2 - p1`", that is, the number of characters between `p1` and `p2`,
+/// returns `p2 - p1`, that is, the number of characters between `p1` and `p2`,
/// but negative if `p1` comes after `p2`.
i64 buffer_pos_diff(TextBuffer *buffer, BufferPos p1, BufferPos p2);
@@ -735,6 +764,7 @@ void build_check_for_errors(Ted *ted);
ColorSetting color_setting_from_str(const char *str);
/// get string corresponding to color setting
const char *color_setting_to_str(ColorSetting s);
+/// parse color (e.g. `"#ff0000"`)
Status color_from_str(const char *str, u32 *color);
/// perform alpha blending with `bg` and `fg`.
u32 color_blend(u32 bg, u32 fg);
@@ -752,8 +782,8 @@ void command_execute(Ted *ted, Command c, i64 argument);
void command_execute_string_argument(Ted *ted, Command c, const char *string);
// === config.c ===
-/// returns the best guess for the root directory of the project containing `path`
-/// (which should be an absolute path).
+/// returns the best guess for the root directory of the project containing absolute path `path`.
+///
/// the return value should be freed.
char *settings_get_root_dir(Settings *settings, const char *path);
@@ -841,7 +871,7 @@ const char *document_link_at_buffer_pos(Ted *ted, BufferPos pos);
void hover_reset_timer(Ted *ted);
// === ide-rename-symbol.c ===
-/// renname symbol at cursor of `buffer` to `new_name`
+/// rename symbol at cursor of `buffer` to `new_name`
void rename_symbol_at_cursor(Ted *ted, TextBuffer *buffer, const char *new_name);
// === ide-signature-help.c ===
@@ -887,18 +917,20 @@ void *menu_get_context(Ted *ted);
bool menu_is_open(Ted *ted, const char *menu_name);
/// is any menu open?
bool menu_is_any_open(Ted *ted);
-/// process a :escape command (by default this happens when the escape key is pressed)
+/// process a `:escape` command for the currently open menu
void menu_escape(Ted *ted);
/// get rectangle which menu takes up
Rect menu_rect(Ted *ted);
// === node.c ===
/// go to the `n`th next tab (e.g. `n=1` goes to the next tab)
+///
/// going past the end of the tabs will "wrap around" to the first one.
///
/// if `node` is a split, nothing happens.
void node_tab_next(Ted *ted, Node *node, i32 n);
/// go to the `n`th previous tab (e.g. `n=1` goes to the previous tab)
+///
/// going before the first tab will "wrap around" to the last one.
///
/// if `node` is a split, nothing happens.
@@ -925,7 +957,7 @@ u32 node_tab_count(Ted *ted, Node *node);
/// returns `NULL` if `tab` is out of range.
TextBuffer *node_tab_get(Ted *ted, Node *node, u32 tab);
*/
-/// returns parent node, or NULL if this is the root node.
+/// returns parent node, or `NULL` if this is the root node.
Node *node_parent(Ted *ted, Node *node);
/// join this node with its sibling
void node_join(Ted *ted, Node *node);
@@ -956,8 +988,6 @@ void session_read(Ted *ted);
///
/// this should be done before loading configs so language-specific settings are recognized properly.
void syntax_register_language(const LanguageInfo *info);
-/// register ted's built-in languages.
-void syntax_register_builtin_languages(void);
/// returns `true` if `language` is a valid language ID
bool language_is_valid(Language language);
/// read language name from `str`. returns `LANG_NONE` if `str` is invalid.
@@ -966,22 +996,26 @@ Language language_from_str(const char *str);
const char *language_to_str(Language language);
/// get the color setting associated with the given syntax highlighting type
ColorSetting syntax_char_type_to_color_setting(SyntaxCharType t);
-/// returns ')' for '(', '[' for ']', etc., or 0 if c is not a bracket
+/// returns ')' for '(', '[' for ']', etc., or 0 if `c` is not a bracket
char32_t syntax_matching_bracket(Language lang, char32_t c);
/// returns true for opening brackets, false for closing brackets/non-brackets
bool syntax_is_opening_bracket(Language lang, char32_t c);
-/// This is the main syntax highlighting function. It will determine which colors to use for each character.
-/// Rather than returning colors, it returns a character type (e.g. comment) which can be converted to a color.
-/// To highlight multiple lines, start out with a zeroed SyntaxState, and pass a pointer to it each time.
-/// You can set char_types to NULL if you just want to advance the state, and don't care about the character types.
+/// main syntax highlighting function.
+///
+/// determines which colors to use for each character.
+///
+/// To highlight multiple lines, start out with a zeroed \ref SyntaxState, and pass a pointer to it each time.
+/// You can set `char_types` to `NULL` if you just want to advance the state, and don't care about the character types.
void syntax_highlight(SyntaxState *state, Language lang, const char32_t *line, u32 line_len, SyntaxCharType *char_types);
// === tags.c ===
+/// generate tags file
void tags_generate(Ted *ted, bool run_in_build_window);
-/// find all tags beginning with the given prefix, returning them into `*out`, writing at most out_size entries.
-/// you may pass NULL for `out`, in which case just the number of matching tags is returned
+/// find all tags beginning with the given prefix, returning them into `out[0..out_size]`.
+///
+/// you can pass NULL for `out`, in which case just the number of matching tags is returned
/// (still maxing out at `out_size`).
-/// each element in `out` should be freed when you're done with them.
+/// each element in `out` should be freed when you're done with it.
size_t tags_beginning_with(Ted *ted, const char *prefix, char **out, size_t out_size, bool error_if_tags_does_not_exist);
/// go to the definition of the given tag
bool tag_goto(Ted *ted, const char *tag);
@@ -1027,11 +1061,11 @@ void ted_info(Ted *ted, PRINTF_FORMAT_STRING const char *fmt, ...) ATTRIBUTE_PRI
void ted_log(Ted *ted, PRINTF_FORMAT_STRING const char *fmt, ...) ATTRIBUTE_PRINTF(2, 3);
/// set error to "out of memory" message.
void ted_out_of_mem(Ted *ted);
-/// allocate memory, producing an error message and returning NULL on failure
+/// allocate memory, producing an error message and returning `NULL` on failure
void *ted_malloc(Ted *ted, size_t size);
-/// allocate memory, producing an error message and returning NULL on failure
+/// allocate memory, producing an error message and returning `NULL` on failure
void *ted_calloc(Ted *ted, size_t n, size_t size);
-/// allocate memory, producing an error message and returning NULL on failure
+/// allocate memory, producing an error message and returning `NULL` on failure
void *ted_realloc(Ted *ted, void *p, size_t new_size);
/// get width of menu (e.g. "open file" menu) in pixels
float ted_get_menu_width(Ted *ted);
@@ -1039,13 +1073,9 @@ float ted_get_menu_width(Ted *ted);
/// (i.e. look for it in the local and global data directories),
/// and return the full path.
Status ted_get_file(Ted const *ted, const char *name, char *out, size_t outsz);
-/// get full path relative to ted->cwd.
+/// get full path relative to ted working directory.
void ted_path_full(Ted *ted, const char *relpath, char *abspath, size_t abspath_size);
-/// set ted->active_buffer to something nice
-void ted_reset_active_buffer(Ted *ted);
-/// set ted's error message to the buffer's error.
-void ted_error_from_buffer(Ted *ted, TextBuffer *buffer);
-/// Returns the buffer containing the file at absolute path `path`, or NULL if there is none.
+/// Returns the buffer containing the file at absolute path `path`, or `NULL` if there is none.
TextBuffer *ted_get_buffer_with_file(Ted *ted, const char *path);
/// close this buffer, discarding unsaved changes.
void ted_close_buffer(Ted *ted, TextBuffer *buffer);
@@ -1057,17 +1087,17 @@ bool ted_close_buffer_with_file(Ted *ted, const char *path);
bool ted_save_all(Ted *ted);
/// reload all buffers from their files
void ted_reload_all(Ted *ted);
-/// Load all the fonts ted will use, freeing any previous ones.
-void ted_load_fonts(Ted *ted);
-/// Change ted's font size. Avoid calling this super often since it trashes all current font textures.
+/// Change ted's font size.
+///
+/// Avoid calling this super often since it trashes all current font textures.
void ted_change_text_size(Ted *ted, float new_size);
-/// Free all of ted's fonts.
-void ted_free_fonts(Ted *ted);
/// Get likely root directory of project containing `path`.
+///
/// The returned value should be freed.
char *ted_get_root_dir_of(Ted *ted, const char *path);
/// Get the root directory of the project containing the active buffer's file,
/// or `ted->cwd` if no file is open.
+///
/// The returned value should be freed.
char *ted_get_root_dir(Ted *ted);
/// the settings of the active buffer, or the default settings if there is no active buffer
@@ -1075,27 +1105,31 @@ Settings *ted_active_settings(Ted *ted);
/// Get the settings for a file at the given path in the given language.
Settings *ted_get_settings(Ted *ted, const char *path, Language language);
/// Get LSP which should be used for the given path and language.
+///
/// If no running LSP server would cover the path and language, a new one is
/// started if possible.
-/// Returns NULL on failure (e.g. there is no LSP server
+/// Returns `NULL` on failure (e.g. there is no LSP server
/// specified for the given path and language).
struct LSP *ted_get_lsp(Ted *ted, const char *path, Language language);
-/// Get the LSP of the active buffer/ted->cwd.
-/// Returns NULL if there is no such server.
+/// Get the LSP of the active buffer or directory.
+///
+/// Returns `NULL` if there is no such server.
struct LSP *ted_active_lsp(Ted *ted);
-/// get the value of the given color setting, according to `ted_active_settings(ted)`.
+/// get the value of the given color setting, according to \ref ted_active_settings.
u32 ted_active_color(Ted *ted, ColorSetting color);
/// open the given file, or switch to it if it's already open.
+///
/// returns true on success.
bool ted_open_file(Ted *ted, const char *filename);
/// create a new buffer for the file `filename`, or open it if it's already open.
-/// if `filename` is NULL, this creates an untitled buffer.
+///
+/// if `filename` is `NULL`, this creates an untitled buffer.
+///
/// returns true on success.
bool ted_new_file(Ted *ted, const char *filename);
/// save all changes to all buffers with unsaved changes.
bool ted_save_all(Ted *ted);
-/// sets the active buffer to this buffer, and updates active_node, etc. accordingly
-/// you can pass NULL to buffer to make it so no buffer is active.
+/// sets the active buffer to this buffer
void ted_switch_to_buffer(Ted *ted, TextBuffer *buffer);
/// switch to this node
void ted_node_switch(Ted *ted, Node *node);
@@ -1104,7 +1138,8 @@ void ted_reload_configs(Ted *ted);
/// handle a key press
void ted_press_key(Ted *ted, i32 keycode, u32 modifier);
/// get the buffer and buffer position where the mouse is.
-/// returns false if the mouse is not in a buffer.
+///
+/// returns `false` if the mouse is not in a buffer.
Status ted_get_mouse_buffer_pos(Ted *ted, TextBuffer **pbuffer, BufferPos *ppos);
/// make the cursor red for a bit to indicate an error (e.g. no autocompletions)
void ted_flash_error_cursor(Ted *ted);
@@ -1112,9 +1147,11 @@ void ted_flash_error_cursor(Ted *ted);
float ted_line_buffer_height(Ted *ted);
/// add a \ref EditNotify callback which will be called whenever `buffer` is edited.
///
-/// returns an ID which can be used with \ref ted_remove_edit_notify
+/// \returns an ID which can be used with \ref ted_remove_edit_notify
EditNotifyID ted_add_edit_notify(Ted *ted, EditNotify notify, void *context);
-/// remove edit notify callback. if `id` is zero or invalid, no action is taken.
+/// remove edit notify callback.
+///
+/// if `id` is zero or invalid, no action is taken.
void ted_remove_edit_notify(Ted *ted, EditNotifyID id);
// === ui.c ===
@@ -1124,18 +1161,18 @@ void selector_up(Ted *ted, Selector *s, i64 n);
void selector_down(Ted *ted, Selector *s, i64 n);
/// sort entries alphabetically
void selector_sort_entries_by_name(Selector *s);
-/// returns a null-terminated UTF-8 string of the entry selected, or NULL if none was.
+/// returns a null-terminated UTF-8 string of the entry selected, or `NULL` if none was.
///
-/// also, sel->cursor will be set to the index of the entry, even if the mouse was used.
-/// you should call free() on the return value.
+/// also, the cursor will be set to the index of the entry, even if the mouse was used.
+/// you should free the return value.
char *selector_update(Ted *ted, Selector *s);
/// render selector
///
/// NOTE: also renders the line buffer
void selector_render(Ted *ted, Selector *s);
-/// free resources uesd by file selecor
+/// free resources used by file selector
void file_selector_free(FileSelector *fs);
-/// returns the name of the selected file, or NULL if none was selected.
+/// returns the name of the selected file, or `NULL` if none was selected.
///
/// the returned pointer should be freed.
char *file_selector_update(Ted *ted, FileSelector *fs);
@@ -1145,13 +1182,13 @@ void file_selector_render(Ted *ted, FileSelector *fs);
vec2 button_get_size(Ted *ted, const char *text);
/// render button
void button_render(Ted *ted, Rect button, const char *text, u32 color);
-/// returns true if the button was clicked on.
+/// returns `true` if the button was clicked on.
bool button_update(Ted *ted, Rect button);
-/// returns selected option, or POPUP_NONE if none was selected
+/// returns selected option, or 0 if none was selected
PopupOption popup_update(Ted *ted, u32 options);
/// render popup menu.
///
-/// `options` should be a bitwise or of the POPUP_* constants.
+/// `options` should be a bitwise-or of the `POPUP_*` constants.
void popup_render(Ted *ted, u32 options, const char *title, const char *body);
/// update and render checkbox
vec2 checkbox_frame(Ted *ted, bool *value, const char *label, vec2 pos);