finished documenting ted.h

7 files changed, 73 insertions, 18 deletions

diff --git a/base.h b/base.h
index 21ff3a3..32229e0 100644
--- a/base.h
+++ b/base.h
@@ -122,7 +122,10 @@ typedef unsigned long long ullong;
 #define PRINTF_FORMAT_STRING
 #endif
 
-#define Status bool WarnUnusedResult // false = error, true = success
+// this type is an alias for bool, except that it
+// produces a warning if it's not used.
+// false = error, true = success
+#define Status bool WarnUnusedResult
 
 #define arr_count(a) (sizeof (a) / sizeof *(a))
 
diff --git a/lsp.h b/lsp.h
index e3f3bcf..6f3c047 100644
--- a/lsp.h
+++ b/lsp.h
@@ -8,8 +8,11 @@
 #include "ds.h"
 #include "os.h"
 
+// a document ID. 0 is a valid document ID, currently.
 typedef u32 LSPDocumentID;
+// ID of an LSP server. a server's ID is never 0.
 typedef u32 LSPID;
+// a request ID. this is unique across all servers. a request's ID is never 0.
 typedef u32 LSPRequestID;
 typedef struct SDL_mutex *LSPMutex;
 typedef struct SDL_semaphore *LSPSemaphore;
diff --git a/main.c b/main.c
index 0588752..513258f 100644
--- a/main.c
+++ b/main.c
@@ -1,7 +1,6 @@
 /*
 @TODO:
-- ted.h documentation
-- document lsp.h and lsp.c.
+- document lsp.h.
 - debug-lsp option (which logs LSP messages)
 - check LSP process status (TEST: what happens if LSP server is not installed)
 - make tags_dir the root folder
@@ -876,7 +875,7 @@ int main(int argc, char **argv) {
 		glViewport(0, 0, (GLsizei)window_width, (GLsizei)window_height);
 		{ // clear (background)
 			float bg_color[4];
-			rgba_u32_to_floats(ted_color(ted, COLOR_BG), bg_color);
+			rgba_u32_to_floats(ted_active_color(ted, COLOR_BG), bg_color);
 			glClearColor(bg_color[0], bg_color[1], bg_color[2], bg_color[3]);
 		}
 		glClear(GL_COLOR_BUFFER_BIT);
@@ -973,7 +972,7 @@ int main(int argc, char **argv) {
 			} else {
 				autocomplete_close(ted);
 				text_utf8_anchored(font, "Press Ctrl+O to open a file or Ctrl+N to create a new one.",
-					window_width * 0.5f, window_height * 0.5f, ted_color(ted, COLOR_TEXT_SECONDARY), ANCHOR_MIDDLE);
+					window_width * 0.5f, window_height * 0.5f, ted_active_color(ted, COLOR_TEXT_SECONDARY), ANCHOR_MIDDLE);
 				text_render(font);
 			}
 		}
@@ -1026,8 +1025,8 @@ int main(int argc, char **argv) {
 				
 				ted_color_settings_for_message_type(ted->message_type, &bg_color, &border_color);
 				
-				gl_geometry_rect(r, ted_color(ted, bg_color));
-				gl_geometry_rect_border(r, settings->border_thickness, ted_color(ted, border_color));
+				gl_geometry_rect(r, ted_active_color(ted, bg_color));
+				gl_geometry_rect_border(r, settings->border_thickness, ted_active_color(ted, border_color));
 
 				float text_x1 = rect_x1(r) + padding, text_x2 = rect_x2(r) - padding;
 				float text_y1 = rect_y1(r) + padding;
@@ -1039,7 +1038,7 @@ int main(int argc, char **argv) {
 				text_state.x = text_x1;
 				text_state.y = text_y1;
 				text_state.wrap = true;
-				rgba_u32_to_floats(ted_color(ted, COLOR_TEXT), text_state.color);
+				rgba_u32_to_floats(ted_active_color(ted, COLOR_TEXT), text_state.color);
 				text_utf8_with_state(font, &text_state, ted->message_shown);
 				gl_geometry_draw();
 				text_render(font);
diff --git a/tags.c b/tags.c
index da974b9..6dd20d3 100644
--- a/tags.c
+++ b/tags.c
@@ -374,7 +374,7 @@ SymbolInfo *tags_get_symbols(Ted *ted) {
 	if (!file) return NULL;
 	
 	SymbolInfo *infos = NULL;
-	u32 color = ted_color(ted, COLOR_TEXT);
+	u32 color = ted_active_color(ted, COLOR_TEXT);
 	if (file) {
 		char line[1024];
 		while (fgets(line, sizeof line, file)) {
diff --git a/ted.c b/ted.c
index 987193e..c718dc2 100644
--- a/ted.c
+++ b/ted.c
@@ -109,7 +109,7 @@ char *ted_get_root_dir_of(Ted *ted, const char *path) {
 // the return value should be freed
 char *ted_get_root_dir(Ted *ted) {
 	TextBuffer *buffer = ted->active_buffer;
-	if (buffer) {
+	if (buffer && buffer_is_named_file(buffer)) {
 		return ted_get_root_dir_of(ted, buffer->path);
 	} else {
 		return ted_get_root_dir_of(ted, ted->cwd);
@@ -214,7 +214,7 @@ LSP *ted_active_lsp(Ted *ted) {
 	return buffer_lsp(ted->active_buffer);
 }
 
-u32 ted_color(Ted *ted, ColorSetting color) {
+u32 ted_active_color(Ted *ted, ColorSetting color) {
 	return ted_active_settings(ted)->colors[color];
 }
 
@@ -226,7 +226,6 @@ static bool ted_is_regular_buffer(Ted *ted, TextBuffer *buffer) {
 	return buffer >= ted->buffers && buffer < ted->buffers + TED_MAX_BUFFERS;
 }
 
-// Check the various places a file could be, and return the full path.
 Status ted_get_file(Ted const *ted, const char *name, char *out, size_t outsz) {
 	if (ted->search_start_cwd && fs_file_exists(name)) {
 		// check in start_cwd
@@ -310,7 +309,6 @@ void ted_switch_to_buffer(Ted *ted, TextBuffer *buffer) {
 	
 }
 
-// set ted->active_buffer to something nice
 void ted_reset_active_buffer(Ted *ted) {
 	if (ted->nodes_used[0]) {
 		Node *node = &ted->nodes[0];
@@ -422,6 +420,11 @@ TextBuffer *ted_get_buffer_with_file(Ted *ted, const char *path) {
 }
 
 bool ted_open_file(Ted *ted, const char *filename) {
+	if (!filename) {
+		assert(0);
+		return false;
+	}
+	
 	char path[TED_PATH_MAX];
 	ted_path_full(ted, filename, path, sizeof path);
 
@@ -600,7 +603,6 @@ bool ted_get_mouse_buffer_pos(Ted *ted, TextBuffer **pbuffer, BufferPos *ppos) {
 	return false;
 }
 
-// make the cursor red for a bit to indicate an error (e.g. no autocompletions)
 void ted_flash_error_cursor(Ted *ted) {
 	ted->cursor_error_time = ted->frame_time;
 }
@@ -635,7 +637,10 @@ void ted_go_to_lsp_document_position(Ted *ted, LSP *lsp, LSPDocumentPosition pos
 }
 
 void ted_cancel_lsp_request(Ted *ted, LSPID lsp, LSPRequestID request) {
-	lsp_cancel_request(ted_get_lsp_by_id(ted, lsp), request);
+	if (!request) return;
+	LSP *lsp_obj = ted_get_lsp_by_id(ted, lsp);
+	if (!lsp_obj) return;
+	lsp_cancel_request(lsp_obj, request);
 }
 
 
diff --git a/ted.cfg b/ted.cfg
index 4ab4aa7..1841542 100644
--- a/ted.cfg
+++ b/ted.cfg
@@ -187,6 +187,8 @@ Ctrl+s = :save
 Ctrl+Alt+Shift+s = :save-all
 Ctrl+Shift+s = :save-as
 Ctrl+q = :quit
+# reload all buffers from their files.
+# this doesn't affect buffers with unsaved changes.
 Ctrl+Shift+r = :reload-all
 
 # You can do something like this:
@@ -339,7 +341,7 @@ hover-text = #fff
 hover-hl = #ffc4
 # these control the text color for various kinds of completions
 autocomplete-variable = #bfb
-autocomplete-function = #aaf
+autocomplete-function = #fec
 autocomplete-type = #faf
 
 
diff --git a/ted.h b/ted.h
index 7353606..ff24530 100644
--- a/ted.h
+++ b/ted.h
@@ -1332,30 +1332,60 @@ 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
 void *ted_malloc(Ted *ted, size_t size);
+// 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
 void *ted_realloc(Ted *ted, void *p, size_t new_size);
+// Check the various places a ted data file could be
+// (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.
 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 `path`, or NULL if there is none.
 TextBuffer *ted_get_buffer_with_file(Ted *ted, const char *path);
+// save all buffers
 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.
 void ted_load_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
 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 by ID. Returns NULL if there is no LSP with that ID.
 LSP *ted_get_lsp_by_id(Ted *ted, LSPID id);
+// 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
+// specified for the given path and language).
 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.
 LSP *ted_active_lsp(Ted *ted);
-u32 ted_color(Ted *ted, ColorSetting color);
+// get the value of the given color setting, according to `ted_active_settings(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.
 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.
 bool ted_new_file(Ted *ted, const char *filename);
 // returns the index of an available buffer, or -1 if none are available 
 i32 ted_new_buffer(Ted *ted);
@@ -1371,12 +1401,22 @@ bool ted_save_all(Ted *ted);
 void ted_switch_to_buffer(Ted *ted, TextBuffer *buffer);
 // switch to this node
 void ted_node_switch(Ted *ted, Node *node);
+// load ted.cfg files
 void ted_load_configs(Ted *ted, bool reloading);
+// handle a key press
 void ted_press_key(Ted *ted, SDL_Keycode keycode, SDL_Keymod modifier);
-bool ted_get_mouse_buffer_pos(Ted *ted, TextBuffer **pbuffer, BufferPos *ppos);
+// get the buffer and buffer position where the mouse is.
+// 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);
+// go to `path` at line `line` and index `index`, opening a new buffer if necessary.
+// if `is_lsp` is set to true, `index` is interpreted as a UTF-16 offset rather than a UTF-32 offset.
 void ted_go_to_position(Ted *ted, const char *path, u32 line, u32 index, bool is_lsp);
+// go to this LSP document position, opening a new buffer containing the file if necessary.
 void ted_go_to_lsp_document_position(Ted *ted, LSP *lsp, LSPDocumentPosition position);
+// cancel this LSP request. if `lsp` or `request` is 0,
+// or if `lsp` is not a valid LSP ID, nothing happens.
 void ted_cancel_lsp_request(Ted *ted, LSPID lsp, LSPRequestID request);
 // how tall is a line buffer?
 float ted_line_buffer_height(Ted *ted);
@@ -1388,7 +1428,9 @@ MessageType ted_message_type_from_lsp(LSPWindowMessageType type);
 void ted_color_settings_for_message_type(MessageType type, ColorSetting *bg_color, ColorSetting *border_color);
 
 // === ui.c ===
+// move selector cursor up by `n` entries
 void selector_up(Ted *ted, Selector *s, i64 n);
+// move selector cursor down by `n` entries
 void selector_down(Ted *ted, Selector *s, i64 n);
 // sort entries alphabetically
 void selector_sort_entries_by_name(Selector *s);
@@ -1407,6 +1449,7 @@ vec2 button_get_size(Ted *ted, const char *text);
 void button_render(Ted *ted, Rect button, const char *text, u32 color);
 // 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
 PopupOption popup_update(Ted *ted, u32 options);
 void popup_render(Ted *ted, u32 options, const char *title, const char *body);
 vec2 checkbox_frame(Ted *ted, bool *value, const char *label, vec2 pos);