vis: add doxygen comments

Rename some structures, add typedefs for function pointers, remove unused
arguments from vis_run.

doc/index.rst

@@ -4,6 +4,7 @@ Vis Editor API Documenation
 .. toctree::
    :maxdepth: 2
 
+   vis
    text
    buffer
    array

doc/vis.rst

@@ -0,0 +1,187 @@
+Vis
+===
+
+The core Vis API.
+
+Lifecycle
+---------
+
+.. doxygengroup:: vis_lifecycle
+   :content-only:
+
+Draw
+----
+
+.. doxygengroup:: vis_draw
+   :content-only:
+
+Windows
+-------
+
+.. doxygengroup:: vis_windows
+   :content-only:
+
+Input
+-----
+
+The editor core processes input through a sequences of symbolic keys:
+
+ * Special keys such as ``<Enter>``, ``<Tab>`` or ``<Backspace>`` as reported by
+   `termkey_strfkey <http://www.leonerd.org.uk/code/libtermkey/doc/termkey_strfkey.3.html>`_.
+
+   .. note:: The prefixes ``C-``, ``S-`` and ``M-`` are used to denote the ``Ctrl``,
+             ``Shift`` and ``Alt`` modifiers, respectively.
+
+ * Key action names as registered with `vis_action_register`.
+
+   .. note:: By convention they are prefixed with ``vis-`` as in ``<vis-nop>``.
+
+ * Regular UTF-8 encoded input.
+
+.. note:: An exhaustive list of the first two types is displayed in the ``:help`` output.
+
+.. doxygengroup:: vis_keys
+   :content-only:
+
+Key Map
+-------
+
+The key map is used to translate keys in non-input modes, *before* any key
+bindings are evaluated. It is intended to facilitate usage of non-latin keyboard
+layouts.
+
+.. doxygengroup:: vis_keymap
+   :content-only:
+
+Key Binding
+-----------
+
+Each mode has a set of key bindings. A key binding maps a key to either
+another key (referred to as an alias) or a key action (implementing an
+editor operation).
+
+If a key sequence is ambiguous (i.e. it is a prefix of multiple mappings)
+more input is awaited, until a unique mapping can be resolved.
+
+.. warning:: Key aliases are always evaluated recursively.
+
+.. doxygengroup:: vis_keybind
+   :content-only:
+
+Key Action
+----------
+
+A key action is invoked by a key binding and implements a certain editor function.
+
+The editor operates like a finite state machine with key sequences as
+transition labels. Once a prefix of the input queue uniquely refers to a
+key action, it is invoked with the remainder of the input queue passed as argument.
+
+.. note:: A triggered key action currently does not know through which key binding
+          it was invoked. TODO: change that?
+
+.. doxygengroup:: vis_action
+   :content-only:
+
+Modes
+-----
+
+A mode defines *enter*, *leave* and *idle* actions and captures a set of
+key bindings.
+
+Modes are hierarchical, key bindings are searched recursively towards
+the top of the hierarchy stopping at the first match.
+
+.. doxygenenum:: VisMode
+.. doxygengroup:: vis_modes
+   :content-only:
+
+Count
+-----
+
+Dictates how many times a motion or text object is evaluated. If none
+is specified, a minimal count of 1 is assumed.
+
+.. doxygengroup:: vis_count
+   :content-only:
+
+Operators
+---------
+
+.. doxygengroup:: vis_operators
+   :content-only:
+
+Motions
+-------
+
+.. doxygengroup:: vis_motions
+   :content-only:
+
+Text Objects
+------------
+
+.. doxygengroup:: vis_textobjs
+   :content-only:
+
+Marks
+-----
+
+Marks keep track of a given text position.
+
+.. note:: Marks are currently file local.
+
+.. doxygengroup:: vis_marks
+   :content-only:
+
+Registers
+---------
+
+.. doxygengroup:: vis_registers
+   :content-only:
+
+Macros
+------
+
+Macros are a sequence of keys stored in a Register which can be reprocessed
+as if entered by the user.
+
+.. warning:: Macro support is currently half-baked. If you do something stupid
+             (e.g. use mutually recursive macros), you will likely encounter
+             stack overflows.
+
+.. doxygengroup:: vis_macros
+   :content-only:
+
+Commands
+--------
+
+.. doxygengroup:: vis_cmds
+   :content-only:
+
+Options
+-------
+
+.. doxygengroup:: vis_options
+   :content-only:
+
+Modification
+------------
+
+These function operate on the currently focused window but ensure that
+all windows which show the affected region are redrawn too.
+
+.. doxygengroup:: vis_changes
+   :content-only:
+
+Interaction
+-----------
+
+.. doxygengroup:: vis_info
+   :content-only:
+
+Miscellaneous
+-------------
+
+.. doxygengroup:: vis_misc
+   :content-only:
+

main.c

@@ -2167,7 +2167,7 @@ int main(int argc, char *argv[]) {
 			vis_prompt_cmd(vis, cmd);
 	}
 
-	int status = vis_run(vis, argc, argv);
+	int status = vis_run(vis);
 	vis_free(vis);
 	return status;
 }

vis-cmds.c

@@ -6,7 +6,7 @@
 // FIXME: avoid this redirection?
 typedef struct {
 	CommandDef def;
-	CmdFunc *func;
+	VisCommandFunction *func;
 	void *data;
 } CmdUser;
 
@@ -18,7 +18,7 @@ static void cmdfree(CmdUser *cmd) {
 	free(cmd);
 }
 
-bool vis_cmd_register(Vis *vis, const char *name, const char *help, void *data, CmdFunc *func) {
+bool vis_cmd_register(Vis *vis, const char *name, const char *help, void *data, VisCommandFunction *func) {
 	if (!name)
 		return false;
 	if (!vis->usercmds && !(vis->usercmds = map_new()))

vis-motions.c

@@ -293,8 +293,7 @@ void vis_motion_type(Vis *vis, enum VisMotionType type) {
 	vis->action.type = type;
 }
 
-int vis_motion_register(Vis *vis, enum VisMotionType type, void *data,
-	size_t (*motion)(Vis*, Win*, void*, size_t pos)) {
+int vis_motion_register(Vis *vis, enum VisMotionType type, void *data, VisMotionFunction *motion) {
 
 	Movement *move = calloc(1, sizeof *move);
 	if (!move)

vis-text-objects.c

@@ -2,8 +2,7 @@
 #include "text-objects.h"
 #include "util.h"
 
-int vis_textobject_register(Vis *vis, int type, void *data,
-	Filerange (*textobject)(Vis*, Win*, void*, size_t pos)) {
+int vis_textobject_register(Vis *vis, int type, void *data, VisTextObjectFunction *textobject) {
 
 	TextObject *obj = calloc(1, sizeof *obj);
 	if (!obj)

vis.c

@@ -558,6 +558,10 @@ void vis_suspend(Vis *vis) {
 	vis->ui->suspend(vis->ui);
 }
 
+void vis_resume(Vis *vis) {
+	vis->ui->resume(vis->ui);
+}
+
 bool vis_window_new(Vis *vis, const char *filename) {
 	File *file = file_new(vis, filename);
 	if (!file)
@@ -1298,7 +1302,7 @@ bool vis_signal_handler(Vis *vis, int signum, const siginfo_t *siginfo, const vo
 	return false;
 }
 
-int vis_run(Vis *vis, int argc, char *argv[]) {
+int vis_run(Vis *vis) {
 	if (!vis->windows)
 		return EXIT_SUCCESS;
 	if (vis->exit_status != -1)
@@ -1347,9 +1351,10 @@ int vis_run(Vis *vis, int argc, char *argv[]) {
 		}
 
 		if (vis->resume) {
-			vis->ui->resume(vis->ui);
+			vis_resume(vis);
 			vis->resume = false;
 		}
+
 		if (vis->need_resize) {
 			vis->ui->resize(vis->ui);
 			vis->need_resize = false;