improve ted.h documentation

1 files changed, 35 insertions, 39 deletions

diff --git a/ted.h b/ted.h
index 8e68d1b..d754e3e 100644
--- a/ted.h
+++ b/ted.h
@@ -246,7 +246,7 @@ typedef enum {
 /// Used for dynamic language registration (\ref syntax_register_language).
 /// Please zero all the fields of the struct which you aren't using.
 ///
-/// The fields `id` and `name` MUST NOT be 0, or `ted` will reject your language.
+/// The fields `id` and `name` MUST be filled in, or else `ted` will reject your language.
 typedef struct {
 	/// Language ID number. For user-defined languages, this must be `>= LANG_USER_MIN` and `< LANG_USER_MAX`.
 	///
@@ -270,17 +270,17 @@ typedef struct {
 	///
 	/// try to pick a unique name.
 	char name[24];
-	/// if non-NULL this will be called right after the menu is opened
+	/// if non-`NULL` this will be called right after the menu is opened
 	void (*open)(Ted *ted);
-	/// if non-NULL this will be called every frame
+	/// if non-`NULL` this will be called every frame
 	/// before anything is rendered to the screen.
 	void (*update)(Ted *ted);
-	/// if non-NULL this will be called every frame
+	/// if non-`NULL` this will be called every frame
 	/// after buffers, etc. have been rendered to the screen
 	/// (when the menu should be rendered)
 	void (*render)(Ted *ted);
-	/// if non-NULL this will be called right before the menu is closed.
-	/// if it returns false, the menu will not be closed.
+	/// if non-`NULL` this will be called right before the menu is closed.
+	/// if it returns `false`, the menu will not be closed.
 	bool (*close)(Ted *ted);
 	/// should be zeroed -- reserved for future use.
 	char reserved[128];
@@ -335,12 +335,12 @@ double buffer_last_write_time(TextBuffer *buffer);
 void buffer_ignore_changes_on_disk(TextBuffer *buffer);
 /// get position of the cursor
 BufferPos buffer_cursor_pos(TextBuffer *buffer);
-/// returns true if anything is selected
+/// returns `true` if anything is selected
 bool buffer_has_selection(TextBuffer *buffer);
 /// get position of non-cursor end of selection.
 ///
-/// `pos` is allowed to be NULL.
-/// returns false if nothing is selected.
+/// `pos` is allowed to be `NULL`.
+/// returns `false` if nothing is selected.
 bool buffer_selection_pos(TextBuffer *buffer, BufferPos *pos);
 /// Get path to buffer's file, or `NULL` if the buffer is unnamed.
 ///
@@ -350,7 +350,7 @@ const char *buffer_get_path(TextBuffer *buffer);
 void buffer_clear_undo_redo(TextBuffer *buffer);
 /// set whether undo history should be kept
 ///
-/// if `enabled` is false, any previous undo/redo history will be cleared.
+/// if `enabled` is `false`, any previous undo/redo history will be cleared.
 void buffer_set_undo_enabled(TextBuffer *buffer, bool enabled);
 /// set manual language override for buffer.
 ///
@@ -374,7 +374,7 @@ bool buffer_unsaved_changes(TextBuffer *buffer);
 bool buffer_is_line_buffer(TextBuffer *buffer);
 /// has this line buffer been submitted?
 ///
-/// returns false if `buffer` is not a line buffer.
+/// returns `false` if `buffer` is not a line buffer.
 bool line_buffer_is_submitted(TextBuffer *buffer);
 /// clear submission status of line buffer.
 void line_buffer_clear_submitted(TextBuffer *buffer);
@@ -453,8 +453,9 @@ String32 buffer_get_str32_text_at_pos(TextBuffer *buffer, BufferPos pos, size_t
 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`.
 ///
-/// 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.
+/// To use this function, first pass `NULL` for `out` to get the number of bytes you need to allocate.
+///
+/// \returns the number of bytes, including a null terminator.
 size_t buffer_contents_utf8(TextBuffer *buffer, char *out);
 /// Returns a UTF-8 string containing the contents of `buffer`.
 ///
@@ -477,7 +478,7 @@ void buffer_scroll(TextBuffer *buffer, double dx, double dy);
 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);
@@ -546,7 +547,7 @@ char *buffer_word_at_cursor_utf8(TextBuffer *buffer);
 /// Used for \ref CMD_INCREMENT_NUMBER and \ref CMD_DECREMENT_NUMBER
 ///
 /// Moves `*ppos` to the start of the (new) number.
-/// returns false if there was no number at `*ppos`.
+/// returns `false` if there was no number at `*ppos`.
 bool buffer_change_number_at_pos(TextBuffer *buffer, BufferPos *ppos, i64 by);
 /// Used for \ref CMD_INCREMENT_NUMBER and \ref CMD_DECREMENT_NUMBER
 bool buffer_change_number_at_cursor(TextBuffer *buffer, i64 argument);
@@ -564,7 +565,7 @@ void buffer_cursor_move_to_start_of_file(TextBuffer *buffer);
 void buffer_cursor_move_to_end_of_file(TextBuffer *buffer);
 /// Put text at a position.
 ///
-/// Returns the position of the end of the text, or (BufferPos){0} on error.
+/// Returns the position of the end of the text, or `(BufferPos){0}` on error.
 BufferPos buffer_insert_text_at_pos(TextBuffer *buffer, BufferPos pos, String32 str);
 /// Insert a single character at a position.
 void buffer_insert_char_at_pos(TextBuffer *buffer, BufferPos pos, char32_t c);
@@ -651,12 +652,8 @@ 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.
-///
-/// 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
 void buffer_undo(TextBuffer *buffer, i64 ntimes);
@@ -682,7 +679,7 @@ void buffer_reload(TextBuffer *buffer);
 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.
+/// 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.
 ///
@@ -721,7 +718,7 @@ void buffer_uncomment_lines(TextBuffer *buffer, u32 first_line, u32 last_line);
 void buffer_toggle_comment_lines(TextBuffer *buffer, u32 first_line, u32 last_line);
 /// comment the selected lines, or uncomment them if they're all commented
 void buffer_toggle_comment_selection(TextBuffer *buffer);
-/// returns true if `p1` and `p2` are equal
+/// returns `true` if `p1` and `p2` are equal
 bool buffer_pos_eq(BufferPos p1, BufferPos p2);
 /// returns `-1` if `p1` comes before `p2`
 ///
@@ -842,7 +839,7 @@ bool autocomplete_has_phantom(Ted *ted);
 bool autocomplete_box_contains_point(Ted *ted, vec2 point);
 /// open autocomplete
 ///
-/// trigger should either be a character (e.g. '.') or one of the TRIGGER_* constants.
+/// trigger should either be a character (e.g. '.') or one of the `TRIGGER_*` constants.
 void autocomplete_open(Ted *ted, uint32_t trigger);
 /// select the completion the cursor is on,
 /// or select the phantom completion if there is one.
@@ -863,8 +860,8 @@ void definition_cancel_lookup(Ted *ted);
 // === ide-document-link.c ===
 /// get document link at this position in the active buffer.
 ///
-/// this will always return `NULL` if the document link activation key isn't presed.
-/// the returned pointer won't be freed immediately, but could be on the next frame,
+/// this will always return `NULL` if the document link activation key isn't pressed.
+/// the returned pointer could be freed on the next frame,
 /// so don't keep it around long.
 const char *document_link_at_buffer_pos(Ted *ted, BufferPos pos);
 
@@ -884,7 +881,7 @@ void signature_help_retrigger(Ted *ted);
 /// open signature help.
 ///
 /// `trigger` should either be the trigger character (e.g. ',')
-/// or one of the TRIGGER_* constants.
+/// or one of the `TRIGGER_*` constants.
 void signature_help_open(Ted *ted, uint32_t trigger);
 /// is the signature help window open?
 bool signature_help_is_open(Ted *ted);
@@ -959,7 +956,7 @@ Node *node_child2(Node *node);
 float node_split_pos(Node *node);
 /// set proportion of split devoted to left/top child.
 void node_split_set_pos(Node *node, float pos);
-/// returns true if this node is a vertical split
+/// returns `true` if this node is a vertical split
 bool node_split_is_vertical(Node *node);
 /// set whether this node is a vertical split
 void node_split_set_vertical(Node *node, bool is_vertical);
@@ -1015,7 +1012,7 @@ const char *language_to_str(Language language);
 ColorSetting syntax_char_type_to_color_setting(SyntaxCharType t);
 /// 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
+/// returns `true` for opening brackets, false for closing brackets/non-brackets
 bool syntax_is_opening_bracket(Language lang, char32_t c);
 /// main syntax highlighting function.
 ///
@@ -1030,7 +1027,7 @@ void syntax_highlight(SyntaxState *state, Language lang, const char32_t *line, u
 void tags_generate(Ted *ted, bool run_in_build_window);
 /// 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
+/// 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 it.
 size_t tags_beginning_with(Ted *ted, const char *prefix, char **out, size_t out_size, bool error_if_tags_does_not_exist);
@@ -1040,11 +1037,11 @@ bool tag_goto(Ted *ted, const char *tag);
 // === ted.c ===
 /// for fatal errors
 void die(PRINTF_FORMAT_STRING const char *fmt, ...) ATTRIBUTE_PRINTF(1, 2);
-/// returns the current active buffer, or NULL if no buffer is active.
+/// returns the current active buffer, or `NULL` if no buffer is active.
 TextBuffer *ted_get_active_buffer(Ted *ted);
 /// if a menu is open, returns the buffer that was open before the menu was opened.
 ///
-/// returns NULL if no menu is open or no buffer was open before the menu was opened.
+/// returns `NULL` if no menu is open or no buffer was open before the menu was opened.
 TextBuffer *ted_get_active_buffer_behind_menu(Ted *ted);
 /// get width of ted window
 float ted_window_width(Ted *ted);
@@ -1098,7 +1095,7 @@ TextBuffer *ted_get_buffer_with_file(Ted *ted, const char *path);
 void ted_close_buffer(Ted *ted, TextBuffer *buffer);
 /// close buffer with this absolute path, discarding unsaved changes.
 ///
-/// returns true if the buffer was actually present.
+/// returns `true` if the buffer was actually present.
 bool ted_close_buffer_with_file(Ted *ted, const char *path);
 /// save all buffers
 bool ted_save_all(Ted *ted);
@@ -1112,8 +1109,7 @@ void ted_change_text_size(Ted *ted, float new_size);
 ///
 /// 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.
+/// Get likely root directory of currently open project.
 ///
 /// The returned value should be freed.
 char *ted_get_root_dir(Ted *ted);
@@ -1121,14 +1117,14 @@ char *ted_get_root_dir(Ted *ted);
 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.
+/// Get LSP server 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
+/// If no running 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
 /// 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 or directory.
+/// Get the LSP server of the active buffer or directory.
 ///
 /// Returns `NULL` if there is no such server.
 struct LSP *ted_active_lsp(Ted *ted);
@@ -1136,13 +1132,13 @@ struct LSP *ted_active_lsp(Ted *ted);
 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.
+/// 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.
 ///
-/// returns true on success.
+/// 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);