fix up docs

5 files changed, 78 insertions, 61 deletions

diff --git a/Doxyfile b/Doxyfile
index a647a92..14c0fc4 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -18,6 +18,8 @@ ENABLE_PREPROCESSING   = YES
 MULTILINE_CPP_IS_BRIEF = YES
 AUTOLINK_SUPPORT       = NO
 DISTRIBUTE_GROUP_DOC   = YES
-EXTRACT_STATIC         = YE
+EXTRACT_STATIC         = YES
 COLLABORATION_GRAPH    = NO
-EXCLUDE                = lsp.h, keywords.h, pcre-inc.h, sdl-inc.h
+EXCLUDE                = keywords.h, pcre-inc.h, sdl-inc.h
+WARN_IF_UNDOCUMENTED   = NO
+QUIET                  = YES
diff --git a/command.h b/command.h
index 15c824b..9c91011 100644
--- a/command.h
+++ b/command.h
@@ -47,6 +47,7 @@ typedef enum {
 	CMD_START_OF_FILE,
 	/// move cursor to end of buffer
 	CMD_END_OF_FILE,
+	/// go to previous position
 	CMD_PREVIOUS_POSITION,
 	CMD_SELECT_START_OF_FILE,
 	CMD_SELECT_END_OF_FILE,
diff --git a/lsp.h b/lsp.h
index 2f1720d..dd7288f 100644
--- a/lsp.h
+++ b/lsp.h
@@ -1,5 +1,7 @@
-// functions for dealing with LSP (Language Server Protocol) servers.
-// don't assume any of the public functions defined here are thread-safe.
+/// \file
+/// functions for dealing with LSP (Language Server Protocol) servers.
+///
+/// don't assume any of the public functions defined here are thread-safe.
 
 #ifndef LSP_H_
 #define LSP_H_
@@ -8,30 +10,30 @@
 #include "ds.h"
 #include "os.h"
 
-// an ID specific to a path. a document's ID is never 0 (thanks to lsp_create).
+/// an ID specific to a path. a document's ID is never 0 (thanks to lsp_create).
 typedef u32 LSPDocumentID;
-// ID of an LSP server. a server's ID is never 0.
+/// 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.
+/// 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;
 typedef struct SDL_Thread *LSPThread;
 
-// a struct for keeping track of a LSP server ID and a request ID
+/// a struct for keeping track of a LSP server ID and a request ID
 typedef struct {
 	LSPID lsp;
 	LSPRequestID id;
 } LSPServerRequestID;
 
-// interface Position in the LSP spec
+/// `interface Position` in the LSP spec
 typedef struct {
 	u32 line;
 	// NOTE: this is the UTF-16 character index!
 	u32 character;
 } LSPPosition;
 
-// interface TextDocumentPositionParams in the LSP spec
+/// `interface TextDocumentPositionParams` in the LSP spec
 typedef struct {
 	LSPDocumentID document;
 	LSPPosition pos;
@@ -42,19 +44,19 @@ typedef enum {
 	LSP_RESPONSE
 } LSPMessageType;
 
-// A string in a LSPResponse
+/// A string in a `LSPResponse`
 typedef struct {
 	// offset into string_data
 	u32 offset;
 } LSPString;
 
-// interface Range in the LSP spec
+/// `interface Range` in the LSP spec
 typedef struct {
 	LSPPosition start;
 	LSPPosition end;
 } LSPRange;
 
-// interface Location in the LSP spec
+/// `interface Location` in the LSP spec
 typedef struct {
 	LSPDocumentID document;
 	LSPRange range;
@@ -64,32 +66,32 @@ typedef enum {
 	LSP_REQUEST_NONE,
 	
 	// client-to-server
-	LSP_REQUEST_INITIALIZE, // initialize
-	LSP_REQUEST_INITIALIZED, // initialized
-	LSP_REQUEST_CANCEL, // $/cancelRequest
-	LSP_REQUEST_CONFIGURATION, // workspace/didChangeConfiguration
-	LSP_REQUEST_SHUTDOWN, // shutdown
-	LSP_REQUEST_EXIT, // exit
-	LSP_REQUEST_DID_OPEN, // textDocument/didOpen
-	LSP_REQUEST_DID_CLOSE, // textDocument/didClose
-	LSP_REQUEST_DID_CHANGE, // textDocument/didChange
-	LSP_REQUEST_COMPLETION, // textDocument/completion
-	LSP_REQUEST_SIGNATURE_HELP, // textDocument/signatureHelp
-	LSP_REQUEST_HOVER, // textDocument/hover
-	LSP_REQUEST_DEFINITION, // textDocument/definition
-	LSP_REQUEST_DECLARATION, // textDocument/declaration
-	LSP_REQUEST_TYPE_DEFINITION, // textDocument/typeDefinition
-	LSP_REQUEST_IMPLEMENTATION, // textDocument/implementation
-	LSP_REQUEST_HIGHLIGHT, // textDocument/documentHighlight
-	LSP_REQUEST_REFERENCES, // textDocument/references
-	LSP_REQUEST_RENAME, // textDocument/rename
-	LSP_REQUEST_WORKSPACE_SYMBOLS, // workspace/symbol
-	LSP_REQUEST_DID_CHANGE_WORKSPACE_FOLDERS, // workspace/didChangeWorkspaceFolders
+	LSP_REQUEST_INITIALIZE, //< initialize
+	LSP_REQUEST_INITIALIZED, //< initialized
+	LSP_REQUEST_CANCEL, //< $/cancelRequest
+	LSP_REQUEST_CONFIGURATION, //< workspace/didChangeConfiguration
+	LSP_REQUEST_SHUTDOWN, //< shutdown
+	LSP_REQUEST_EXIT, //< exit
+	LSP_REQUEST_DID_OPEN, //< textDocument/didOpen
+	LSP_REQUEST_DID_CLOSE, //< textDocument/didClose
+	LSP_REQUEST_DID_CHANGE, //< textDocument/didChange
+	LSP_REQUEST_COMPLETION, //< textDocument/completion
+	LSP_REQUEST_SIGNATURE_HELP, //< textDocument/signatureHelp
+	LSP_REQUEST_HOVER, //< textDocument/hover
+	LSP_REQUEST_DEFINITION, //< textDocument/definition
+	LSP_REQUEST_DECLARATION, //< textDocument/declaration
+	LSP_REQUEST_TYPE_DEFINITION, //< textDocument/typeDefinition
+	LSP_REQUEST_IMPLEMENTATION, //< textDocument/implementation
+	LSP_REQUEST_HIGHLIGHT, //< textDocument/documentHighlight
+	LSP_REQUEST_REFERENCES, //< textDocument/references
+	LSP_REQUEST_RENAME, //< textDocument/rename
+	LSP_REQUEST_WORKSPACE_SYMBOLS, //< workspace/symbol
+	LSP_REQUEST_DID_CHANGE_WORKSPACE_FOLDERS, //< workspace/didChangeWorkspaceFolders
 	
 	// server-to-client
-	LSP_REQUEST_SHOW_MESSAGE, // window/showMessage and window/showMessageRequest
-	LSP_REQUEST_LOG_MESSAGE, // window/logMessage
-	LSP_REQUEST_WORKSPACE_FOLDERS, // workspace/workspaceFolders - NOTE: this is handled directly in lsp-parse.c (because it only needs information from the LSP struct)
+	LSP_REQUEST_SHOW_MESSAGE, //< window/showMessage and window/showMessageRequest
+	LSP_REQUEST_LOG_MESSAGE, //< window/logMessage
+	LSP_REQUEST_WORKSPACE_FOLDERS, //< workspace/workspaceFolders - NOTE: this is handled directly in lsp-parse.c (because it only needs information from the LSP struct)
 } LSPRequestType;
 
 typedef enum {
@@ -113,7 +115,7 @@ typedef struct {
 typedef struct {
 	u64 language;
 	LSPDocumentID document;
-	// freed by lsp_request_free
+	// freed by \ref lsp_request_free
 	char *file_contents;
 } LSPRequestDidOpen;
 
@@ -124,7 +126,7 @@ typedef struct {
 // see TextDocumentContentChangeEvent in the LSP spec
 typedef struct {
 	LSPRange range;
-	// new text. will be freed. you can use NULL for the empty string.
+	/// new text. will be freed. you can use NULL for the empty string.
 	char *text;
 } LSPDocumentChangeEvent;
 
@@ -142,12 +144,12 @@ typedef enum {
 
 typedef struct {
 	LSPWindowMessageType type;
-	// freed by lsp_request_free
+	// freed by \ref lsp_request_free
 	char *message;
 } LSPRequestMessage;
 
 
-// these triggers are used for completion context and signature help context.
+/// these triggers are used for completion context and signature help context.
 #define LSP_TRIGGER_NONE 0 // not actually defined in LSP spec
 #define LSP_TRIGGER_INVOKED 1
 #define LSP_TRIGGER_CHARACTER 2
@@ -721,9 +723,9 @@ void json_debug_print_object(const JSON *json, JSONObject obj);
 void json_debug_print_string(const JSON *json, JSONString string);
 void json_debug_print_value(const JSON *json, JSONValue value);
 void json_free(JSON *json);
-// NOTE: text must live as long as json!!!
+/// NOTE: text must live as long as json!!!
 bool json_parse(JSON *json, const char *text);
-// like json_parse, but a copy of text is made, so you can free/overwrite it immediately.
+/// like json_parse, but a copy of text is made, so you can free/overwrite it immediately.
 bool json_parse_copy(JSON *json, const char *text);
 JSONValue json_object_get(const JSON *json, JSONObject object, const char *name);
 JSONValue json_array_get(const JSON *json, JSONArray array, u64 i);
@@ -748,15 +750,15 @@ JSONValue json_root(const JSON *json);
 JSONValue json_get(const JSON *json, const char *path);
 bool json_has(const JSON *json, const char *path);
 void json_string_get(const JSON *json, JSONString string, char *buf, size_t buf_sz);
-// returns a malloc'd null-terminated string.
+/// returns a malloc'd null-terminated string.
 char *json_string_get_alloc(const JSON *json, JSONString string);
 void json_debug_print(const JSON *json);
 size_t json_escape_to(char *out, size_t out_sz, const char *in);
 char *json_escape(const char *str);
 
-// print server-to-client communication
+/// print server-to-client communication
 #define LSP_SHOW_S2C 0
-// print client-to-server communication
+/// print client-to-server communication
 #define LSP_SHOW_C2S 0
 
 #endif // LSP_INTERNAL
diff --git a/os.h b/os.h
index 6b9389a..48d67c3 100644
--- a/os.h
+++ b/os.h
@@ -86,7 +86,7 @@ static void time_sleep_s(u64 s) {
 	time_sleep_ns(s * 1000000000);
 }
 
-
+/// a process
 typedef struct Process Process;
 
 /// zero everything except what you're using
diff --git a/ted.h b/ted.h
index 25dfd0a..1a22996 100644
--- a/ted.h
+++ b/ted.h
@@ -293,8 +293,12 @@ typedef struct {
 
 /// A position in the buffer
 typedef struct {
+	/// line number (0-indexed)
 	u32 line;
-	u32 index; // index of character in line (not the same as column, since a tab is settings->tab_width columns)
+	/// UTF-32 index of character in line
+	///
+	/// (not the same as column, since a tab is `settings->tab_width` columns)
+	u32 index;
 } BufferPos;
 
 /// A single line in a buffer
@@ -342,17 +346,19 @@ typedef struct {
 	char *path;
 	/// we keep a back-pointer to the ted instance so we don't have to pass it in to every buffer function
 	struct Ted *ted;
-	/// number of characters scrolled in the x/y direction
-	double scroll_x, scroll_y;
-	/// last write time to `path`
+	/// number of characters scrolled in the x direction
+	double scroll_x;
+	/// number of characters scrolled in the y direction
+	double scroll_y;
+	/// last write time to \ref path
 	double last_write_time;
-	/// the language the buffer has been manually set to, or `LANG_NONE` if it hasn't been set to anything
+	/// the language the buffer has been manually set to, or \ref LANG_NONE if it hasn't been set to anything
 	i64 manual_language;
 	/// position of cursor
 	BufferPos cursor_pos;
-	/// if `selection` is true, the text between `selection_pos` and `cursor_pos` is selected.
+	/// if \ref selection is true, the text between \ref selection_pos and \ref cursor_pos is selected.
 	BufferPos selection_pos;
-	/// "previous" position of cursor, for CMD_PREVIOUS_POSITION
+	/// "previous" position of cursor, for \ref CMD_PREVIOUS_POSITION
 	BufferPos prev_cursor_pos;
 	/// "line buffers" are buffers which can only have one line of text (used for inputs)
 	bool is_line_buffer;
@@ -372,13 +378,19 @@ typedef struct {
 	/// (line buffers only) set to true when submitted. you have to reset it to false.
 	bool line_buffer_submitted;
 	/// If set to true, buffer will be scrolled to the cursor position next frame.
-	/// This is to fix the problem that x1,y1,x2,y2 are not updated until the buffer is rendered.
-	bool center_cursor_next_frame; 
-	/// buffer's rectangle on screen
-	float x1, y1, x2, y2;
+	/// This is to fix the problem that \ref x1, \ref y1, \ref x2, \ref y2 are not updated until the buffer is rendered.
+	bool center_cursor_next_frame;
+	/// x coordinate of left side of buffer
+	float x1;
+	/// y coordinate of top side of buffer
+	float y1;
+	/// x coordinate of right side of buffer
+	float x2;
+	/// y coordinate of bottom side of buffer
+	float y2;
 	/// number of lines in buffer
 	u32 nlines;
-	/// capacity of `lines`
+	/// capacity of \ref lines
 	u32 lines_capacity;
 	
 	/// which LSP this document is open in
@@ -389,8 +401,8 @@ typedef struct {
 	/// which lines are on screen? updated when \ref buffer_render is called.
 	u32 first_line_on_screen, last_line_on_screen;
 
-	// to cache syntax highlighting properly, it is important to keep track of the
-	// first and last line modified since last frame.
+	/// to cache syntax highlighting properly, it is important to keep track of the
+	/// first and last line modified since last frame.
 	u32 frame_earliest_line_modified;
 	/// see \ref frame_earliest_line_modified.
 	u32 frame_latest_line_modified;