vis-lua: more extensive Lua API documentation

5 files changed, 281 insertions, 33 deletions

diff --git a/Makefile b/Makefile
index c2b4d04..42260b9 100644
--- a/Makefile
+++ b/Makefile
@@ -86,8 +86,10 @@ man:
 	done
 
 luadoc:
-	@ldoc -p "Vis Editor" -f markdown -M vis-lua.c -s '!pale' && \
-	sed -e "s/RELEASE/${VERSION}/" -i doc/index.html
+	@cd luadoc && ldoc . && sed -e "s/RELEASE/${VERSION}/" -i index.html
+
+luadoc-all:
+	@cd luadoc && ldoc -a . && sed -e "s/RELEASE/${VERSION}/" -i index.html
 
 install: vis vis-menu
 	@echo stripping executable
@@ -127,4 +129,4 @@ uninstall:
 	@echo removing support files from ${DESTDIR}${SHAREPREFIX}/vis
 	@rm -rf ${DESTDIR}${SHAREPREFIX}/vis
 
-.PHONY: all clean dist install uninstall debug profile coverage test test-update
+.PHONY: all clean dist install uninstall debug profile coverage test test-update luadoc luadoc-all
diff --git a/luadoc/README.md b/luadoc/README.md
new file mode 100644
index 0000000..17531da
--- /dev/null
+++ b/luadoc/README.md
@@ -0,0 +1,37 @@
+This is the destination directory for the LDoc documentation of Vis' Lua API
+as generated by the `make luadoc`.
+
+Unfortunately `ldoc(1)` seems to have a bug which generates broken reference
+links for custom types. The following patch seems to fix the issue:
+
+```
+From 96a1fbc8e972fedf665049a6351f46bc1aac1768 Mon Sep 17 00:00:00 2001
+From: =?UTF-8?q?Marc=20Andr=C3=A9=20Tanner?= <mat@brain-dump.org>
+Date: Tue, 6 Dec 2016 15:59:17 +0100
+Subject: [PATCH] Fix references to class types.
+
+For classes the generated HTML anchors need to be prefixed 'Class_'.
+---
+ ldoc/doc.lua | 6 +++---
+ 1 file changed, 3 insertions(+), 3 deletions(-)
+
+diff --git a/ldoc/doc.lua b/ldoc/doc.lua
+index e19b2df..f368b90 100644
+--- a/ldoc/doc.lua
++++ b/ldoc/doc.lua
+@@ -1073,9 +1073,9 @@ end
+ local function reference (s, mod_ref, item_ref)
+    local name = item_ref and item_ref.name or ''
+    -- this is deeply hacky; classes have 'Class ' prepended.
+---~    if item_ref and doc.class_tag(item_ref.type) then
+---~       name = 'Class_'..name
+---~    end
++       if item_ref and doc.class_tag(item_ref.type) then
++          name = 'Class_'..name
++       end
+    return {mod = mod_ref, name = name, label=s}
+ end
+ 
+-- 
+1.9.1
+```
diff --git a/luadoc/config.ld b/luadoc/config.ld
new file mode 100644
index 0000000..8567a89
--- /dev/null
+++ b/luadoc/config.ld
@@ -0,0 +1,14 @@
+-- Configuration file for Luadoc API generation
+project="Vis Editor"
+title="Vis Editor Lua API documentation"
+format="markdown"
+style="!fixed"
+dir="."
+sort=true
+merge=true
+no_space_before_args=true
+file={
+	"../vis-lua.c",
+	"../vis.lua",
+}
+	
\ No newline at end of file
diff --git a/vis-lua.c b/vis-lua.c
index 54551f4..b88a1d1 100644
--- a/vis-lua.c
+++ b/vis-lua.c
@@ -1,5 +1,8 @@
 /***
- * Lua API for [Vis Editor](https://github.com/martanne/vis).
+ * Lua Extension API for the [Vis Editor](https://github.com/martanne/vis).
+ *
+ * *WARNING:* there is no stability guarantee at this time, the API might
+ * change without notice!
  *
  * @module vis
  * @author Marc André Tanner
@@ -499,7 +502,10 @@ static const char *keymapping(Vis *vis, const char *keys, const Arg *arg) {
  * @tfield string VERSION
  * version information in `git describe` format, same as reported by `vis -v`.
  */
-// FIXME: resulting Lua documentation of these constants is suboptimal
+/***
+ * User interface.
+ * @tfield Ui ui the user interface being used
+ */
 /***
  * Normal mode.
  * @tfield int MODE_NORMAL
@@ -526,14 +532,8 @@ static const char *keymapping(Vis *vis, const char *keys, const Arg *arg) {
  */
 
 /***
- * Current mode.
- * @tfield int mode
- */
-
-/***
  * LPeg lexer support module.
  * @field lexers
- * @ref{TODO|LPeg lexer} support module.
  */
 
 // TODO vis.events
@@ -542,6 +542,11 @@ static const char *keymapping(Vis *vis, const char *keys, const Arg *arg) {
  * Create an iterator over all windows.
  * @function windows
  * @return the new iterator
+ * @see win
+ * @usage
+ * for win in vis:windows() do
+ * 	-- do something with win
+ * end
  */
 static int windows_iter(lua_State *L);
 static int windows(lua_State *L) {
@@ -571,6 +576,10 @@ static int windows_iter(lua_State *L) {
  * Create an iterator over all files.
  * @function files
  * @return the new iterator
+ * @usage
+ * for file in vis:files() do
+ * 	-- do something with file
+ * end
  */
 static int files_iter(lua_State *L);
 static int files(lua_State *L) {
@@ -597,10 +606,12 @@ static int files_iter(lua_State *L) {
 }
 
 /***
- * Execute an editor command.
+ * Execute a `:`-command.
  * @function command
  * @tparam string command the command to execute
  * @treturn bool whether the command succeeded
+ * @usage
+ * vis:command("set number")
  */
 static int command(lua_State *L) {
 	Vis *vis = obj_ref_check(L, 1, "vis");
@@ -656,7 +667,7 @@ static int message(lua_State *L) {
  *
  * Creates a new window and loads the given file.
  *
- * @function message
+ * @function open
  * @tparam string filename the file name to load
  * @treturn File the file object representing the new file, or `nil` on failure
  */
@@ -747,6 +758,7 @@ static int map(lua_State *L) {
  * @function motion
  * @tparam int id the id of the motion to execute
  * @treturn bool whether the id was valid
+ * @local
  */
 static int motion(lua_State *L) {
 	Vis *vis = obj_ref_check(L, 1, "vis");
@@ -773,7 +785,8 @@ static size_t motion_lua(Vis *vis, Win *win, void *data, size_t pos) {
  * @function motion_register
  * @tparam function motion the Lua function implementing the motion
  * @treturn int the associated motion id, or `-1` on failure
- * @see motion
+ * @see motion, motion_new
+ * @local
  * @usage
  * -- custom motion advancing to the next byte
  * local id = vis:motion_register(function(win, pos)
@@ -798,6 +811,8 @@ err:
  * @function textobject
  * @tparam int id the id of the text object to execute
  * @treturn bool whether the id was valid
+ * @see textobject_register, textobject_new
+ * @local
  */
 static int textobject(lua_State *L) {
 	Vis *vis = obj_ref_check(L, 1, "vis");
@@ -822,7 +837,8 @@ static Filerange textobject_lua(Vis *vis, Win *win, void *data, size_t pos) {
  * @function textobject_register
  * @tparam function textobject the Lua function implementing the text object
  * @treturn int the associated text object id, or `-1` on failure
- * @see textobject
+ * @see textobject, textobject_new
+ * @local
  * @usage
  * -- custom text object covering the next byte
  * local id = vis:textobject_register(function(win, pos)
@@ -905,10 +921,17 @@ static int feedkeys(lua_State *L) {
 /***
  * Currently active window.
  * @tfield Window win
+ * @see windows
  */
 /***
  * Currently active mode.
  * @tfield int mode
+ * @see MODE_NORMAL
+ * @see MODE_OPERATOR_PENDING
+ * @see MODE_INSERT
+ * @see MODE_REPLACE
+ * @see MODE_VISUAL
+ * @see MODE_VISUAL_LINE
  */
 /***
  * Whether a macro is being recorded.
@@ -996,7 +1019,7 @@ static const struct luaL_Reg ui_funcs[] = {
 
 /***
  * Viewport currently being displayed.
- * @tfield range viewport
+ * @tfield Range viewport
  */
 /***
  * The window width.
@@ -1139,6 +1162,17 @@ static int window_map(lua_State *L) {
 	return keymap(L, win->vis, win);
 }
 
+/***
+ * Define a display style.
+ * @function style_define
+ * @tparam int id the style id to use
+ * @tparam string style the style definition 
+ * @treturn bool whether the style definition has been successfully
+ *  associated with the given id
+ * @see style
+ * @usage
+ * win:style_define(win.STYLE_DEFAULT, "fore:red")
+ */
 static int window_style_define(lua_State *L) {
 	Win *win = obj_ref_check(L, 1, "vis.window");
 	bool ret = false;
@@ -1151,6 +1185,18 @@ static int window_style_define(lua_State *L) {
 	return 1;
 }
 
+/***
+ * Style a window range.
+ *
+ * The style will be cleared after every window redraw.
+ * @function style
+ * @tparam int id the display style as registered with @{style_define}
+ * @tparam int start the absolute file position in bytes
+ * @tparam int len the length in bytes to style
+ * @see style_define
+ * @usage
+ * win:style(win.STYLE_DEFAULT, 0, 10)
+ */
 static int window_style(lua_State *L) {
 	Win *win = obj_ref_check(L, 1, "vis.window");
 	if (win) {
@@ -1270,7 +1316,7 @@ static const struct luaL_Reg window_cursors_funcs[] = {
  */
 /***
  * The selection associated with this cursor.
- * @tfield range selection the selection or `nil` if not in visual mode
+ * @tfield Range selection the selection or `nil` if not in visual mode
  */
 static int window_cursor_index(lua_State *L) {
 	Cursor *cur = obj_lightref_check(L, 1, "vis.window.cursor");
@@ -1372,7 +1418,16 @@ static const struct luaL_Reg window_cursor_funcs[] = {
  */
 /***
  * File content by logical lines.
+ *
+ * Assigning to array element `0` (`#lines+1`) will insert a new line at
+ * the beginning (end) of the file.
  * @tfield Array(string) lines the file content accessible as 1-based array
+ * @see content
+ * @usage
+ * local lines = vis.win.file.lines
+ * for i=1, #lines do
+ * 	lines[i] = i .. ": " .. lines[i]
+ * end
  */
 /***
  * Type of line endings.
@@ -1496,8 +1551,15 @@ static int file_delete(lua_State *L) {
 
 /***
  * Create an iterator over all lines of the file.
+ *
+ * For large files this is probably faster than @{lines}.
  * @function lines_iterator
  * @return the new iterator
+ * @see lines
+ * @usage
+ * for line in file:lines_iterator() do
+ * 	-- do something with line
+ * end
  */
 static int file_lines_iterator_it(lua_State *L);
 static int file_lines_iterator(lua_State *L) {
@@ -1535,6 +1597,10 @@ static int file_lines_iterator_it(lua_State *L) {
  * @tparam int pos the 0-based file position in bytes
  * @tparam int len the length in bytes to read
  * @treturn string the file content corresponding to the range
+ * @see lines
+ * @usage
+ * local file = vis.win.file
+ * local text = file:content(0, file.size)
  */
 /***
  * Get file content of range.
@@ -1640,6 +1706,42 @@ static const struct luaL_Reg file_lines_funcs[] = {
 	{ NULL, NULL },
 };
 
+/***
+ * The user interface.
+ *
+ * @type Ui
+ */
+/***
+ * Number of available colors.
+ * @tfield int colors
+ */
+
+/***
+ * A file range.
+ *
+ * For a valid range `start <= finish` holds.
+ * An invalid range is represented as `nil`.
+ * @type Range
+ */
+/***
+ * The being of the range.
+ * @tfield int start
+ */
+/***
+ * The end of the range.
+ * @tfield int finish
+ */
+
+/***
+ * Events.
+ *
+ * These events are invoked from the editor core.
+ * The following functions are looked up in the `vis.events` table.
+ * Keep in mind that the editor is blocked while the event handlers
+ * are being executed, avoid long running tasks.
+ * @section Events
+ */
+
 static void vis_lua_event_get(lua_State *L, const char *name) {
 	lua_getglobal(L, "vis");
 	lua_getfield(L, -1, "events");
@@ -1871,16 +1973,33 @@ void vis_lua_init(Vis *vis) {
 	}
 }
 
+/***
+ * Editor startup completed.
+ * This event is emitted immediately before the main loop starts.
+ * At this point all files are loaded and corresponding windows are created.
+ * We are about to process interactive keyboard input.
+ * Can be used to set *global* configuration options.
+ * @function start
+ */
 void vis_lua_start(Vis *vis) {
 	vis_lua_event_call(vis, "start");
 }
 
+/**
+ * Editor is about to terminate.
+ * @function quit
+ */
 void vis_lua_quit(Vis *vis) {
 	vis_lua_event_call(vis, "quit");
 	lua_close(vis->lua);
 	vis->lua = NULL;
 }
 
+/***
+ * File open.
+ * @function file_open
+ * @tparam File file the file to be opened
+ */
 void vis_lua_file_open(Vis *vis, File *file) {
 	debug("event: file-open: %s %p %p\n", file->name ? file->name : "unnamed", (void*)file, (void*)file->text);
 	lua_State *L = vis->lua;
@@ -1892,6 +2011,14 @@ void vis_lua_file_open(Vis *vis, File *file) {
 	lua_pop(L, 1);
 }
 
+/***
+ * File pre save.
+ * Triggered *before* the file is being written.
+ * @function file_save_pre
+ * @tparam File file the file being written
+ * @tparam string path the absolute path to which the file will be written, `nil` if standard output
+ * @treturn bool whether the write operation should be proceeded
+ */
 bool vis_lua_file_save_pre(Vis *vis, File *file, const char *path) {
 	lua_State *L = vis->lua;
 	vis_lua_event_get(L, "file_save_pre");
@@ -1906,6 +2033,13 @@ bool vis_lua_file_save_pre(Vis *vis, File *file, const char *path) {
 	return true;
 }
 
+/***
+ * File post save.
+ * Triggered *after* a successfull write operation.
+ * @function file_save_post
+ * @tparam File file the file which was written
+ * @tparam string path the absolute path to which it was written, `nil` if standard output
+ */
 void vis_lua_file_save_post(Vis *vis, File *file, const char *path) {
 	lua_State *L = vis->lua;
 	vis_lua_event_get(L, "file_save_post");
@@ -1917,6 +2051,12 @@ void vis_lua_file_save_post(Vis *vis, File *file, const char *path) {
 	lua_pop(L, 1);
 }
 
+/***
+ * File close.
+ * The last window displaying the file has been closed.
+ * @function file_close
+ * @tparam File file the file being closed
+ */
 void vis_lua_file_close(Vis *vis, File *file) {
 	debug("event: file-close: %s %p %p\n", file->name ? file->name : "unnamed", (void*)file, (void*)file->text);
 	lua_State *L = vis->lua;
@@ -1930,6 +2070,12 @@ void vis_lua_file_close(Vis *vis, File *file) {
 	lua_pop(L, 1);
 }
 
+/***
+ * Window open.
+ * A new window has been created.
+ * @function win_open
+ * @tparam Window win the window being opened
+ */
 void vis_lua_win_open(Vis *vis, Win *win) {
 	debug("event: win-open: %s %p %p\n", win->file->name ? win->file->name : "unnamed", (void*)win, (void*)win->view);
 	lua_State *L = vis->lua;
@@ -1941,6 +2087,12 @@ void vis_lua_win_open(Vis *vis, Win *win) {
 	lua_pop(L, 1);
 }
 
+/***
+ * Window close.
+ * An window is being closed.
+ * @function win_close
+ * @tparam Window win the window being closed
+ */
 void vis_lua_win_close(Vis *vis, Win *win) {
 	debug("event: win-close: %s %p %p\n", win->file->name ? win->file->name : "unnamed", (void*)win, (void*)win->view);
 	lua_State *L = vis->lua;
@@ -1954,6 +2106,14 @@ void vis_lua_win_close(Vis *vis, Win *win) {
 	lua_pop(L, 1);
 }
 
+/**
+ * Window highlight.
+ * The window has been redrawn and the syntax highlighting needs to be performed.
+ * @function win_highlight
+ * @tparam Window win the window being redrawn
+ * @tparam int horizon the maximal number of bytes the lexer should look behind to synchronize parsing state
+ * @see style
+ */
 void vis_lua_win_highlight(Vis *vis, Win *win, size_t horizon) {
 	lua_State *L = vis->lua;
 	vis_lua_event_get(L, "win_highlight");
@@ -1965,6 +2125,13 @@ void vis_lua_win_highlight(Vis *vis, Win *win, size_t horizon) {
 	lua_pop(L, 1);
 }
 
+/***
+ * Window syntax/filetype change.
+ * @function win_syntax
+ * @tparam Window win the affected window
+ * @tparam string syntax the lexer name or `nil` if syntax highlighting should be disabled for this window
+ * @treturn bool whether the syntax change was successful
+ */
 bool vis_lua_win_syntax(Vis *vis, Win *win, const char *syntax) {
 	lua_State *L = vis->lua;
 	bool ret = false;
@@ -1983,6 +2150,12 @@ bool vis_lua_win_syntax(Vis *vis, Win *win, const char *syntax) {
 	return ret;
 }
 
+/***
+ * Window status bar redraw.
+ * @function win_status
+ * @tparam Window win the affected window
+ * @see status
+ */
 void vis_lua_win_status(Vis *vis, Win *win) {
 	lua_State *L = vis->lua;
 	vis_lua_event_get(L, "win_status");
@@ -1995,6 +2168,11 @@ void vis_lua_win_status(Vis *vis, Win *win) {
 	lua_pop(L, 1);
 }
 
+/***
+ * Theme change.
+ * @function theme_change
+ * @tparam string theme the name of the new theme to load
+ */
 bool vis_theme_load(Vis *vis, const char *name) {
 	lua_State *L = vis->lua;
 	vis_lua_event_get(L, "theme_change");
@@ -2008,20 +2186,4 @@ bool vis_theme_load(Vis *vis, const char *name) {
 	return true;
 }
 
-/***
- * A file range.
- *
- * For a valid range `start <= finish` holds.
- * An invalid range is represented as `nil`.
- * @type Range
- */
-/***
- * The being of the range.
- * @tfield int start
- */
-/***
- * The end of the range.
- * @tfield int finish
- */
-
 #endif
diff --git a/vis.lua b/vis.lua
index bc5b618..7d07b4b 100644
--- a/vis.lua
+++ b/vis.lua
@@ -1,4 +1,9 @@
+---
 -- Vis Lua plugin API standard library
+-- @module vis
+
+---
+-- @type Vis
 
 local ok, msg = pcall(function()
 	vis.lexers = {}
@@ -11,6 +16,20 @@ end
 
 vis.events = {}
 
+--- Map a new motion.
+--
+-- Sets up a mapping in normal, visual and operator pending mode.
+-- The motion function will receive the @{Window} and an initial position
+-- (in bytes from the start of the file) as argument and is expected to
+-- return the resulting position.
+-- @tparam string key the key to associate with the new mption
+-- @tparam function motion the motion logic implemented as Lua function
+-- @treturn bool whether the new motion could be installed
+-- @usage
+-- vis:motion_new("<C-l>", function(win, pos)
+-- 	return pos+1
+-- end)
+--
 vis.motion_new = function(vis, key, motion)
 	local id = vis:motion_register(motion)
 	if id < 0 then
@@ -25,6 +44,20 @@ vis.motion_new = function(vis, key, motion)
 	return true
 end
 
+--- Map a new text object.
+--
+-- Sets up a mapping in visual and operator pending mode.
+-- The text object function will receive the @{Window} and an initial
+-- position(in bytes from the start of the file) as argument and is
+-- expected to return the resulting range or `nil`.
+-- @tparam string key the key associated with the new text object
+-- @tparam function textobject the text object logic implemented as Lua function
+-- @treturn bool whether the new text object could be installed
+-- @usage
+-- vis:textobject_new("<C-l>", function(win, pos)
+-- 	return pos, pos+1
+-- end)
+--
 vis.textobject_new = function(vis, key, textobject)
 	local id = vis:textobject_register(textobject)
 	if id < 0 then