more documentation

9 files changed, 103 insertions, 30 deletions

diff --git a/buffer.c b/buffer.c
index 719c24e..176178d 100644
--- a/buffer.c
+++ b/buffer.c
@@ -2362,8 +2362,6 @@ Status buffer_load_file(TextBuffer *buffer, const char *path) {
 	return success;
 }
 
-// Reloads the file loaded in the buffer.
-// Note that this clears undo history, etc.
 void buffer_reload(TextBuffer *buffer) {
 	if (buffer_is_named_file(buffer)) {
 		BufferPos cursor_pos = buffer->cursor_pos;
@@ -2382,7 +2380,6 @@ void buffer_reload(TextBuffer *buffer) {
 	}
 }
 
-// has this buffer been changed by another program since last save?
 bool buffer_externally_changed(TextBuffer *buffer) {
 	if (!buffer_is_named_file(buffer))
 		return false;
diff --git a/config.c b/config.c
index 2257722..f16e7b7 100644
--- a/config.c
+++ b/config.c
@@ -171,7 +171,6 @@ static void context_copy(SettingsContext *dest, const SettingsContext *src) {
 		dest->path = str_dup(src->path);
 }
 
-// score is higher if context is closer match.
 long context_score(const char *path, Language lang, const SettingsContext *context) {
 	long score = 0;
 	
@@ -1058,8 +1057,6 @@ static char *last_separator(char *path) {
 	return NULL;
 }
 
-// returns the best guess for the root directory of the project containing `path` (which should be an absolute path)
-// the return value should be freed.
 char *settings_get_root_dir(Settings *settings, const char *path) {
 	char best_path[TED_PATH_MAX];
 	*best_path = '\0';
diff --git a/find.c b/find.c
index a292e5c..2abcd42 100644
--- a/find.c
+++ b/find.c
@@ -15,7 +15,6 @@ static u32 find_replace_flags(Ted *ted) {
 	return (ted->find_regex ? 0 : PCRE2_SUBSTITUTE_LITERAL);
 }
 
-// which buffer will be searched?
 TextBuffer *find_search_buffer(Ted *ted) {
 	if (ted->active_buffer && ted->active_buffer != &ted->find_buffer && ted->active_buffer != &ted->replace_buffer) {
 		return ted->active_buffer;
@@ -132,7 +131,7 @@ void find_update(Ted *ted, bool force) {
 	TextBuffer *find_buffer = &ted->find_buffer;
 	u32 flags = find_compilation_flags(ted);
 	if (!force
-		&& !find_buffer->modified // check if buffer has been modified,
+		&& !find_buffer->modified // check if pattern has been modified,
 		&& ted->find_flags == flags) // or checkboxes have been (un)checked
 		return;
 	ted->find_flags = flags;
@@ -267,7 +266,6 @@ static bool find_replace_match(Ted *ted, u32 match_idx) {
 	return success;
 }
 
-// replace the match we are currently highlighting, or do nothing if there is no highlighted match
 void find_replace(Ted *ted) {
 	TextBuffer *buffer = find_search_buffer(ted);
 	if (!buffer) return;
@@ -278,8 +276,7 @@ void find_replace(Ted *ted) {
 		find_update(ted, true);
 	}
 }
-	
-// go to next find result
+
 void find_next(Ted *ted) {
 	if (ted->replace) {
 		find_replace(ted);
diff --git a/ide-autocomplete.c b/ide-autocomplete.c
index 9f70758..49fcba3 100644
--- a/ide-autocomplete.c
+++ b/ide-autocomplete.c
@@ -86,7 +86,7 @@ void autocomplete_close(Ted *ted) {
 	}
 }
 
-void autocomplete_update_suggested(Ted *ted) {
+static void autocomplete_update_suggested(Ted *ted) {
 	Autocomplete *ac = &ted->autocomplete;
 	arr_clear(ac->suggested);
 	char *word = str32_to_utf8_cstr(
diff --git a/ide-signature-help.c b/ide-signature-help.c
index e7138a8..8cabdf7 100644
--- a/ide-signature-help.c
+++ b/ide-signature-help.c
@@ -14,7 +14,7 @@ static void signature_help_clear(SignatureHelp *help) {
 	help->signature_count = 0;
 }
 
-void signature_help_send_request(Ted *ted) {
+static void signature_help_send_request(Ted *ted) {
 	SignatureHelp *help = &ted->signature_help;
 	Settings *settings = ted_active_settings(ted);
 	if (!settings->signature_help_enabled) {
@@ -44,7 +44,7 @@ void signature_help_retrigger(Ted *ted) {
 	ted->signature_help.retrigger = true;
 }
 
-void signature_help_open(Ted *ted, char32_t trigger) {
+void signature_help_open(Ted *ted, uint32_t trigger) {
 	(void)trigger; // for now we don't send context
 	signature_help_send_request(ted);
 }
diff --git a/ide-usages.c b/ide-usages.c
index 806c09a..95324fd 100644
--- a/ide-usages.c
+++ b/ide-usages.c
@@ -29,14 +29,14 @@ void usages_find(Ted *ted) {
 }
 
 
-void usages_process_lsp_response(Ted *ted, LSPResponse *response) {
+void usages_process_lsp_response(Ted *ted, const LSPResponse *response) {
 	Usages *usages = &ted->usages;
 	if (response->request.type != LSP_REQUEST_REFERENCES)
 		return; // not for us
 	if (response->request.id != usages->last_request_id)
 		return;
 	LSP *lsp = ted_get_lsp_by_id(ted, usages->last_request_lsp);
-	LSPResponseReferences *refs = &response->data.references;
+	const LSPResponseReferences *refs = &response->data.references;
 	if (lsp && arr_len(refs->locations)) { 
 		TextBuffer *buffer = &ted->build_buffer;
 		build_setup_buffer(ted);
diff --git a/main.c b/main.c
index 29223d4..0588752 100644
--- a/main.c
+++ b/main.c
@@ -18,10 +18,10 @@
    textDocument/references to work?
 	- maybe it can be done with the clangd config instead.
 	- does vscode have the same problem?
-- more documentation generally (development.md or something?)
+- more documentation generally
 - rust-analyzer bug reports:
     - bad json can give "Unexpected error: client exited without proper shutdown sequence"
-    - containerName not always given
+    - containerName not always given in textDocument/references
 - clangd bug report:
     - textDocumemt/definition on ted.h declarations just gives you the declaration
 FUTURE FEATURES:
diff --git a/syntax.c b/syntax.c
index e72d664..2d9dd15 100644
--- a/syntax.c
+++ b/syntax.c
@@ -123,7 +123,6 @@ static bool syntax_keyword_matches(const char32_t *text, size_t len, const char
 	}
 }
 
-// returns ')' for '(', etc., or 0 if c is not an opening bracket
 char32_t syntax_matching_bracket(Language lang, char32_t c) {
 	(void)lang; // not needed yet
 	switch (c) {
@@ -137,7 +136,6 @@ char32_t syntax_matching_bracket(Language lang, char32_t c) {
 	return 0;
 }
 
-// returns true for opening brackets, false for closing brackets/non-brackets
 bool syntax_is_opening_bracket(Language lang, char32_t c) {
 	(void)lang;
 	switch (c) {
@@ -1641,10 +1639,6 @@ static void syntax_highlight_go(SyntaxState *state_ptr, const char32_t *line, u3
 	);
 }
 
-// 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.
 void syntax_highlight(SyntaxState *state, Language lang, const char32_t *line, u32 line_len, SyntaxCharType *char_types) {
 	switch (lang) {
 	case LANG_NONE:
diff --git a/ted.h b/ted.h
index 3c137db..7353606 100644
--- a/ted.h
+++ b/ted.h
@@ -412,10 +412,13 @@ typedef struct {
 } Autocompletion;
 
 enum {
-	// autocomplete was triggered by :autocomplete command
+	// autocomplete/signature help was manually triggered
 	TRIGGER_INVOKED = 0x12000,
 	// autocomplete list needs to be updated because more characters were typed
 	TRIGGER_INCOMPLETE = 0x12001,
+	// signtaure help needs to be updated because the cursor was moved or
+	// the buffer's contents changed.
+	TRIGGER_CONTENT_CHANGE = 0x12002,
 };
 
 // data needed for autocompletion
@@ -925,7 +928,9 @@ void buffer_paste(TextBuffer *buffer);
 // Load the file `path`. If `path` is not an absolute path,
 // this function will fail.
 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.
@@ -935,23 +940,40 @@ void buffer_new_file(TextBuffer *buffer, const char *path);
 bool buffer_save(TextBuffer *buffer);
 // save, but with a different path
 bool buffer_save_as(TextBuffer *buffer, const char *new_filename);
+// index of first line that will be displayed on screen
 u32 buffer_first_rendered_line(TextBuffer *buffer);
+// index of last line that will be displayed on screen
 u32 buffer_last_rendered_line(TextBuffer *buffer);
+// go to the definition/declaration/etc of the word at the cursor.
 void buffer_goto_word_at_cursor(TextBuffer *buffer, GotoType type);
+// process a mouse click.
+// returns true if the event was consumed.
 bool buffer_handle_click(Ted *ted, TextBuffer *buffer, vec2 click, u8 times);
+// render the buffer in the given rectangle
 void buffer_render(TextBuffer *buffer, Rect r);
+// indent the given lines
 void buffer_indent_lines(TextBuffer *buffer, u32 first_line, u32 last_line);
+// de-indent the given lines
 void buffer_dedent_lines(TextBuffer *buffer, u32 first_line, u32 last_line);
+// indent the selected lines
 void buffer_indent_selection(TextBuffer *buffer);
+// de-indent the selected lines
 void buffer_dedent_selection(TextBuffer *buffer);
+// indent the line the cursor is on
 void buffer_indent_cursor_line(TextBuffer *buffer);
+// de-indent the line the cursor is on
 void buffer_dedent_cursor_line(TextBuffer *buffer);
+// comment the lines from `first_line` to `last_line`
 void buffer_comment_lines(TextBuffer *buffer, u32 first_line, u32 last_line);
+// uncomment the lines from `first_line` to `last_line`
 void buffer_uncomment_lines(TextBuffer *buffer, u32 first_line, u32 last_line);
+// comment the lines from `first_line` to `last_line`, or uncomment them if they're all commented.
 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);
 // make sure to call gl_geometry_draw after this
 void buffer_highlight_lsp_range(TextBuffer *buffer, LSPRange range);
+// returns true if p1 and p2 are equal
 bool buffer_pos_eq(BufferPos p1, BufferPos p2);
 
 // returns:
@@ -990,6 +1012,8 @@ void build_frame(Ted *ted, float x1, float y1, float x2, float y2);
 ColorSetting color_setting_from_str(const char *str);
 const char *color_setting_to_str(ColorSetting s);
 Status color_from_str(const char *str, u32 *color);
+// which color setting should be used for the given symbol kind.
+// this is the color used in the autocomplete selector, for example.
 ColorSetting color_for_symbol_kind(SymbolKind kind);
 
 // === command.c ===
@@ -1012,25 +1036,41 @@ void command_execute(Ted *ted, Command c, i64 argument);
 //   ---config file 2---
 //     [core]
 //     tab-width = 4
-void config_read(Ted *ted, ConfigPart **parts, const char *filename);
+void config_read(Ted *ted, ConfigPart **pparts, const char *filename);
 void config_parse(Ted *ted, ConfigPart **pparts);
 void config_free(Ted *ted);
+// returns the best guess for the root directory of the project containing `path`
+// (which should be an absolute path).
+// the return value should be freed.
 char *settings_get_root_dir(Settings *settings, const char *path);
+// how well does this settings context fit the given path and language?
+// the context with the highest score will be chosen.
 long context_score(const char *path, Language lang, const SettingsContext *context);
 
 // === find.c ===
+// which buffer will be searched?
 TextBuffer *find_search_buffer(Ted *ted);
+// height of the find/find+replace menu in pixels
 float find_menu_height(Ted *ted);
+// update find results.
+// if `force` is true, the results will be updated even if the pattern & flags have not been changed.
 void find_update(Ted *ted, bool force);
+// replace the match we are currently highlighting, or do nothing if there is no highlighted match
 void find_replace(Ted *ted);
+// go to next find result
 void find_next(Ted *ted);
+// go to previous find result
 void find_prev(Ted *ted);
+// replace all matches
 void find_replace_all(Ted *ted);
 void find_menu_frame(Ted *ted, Rect menu_bounds);
+// open the find/find+replace menu.
 void find_open(Ted *ted, bool replace);
+// close the find/find+replace menu.
 void find_close(Ted *ted);
 
 // === gl.c ===
+// set by main()
 extern float gl_window_width, gl_window_height;
 // set by main()
 extern int gl_version_major, gl_version_minor;
@@ -1096,24 +1136,39 @@ extern int gl_version_major, gl_version_minor;
 gl_for_each_proc(gl_declare_proc)
 #undef gl_declare_proc
 
+// get addresses of GL functions
 void gl_get_procs(void);
+// create a new reference-counted shader-array-buffer object.
 GlRcSAB *gl_rc_sab_new(GLuint shader, GLuint array, GLuint buffer);
+// increase reference count on `s`.
 void gl_rc_sab_incref(GlRcSAB *s);
+// decrease reference count on `*ps`, and set `*ps` to NULL if the reference count is 0.
 void gl_rc_sab_decref(GlRcSAB **ps);
+// create a new reference-counted texture.
 GlRcTexture *gl_rc_texture_new(GLuint texture);
+// increase reference count on `t`.
 void gl_rc_texture_incref(GlRcTexture *t);
+// decrease reference count on `*t`, and set `*t` to NULL if the reference count is 0.
 void gl_rc_texture_decref(GlRcTexture **pt);
+// create and compile a shader
 GLuint gl_compile_shader(char error_buf[256], const char *code, GLenum shader_type);
+// create new shader program from shaders
 GLuint gl_link_program(char error_buf[256], GLuint *shaders, size_t count);
+// create a shader program from vertex shader and fragment shader source
 GLuint gl_compile_and_link_shaders(char error_buf[256], const char *vshader_code, const char *fshader_code);
 // prints a debug message if `attrib` is not found
 GLuint gl_attrib_location(GLuint program, const char *attrib);
 // prints a debug message if `uniform` is not found
 GLint gl_uniform_location(GLuint program, const char *uniform);
+// initialize geometry stuff
 void gl_geometry_init(void);
+// queue a filled rectangle with the given color.
 void gl_geometry_rect(Rect r, u32 color_rgba);
+// queue the border of a rectangle with the given color.
 void gl_geometry_rect_border(Rect r, float border_thickness, u32 color);
+// draw all queued geometry
 void gl_geometry_draw(void);
+// create an OpenGL texture object from an image file.
 GLuint gl_load_texture_from_image(const char *path);
 
 // === ide-autocomplete.c ===
@@ -1122,11 +1177,14 @@ GLuint gl_load_texture_from_image(const char *path);
 void autocomplete_open(Ted *ted, uint32_t trigger);
 void autocomplete_process_lsp_response(Ted *ted, const LSPResponse *response); 
 void autocomplete_select_cursor_completion(Ted *ted);
+// scroll completion list
 void autocomplete_scroll(Ted *ted, i32 by);
+// move cursor to next completion
 void autocomplete_next(Ted *ted);
+// move cursor to previous completion
 void autocomplete_prev(Ted *ted);
+// close completion menu
 void autocomplete_close(Ted *ted);
-void autocomplete_update_suggested(Ted *ted);
 void autocomplete_frame(Ted *ted);
 
 // === ide-definitions.c ===
@@ -1135,11 +1193,15 @@ void autocomplete_frame(Ted *ted);
 // Note: the document position is required for LSP requests because of overloading (where the name
 // alone isn't sufficient)
 void definition_goto(Ted *ted, LSP *lsp, const char *name, LSPDocumentPosition pos, GotoType type);
+// cancel the last go-to-definition / find symbols request.
 void definition_cancel_lookup(Ted *ted);
 void definitions_process_lsp_response(Ted *ted, LSP *lsp, const LSPResponse *response);
+// open the definitions menu
 void definitions_selector_open(Ted *ted);
+// update the definitions menu
 void definitions_selector_update(Ted *ted);
 void definitions_selector_render(Ted *ted, Rect bounds);
+// close the definitions menu
 void definitions_selector_close(Ted *ted);
 void definitions_frame(Ted *ted);
 
@@ -1154,25 +1216,32 @@ void hover_process_lsp_response(Ted *ted, LSPResponse *response);
 void hover_frame(Ted *ted, double dt);
 
 // === ide-signature-help.c ===
-void signature_help_send_request(Ted *ted);
+// figure out new signature help
 void signature_help_retrigger(Ted *ted);
-void signature_help_open(Ted *ted, char32_t trigger);
+// open signature help. `trigger` should either be the trigger character (e.g. ',')
+// or one of the TRIGGER_* constants.
+void signature_help_open(Ted *ted, uint32_t trigger);
 bool signature_help_is_open(Ted *ted);
 void signature_help_close(Ted *ted);
 void signature_help_process_lsp_response(Ted *ted, const LSPResponse *response);
 void signature_help_frame(Ted *ted);
 
 // === ide-usages.c ===
+// cancel the last "find usages" request
 void usages_cancel_lookup(Ted *ted);
+// find usages for word under the cursor in the active buffer.
 void usages_find(Ted *ted);
-void usages_process_lsp_response(Ted *ted, LSPResponse *response);
+void usages_process_lsp_response(Ted *ted, const LSPResponse *response);
 void usages_frame(Ted *ted);
 
 // === menu.c ===
 void menu_close(Ted *ted);
 void menu_open(Ted *ted, Menu menu);
+// process a :escape command (by default this happens when the escape key is pressed)
 void menu_escape(Ted *ted);
+// get width of menu in pixels
 float menu_get_width(Ted *ted);
+// get rectangle which menu takes up
 Rect menu_rect(Ted *ted);
 void menu_update(Ted *ted);
 void menu_render(Ted *ted);
@@ -1185,8 +1254,13 @@ void menu_shell_down(Ted *ted);
 
 // === node.c ===
 void node_switch_to_tab(Ted *ted, Node *node, u16 new_tab_index);
+// 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.
 void node_tab_next(Ted *ted, Node *node, i64 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.
 void node_tab_prev(Ted *ted, Node *node, i64 n);
+// switch to a specific tab. if `tab` is out of range, nothing happens.
 void node_tab_switch(Ted *ted, Node *node, i64 tab);
 // swap the position of two tabs
 void node_tabs_swap(Node *node, u16 tab1, u16 tab2);
@@ -1195,13 +1269,17 @@ void node_free(Node *node);
 i32 node_parent(Ted *ted, u16 node_idx);
 // join this node with its sibling
 void node_join(Ted *ted, Node *node);
+// close a node, WITHOUT checking for unsaved changes
 void node_close(Ted *ted, u16 node_idx);
 // close tab, WITHOUT checking for unsaved changes!
 // returns true if the node is still open
 bool node_tab_close(Ted *ted, Node *node, u16 index);
 void node_frame(Ted *ted, Node *node, Rect r);
+// make a split
 void node_split(Ted *ted, Node *node, bool vertical);
+// switch to the other side of the current split.
 void node_split_switch(Ted *ted);
+// swap the two sides of the current split.
 void node_split_swap(Ted *ted);
 
 // === session.c ===
@@ -1211,11 +1289,20 @@ void session_read(Ted *ted);
 // === syntax.c ===
 Language language_from_str(const char *str);
 const char *language_to_str(Language language);
+// string which should be put before comments in the given language
 const char *language_comment_start(Language l);
+// string which should be put after comments in the given language
 const char *language_comment_end(Language l);
+// get the color setting associated with the given syntax highlighting type
 ColorSetting syntax_char_type_to_color_setting(SyntaxCharType t);
+// returns ')' for '(', etc., or 0 if c is not an opening 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.
 void syntax_highlight(SyntaxState *state, Language lang, const char32_t *line, u32 line_len, SyntaxCharType *char_types);
 
 // === tags.c ===
@@ -1225,6 +1312,7 @@ void tags_generate(Ted *ted, bool run_in_build_window);
 // (still maxing out at `out_size`).
 // each element in `out` should be freed when you're done with them.
 size_t tags_beginning_with(Ted *ted, const char *prefix, char **out, size_t out_size);
+// go to the definition of the given tag
 bool tag_goto(Ted *ted, const char *tag);
 // get all tags in the tags file as SymbolInfos.
 SymbolInfo *tags_get_symbols(Ted *ted);