commit 82723082181a863b7bc7c7cbbcc92da5c30caf6d
parent 7a64b99342bd37248395655399b5a4ef2334b4fe
Author: lumidify <nobody@lumidify.org>
Date: Fri, 3 Dec 2021 23:02:10 +0100
Add some more documentation
Diffstat:
10 files changed, 73 insertions(+), 9 deletions(-)
diff --git a/action.h b/action.h
@@ -1,9 +0,0 @@
-enum action_type {
- ACTION_NONE, /* pass next key to basic key handler */
- ACTION_GRABKEY /* pass next key to given callback */
-};
-
-struct action {
- enum action_type type;
- struct action (*callback)(ledit_buffer *buffer, XEvent *event, int lang_index);
-};
diff --git a/keys.h b/keys.h
@@ -1,5 +1,9 @@
#define LENGTH(X) (sizeof(X) / sizeof(X[0]))
+/*
+ * These are the language strings compared with the language strings that
+ * xkb gives in order to change the key mapping on layout change events.
+ */
#define KEY_LANGS \
static char *key_langs[] = { \
"English (US)", \
@@ -21,8 +25,11 @@ static struct { \
#define LANG_KEYS(index) &keys[index]
+/* get the index of a language with the given name, or -1 if none exists */
int get_language_index(char *lang);
+/* match a modifier key mask with a key state, ignoring some unimportant parts */
int match_key(unsigned int mask, unsigned int state);
+/* preprocess key, i.e. get the KeySym and text corresponding to it */
void preprocess_key(
ledit_window *window, XEvent *event, KeySym *sym_ret,
char *buf_ret, int buf_size, int *buf_len_ret
diff --git a/keys_basic.c b/keys_basic.c
@@ -430,6 +430,7 @@ delete_range(
txtbuf_destroy(buf);
}
+/* FIXME: better interface for this; documentation */
static void
insert_text(
ledit_view *view,
diff --git a/keys_basic.h b/keys_basic.h
@@ -1,2 +1,3 @@
+/* perform cleanup of global data */
void basic_key_cleanup(void);
struct action basic_key_handler(ledit_view *view, XEvent *event, int lang_index);
diff --git a/keys_basic_config.h b/keys_basic_config.h
@@ -1,3 +1,7 @@
+/*
+ * These are all the regular keys used in normal, visual, and insert mode.
+ */
+
/* FIXME: these aren't really used properly */
enum key_type {
KEY_NONE = 0,
@@ -98,6 +102,7 @@ static struct action toggle_hard_line_based(ledit_view *view, char *text, size_t
/* FIXME: maybe sort these and use binary search
-> but that would mess with the catch-all keys */
+/* FIXME: sort out the key types */
static struct key keys_en[] = {
{NULL, 0, XK_BackSpace, INSERT, KEY_ANY, KEY_ANY, &backspace},
{NULL, 0, XK_Left, VISUAL|INSERT|NORMAL, KEY_ANY, KEY_ANY, &cursor_left},
diff --git a/keys_command_config.h b/keys_command_config.h
@@ -1,3 +1,9 @@
+/*
+ * These are the keys used by special commands that require a special key
+ * handler. This includes keys used to edit the line entry at the bottom
+ * and keys used for confirmation (e.g. when substituting).
+ */
+
static int substitute_yes(ledit_view *view, char *key_text, size_t len);
static int substitute_yes_all(ledit_view *view, char *key_text, size_t len);
static int substitute_no(ledit_view *view, char *key_text, size_t len);
diff --git a/memory.h b/memory.h
@@ -1,8 +1,16 @@
+/*
+ * These functions all wrap the regular functions but exit on error.
+ */
+
char *ledit_strdup(const char *s);
char *ledit_strndup(const char *s, size_t n);
void *ledit_malloc(size_t size);
void *ledit_calloc(size_t nmemb, size_t size);
void *ledit_realloc(void *ptr, size_t size);
+/*
+ * This is different than the normal strcat - it allocates memory for
+ * a new string to hold the concatenation of str1 and str2.
+ */
char *ledit_strcat(const char *str1, const char *str2);
void *ledit_reallocarray(void *optr, size_t nmemb, size_t size);
diff --git a/theme_config.h b/theme_config.h
@@ -1,3 +1,4 @@
+/* FIXME: configure font here */
static const int TEXT_SIZE = 12;
static const char *TEXT_FG = "#000000";
static const char *TEXT_BG = "#FFFFFF";
diff --git a/txtbuf.h b/txtbuf.h
@@ -1,11 +1,40 @@
+/*
+ * txtbuf is really just a string data type that is badly named.
+ */
+
typedef struct {
size_t len, cap;
char *text;
} txtbuf;
+/*
+ * Create an empty txtbuf.
+ */
txtbuf *txtbuf_new(void);
+
+/*
+ * Make sure the txtbuf has space for at least the given size,
+ * plus '\0' at the end.
+ */
void txtbuf_grow(txtbuf *buf, size_t sz);
+
+/*
+ * Shrink a textbuf, if the allocated space is much larger than the text.
+ */
+/* FIXME: actually use this */
void txtbuf_shrink(txtbuf *buf);
+
+/*
+ * Destroy a txtbuf.
+ */
void txtbuf_destroy(txtbuf *buf);
+
+/*
+ * Copy txtbuf 'src' to txtbuf 'dst'.
+ */
void txtbuf_copy(txtbuf *dst, txtbuf *src);
+
+/*
+ * Duplicate txtbuf 'src'.
+ */
txtbuf *txtbuf_dup(txtbuf *src);
diff --git a/util.h b/util.h
@@ -1,11 +1,26 @@
/* FIXME: rename this to draw_util.h and rename macros.h to util.h */
+/*
+ * This is just a basic wrapper for XftDraws and Pixmaps
+ * that is used by the window for its text display at the bottom.
+ */
typedef struct {
XftDraw *xftdraw;
Pixmap pixmap;
int w, h;
} ledit_draw;
+/*
+ * Create a draw with the specified width and height.
+ */
ledit_draw *draw_create(ledit_window *window, int w, int h);
+
+/*
+ * Make sure the size of the draw is at least the given width and height.
+ */
void draw_grow(ledit_window *window, ledit_draw *draw, int w, int h);
+
+/*
+ * Destroy a draw.
+ */
void draw_destroy(ledit_window *window, ledit_draw *draw);
