14 files changed, 50 insertions, 51 deletions
diff --git a/core/.buffer.luadoc b/core/.buffer.luadoc
index d36c1dc0..8060a41d 100644
--- a/core/.buffer.luadoc
+++ b/core/.buffer.luadoc
@@ -2821,6 +2821,7 @@ function upper_case(buffer) end
 -- @param items The sorted string of words to show, separated by
 --   `buffer.auto_c_separator` characters (initially spaces).
 -- @see _SCINTILLA.next_user_list_type
+-- @see events.USER_LIST_SELECTION
 function user_list_show(buffer, id, items) end
 
 ---
diff --git a/core/.ui.dialogs.luadoc b/core/.ui.dialogs.luadoc
index fed8b340..0a18e6e1 100644
--- a/core/.ui.dialogs.luadoc
+++ b/core/.ui.dialogs.luadoc
@@ -67,7 +67,7 @@ function msgbox(options) end
 --   * `height`: The dialog's pixel height.
 --   * `float`: Show the dialog on top of all desktop windows. The default value
 --     is `false`.
---   * `timeout`: the integer number of seconds the dialog waits for the user to
+--   * `timeout`: The integer number of seconds the dialog waits for the user to
 --     select a button before timing out. Dialogs do not time out by default.
 -- @return selected button or exit code
 function ok_msgbox(options) end
@@ -98,7 +98,7 @@ function ok_msgbox(options) end
 --   * `height`: The dialog's pixel height.
 --   * `float`: Show the dialog on top of all desktop windows. The default value
 --     is `false`.
---   * `timeout`: the integer number of seconds the dialog waits for the user to
+--   * `timeout`: The integer number of seconds the dialog waits for the user to
 --     select a button before timing out. Dialogs do not time out by default.
 -- @return selected button or exit code
 function yesno_msgbox(options) end
@@ -134,7 +134,7 @@ function yesno_msgbox(options) end
 --   * `height`: The dialog's pixel height.
 --   * `float`: Show the dialog on top of all desktop windows. The default value
 --     is `false`.
---   * `timeout`: the integer number of seconds the dialog waits for the user to
+--   * `timeout`: The integer number of seconds the dialog waits for the user to
 --     select a button before timing out. Dialogs do not time out by default.
 -- @return selected button or exit code, input text
 -- @usage ui.dialogs.inputbox{title = 'Goto Line', informative_text = 'Line:',
@@ -169,7 +169,7 @@ function inputbox(options) end
 --   * `height`: The dialog's pixel height.
 --   * `float`: Show the dialog on top of all desktop windows. The default value
 --     is `false`.
---   * `timeout`: the integer number of seconds the dialog waits for the user to
+--   * `timeout`: The integer number of seconds the dialog waits for the user to
 --     select a button before timing out. Dialogs do not time out by default.
 -- @return selected button or exit code, input text
 function standard_inputbox(options) end
@@ -205,7 +205,7 @@ function standard_inputbox(options) end
 --   * `height`: The dialog's pixel height.
 --   * `float`: Show the dialog on top of all desktop windows. The default value
 --     is `false`.
---   * `timeout`: the integer number of seconds the dialog waits for the user to
+--   * `timeout`: The integer number of seconds the dialog waits for the user to
 --     select a button before timing out. Dialogs do not time out by default.
 -- @return selected button or exit code, input text
 function secure_inputbox(options) end
@@ -238,7 +238,7 @@ function secure_inputbox(options) end
 --   * `height`: The dialog's pixel height.
 --   * `float`: Show the dialog on top of all desktop windows. The default value
 --     is `false`.
---   * `timeout`: the integer number of seconds the dialog waits for the user to
+--   * `timeout`: The integer number of seconds the dialog waits for the user to
 --     select a button before timing out. Dialogs do not time out by default.
 -- @return selected button or exit code, input text
 function secure_standard_inputbox(options) end
@@ -317,7 +317,7 @@ function filesave(options) end
 --   * `height`: The dialog's pixel height.
 --   * `float`: Show the dialog on top of all desktop windows. The default value
 --     is `false`.
---   * `timeout`: the integer number of seconds the dialog waits for the user to
+--   * `timeout`: The integer number of seconds the dialog waits for the user to
 --     select a button before timing out. Dialogs do not time out by default.
 -- @return selected button or exit code, textbox text
 -- @usage ui.dialogs.textbox{title = 'License Agreement',
@@ -356,7 +356,7 @@ function textbox(options) end
 --   * `height`: The dialog's pixel height.
 --   * `float`: Show the dialog on top of all desktop windows. The default value
 --     is `false`.
---   * `timeout`: the integer number of seconds the dialog waits for the user to
+--   * `timeout`: The integer number of seconds the dialog waits for the user to
 --     select a button before timing out. Dialogs do not time out by default.
 -- @return selected button or exit code, selected item
 -- @usage ui.dialogs.dropdown{title = 'Select Encoding', width = 200,
@@ -392,7 +392,7 @@ function dropdown(options) end
 --   * `height`: The dialog's pixel height.
 --   * `float`: Show the dialog on top of all desktop windows. The default value
 --     is `false`.
---   * `timeout`: the integer number of seconds the dialog waits for the user to
+--   * `timeout`: The integer number of seconds the dialog waits for the user to
 --     select a button before timing out. Dialogs do not time out by default.
 -- @return selected button or exit code, selected item
 function standard_dropdown(options) end
@@ -435,7 +435,7 @@ function standard_dropdown(options) end
 --   * `height`: The dialog's pixel height.
 --   * `float`: Show the dialog on top of all desktop windows. The default value
 --     is `false`.
---   * `timeout`: the integer number of seconds the dialog waits for the user to
+--   * `timeout`: The integer number of seconds the dialog waits for the user to
 --     select a button before timing out. Dialogs do not time out by default.
 -- @return selected button or exit code, selected item or list of selected items
 -- @usage ui.dialogs.filteredlist{title = 'Title', columns = {'Foo', 'Bar'},
@@ -469,7 +469,7 @@ function filteredlist(options) end
 --   * `height`: The dialog's pixel height.
 --   * `float`: Show the dialog on top of all desktop windows. The default value
 --     is `false`.
---   * `timeout`: the integer number of seconds the dialog waits for the user to
+--   * `timeout`: The integer number of seconds the dialog waits for the user to
 --     select a button before timing out. Dialogs do not time out by default.
 -- @return selected button or exit code, list of selected options
 -- @usage ui.dialogs.optionselect{title = 'Language',
diff --git a/core/args.lua b/core/args.lua
index 834ba973..cb6454b5 100644
--- a/core/args.lua
+++ b/core/args.lua
@@ -5,9 +5,6 @@ local M = {}
 --[[ This comment is for LuaDoc.
 ---
 -- Processes command line arguments for Textadept.
---
--- ## Arg Events
---
 -- @field _G.events.ARG_NONE (string)
 --   Emitted when no command line arguments are passed to Textadept on startup.
 module('args')]]
diff --git a/core/events.lua b/core/events.lua
index 2173ea4b..0569b09a 100644
--- a/core/events.lua
+++ b/core/events.lua
@@ -6,8 +6,6 @@ local M = {}
 ---
 -- Textadept's core event structure and handlers.
 --
--- ## Overview
---
 -- Textadept emits events when you do things like create a new buffer, press a
 -- key, click on a menu, etc. You can even emit events yourself using Lua. Each
 -- event has a set of event handlers, which are simply Lua functions called in
@@ -119,7 +117,7 @@ local M = {}
 --
 --   * _`text`_: The error message text.
 -- @field FIND (string)
---   Emitted to find text via the Find & Replace Pane.
+--   Emitted in order to find text via the Find & Replace Pane.
 --   Arguments:
 --
 --   * _`text`_: The text to search for.
@@ -170,7 +168,8 @@ local M = {}
 --   Emitted after selecting a menu item.
 --   Arguments:
 --
---   * _`menu_id`_: The numeric ID of the menu item set in [`ui.menu()`]().
+--   * _`menu_id`_: The numeric ID of the menu item, which was defined in
+--     [`ui.menu()`]().
 -- @field MOUSE (string)
 --   Emitted by the terminal version for an unhandled mouse event.
 --   Arguments:
@@ -192,7 +191,7 @@ local M = {}
 --   procedure.
 --   Emitted by [`quit()`]().
 -- @field REPLACE (string)
---   Emitted to replace selected (found) text.
+--   Emitted in order to replace selected (found) text.
 --   Arguments:
 --
 --   * _`text`_: The replacement text.
diff --git a/core/file_io.lua b/core/file_io.lua
index 62966f3a..c4aecfe3 100644
--- a/core/file_io.lua
+++ b/core/file_io.lua
@@ -25,8 +25,8 @@
 --     filename.
 -- @field _G.events.FILE_CHANGED (string)
 --   Emitted when Textadept detects that an open file was modified externally.
---   When connecting to this event, connect with an index of 1 to override the
---   default prompt to reload the file.
+--   When connecting to this event, connect with an index of 1 in order to
+--   override the default prompt to reload the file.
 --   Arguments:
 --
 --   * _`filename`_: The filename externally modified.
diff --git a/core/init.lua b/core/init.lua
index 3b9f35cf..779dfab9 100644
--- a/core/init.lua
+++ b/core/init.lua
@@ -138,7 +138,7 @@ local quit
 -- This function is useful for modifying user scripts (such as
 -- *~/.textadept/init.lua* and *~/.textadept/modules/textadept/keys.lua*) on
 -- the fly without having to restart Textadept. `arg` is set to `nil` when
--- reinitializing the Lua State. Any scripts that need to differentiate between
+-- reinitializing the Lua state. Any scripts that need to differentiate between
 -- startup and reset can test `arg`.
 -- @class function
 -- @name reset
@@ -162,8 +162,8 @@ local timeout
 -- a handle to that process.
 -- At the moment, only the Win32 terminal version spawns processes in the same
 -- thread.
--- @param argv A command line string containing the program's name followed by
---   arguments to pass to it. `PATH` is searched for program names.
+-- @param argv A command line string that contains the program's name followed
+--   by arguments to pass to it. `PATH` is searched for program names.
 -- @param cwd Optional current working directory (cwd) for the child
 --   process. The default value is `nil`, which inherits the parent's cwd.
 -- @param env Optional list of environment variables for the child process.
@@ -206,7 +206,7 @@ function spawn_proc:wait() end
 -- Similar to Lua's `io.read()` and blocks for input. *spawn_proc* must still be
 -- running. If an error occurs while reading, returns `nil`, an error code, and
 -- an error message.
--- Ensure any read operations read all stdout available. The stdout callback
+-- Ensure any read operations read all stdout available, as the stdout callback
 -- function passed to `spawn()` will not be called until the stdout buffer is
 -- clear.
 -- @param arg Optional argument similar to those in Lua's `io.read()`, but "n"
diff --git a/modules/ansi_c/init.lua b/modules/ansi_c/init.lua
index 950479d3..a8f7ef7f 100644
--- a/modules/ansi_c/init.lua
+++ b/modules/ansi_c/init.lua
@@ -6,11 +6,6 @@ local M = {}
 ---
 -- The ansi_c module.
 -- It provides utilities for editing C code.
---
--- ## Key Bindings
---
--- + `Shift+Enter` (`⇧↩` | `S-Enter`)
---   Add ';' to the end of the current line and insert a newline.
 module('_M.ansi_c')]]
 
 -- Autocompletion and documentation.
@@ -90,6 +85,9 @@ textadept.editing.api_files.ansi_c = {
 
 ---
 -- Table of C-specific key bindings.
+--
+-- + `Shift+Enter` (`⇧↩` | `S-Enter`)
+--   Add ';' to the end of the current line and insert a newline.
 -- @class table
 -- @name _G.keys.ansi_c
 keys.ansi_c = {
diff --git a/modules/lua/init.lua b/modules/lua/init.lua
index 1fb007be..b2122d93 100644
--- a/modules/lua/init.lua
+++ b/modules/lua/init.lua
@@ -20,6 +20,7 @@ M.tags = {_HOME..'/modules/lua/tags', _USERHOME..'/modules/lua/tags'}
 
 ---
 -- Map of expression patterns to their types.
+-- Used for type-hinting when showing autocompletions for variables.
 -- Expressions are expected to match after the '=' sign of a statement.
 -- @class table
 -- @name expr_types
diff --git a/modules/textadept/editing.lua b/modules/textadept/editing.lua
index cd8be1ba..dddbf98a 100644
--- a/modules/textadept/editing.lua
+++ b/modules/textadept/editing.lua
@@ -84,8 +84,8 @@ M.auto_pairs = {[40] = ')', [91] = ']', [123] = '}', [39] = "'", [34] = '"'}
 -- values. The default brace characters are '(', ')', '[', ']', '{', and '}'.
 -- @class table
 -- @name brace_matches
--- @usage textadept.editing.brace_matches[60] = 1 -- '<'
--- @usage textadept.editing.brace_matches[62] = 1 -- '>'
+-- @usage textadept.editing.brace_matches[60] = true -- '<'
+-- @usage textadept.editing.brace_matches[62] = true -- '>'
 M.brace_matches = {[40] = 1, [41] = 1, [91] = 1, [93] = 1, [123] = 1, [125] = 1}
 
 ---
@@ -94,7 +94,7 @@ M.brace_matches = {[40] = 1, [41] = 1, [91] = 1, [93] = 1, [123] = 1, [125] = 1}
 -- The default characters are ')', ']', '}', '&apos;', and '&quot;'.
 -- @class table
 -- @name typeover_chars
--- @usage textadept.editing.typeover_chars[62] = 1 -- '>'
+-- @usage textadept.editing.typeover_chars[62] = true -- '>'
 M.typeover_chars = {[41] = 1, [93] = 1, [125] = 1, [39] = 1, [34] = 1}
 
 ---
@@ -113,7 +113,7 @@ M.autocompleters = {}
 ---
 -- Map of lexer names to API documentation file tables.
 -- Each line in an API file consists of a symbol name (not a fully qualified
--- symbol name), a space character, and that symbol's documentation. '\n'
+-- symbol name), a space character, and that symbol's documentation. "\n"
 -- represents a newline character.
 -- @class table
 -- @name api_files
diff --git a/modules/textadept/find.lua b/modules/textadept/find.lua
index 561cae5b..366e4774 100644
--- a/modules/textadept/find.lua
+++ b/modules/textadept/find.lua
@@ -223,8 +223,8 @@ end
 -- *anchor* indicates whether or not to search for *text* starting from the
 -- caret position instead of the position where the incremental search began.
 -- Only the `match_case` find option is recognized. Normal command entry
--- functionality is unavailable until the search is finished by pressing `Esc`
--- (`⎋` on Mac OSX | `Esc` in curses).
+-- functionality is unavailable until the search is finished or by pressing
+-- `Esc` (`⎋` on Mac OSX | `Esc` in curses).
 -- @param text The text to incrementally search for, or `nil` to begin an
 --   incremental search.
 -- @param next Flag indicating whether or not the search direction is forward.
diff --git a/modules/textadept/keys.lua b/modules/textadept/keys.lua
index c95673c4..1a810969 100644
--- a/modules/textadept/keys.lua
+++ b/modules/textadept/keys.lua
@@ -5,7 +5,8 @@ local M = {}
 --[[ This comment is for LuaDoc.
 ---
 -- Defines key commands for Textadept.
--- This set of key commands is pretty standard among other text editors.
+-- This set of key commands is pretty standard among other text editors, at
+-- least for basic editing commands and movements.
 --
 -- ## Key Bindings
 --
diff --git a/modules/textadept/run.lua b/modules/textadept/run.lua
index 7aa9c61a..f663eb0f 100644
--- a/modules/textadept/run.lua
+++ b/modules/textadept/run.lua
@@ -19,8 +19,9 @@ local M = {}
 --   The run or compile error marker number.
 -- @field _G.events.COMPILE_OUTPUT (string)
 --   Emitted when executing a language's compile shell command.
---   By default, compiler output is printed to the message buffer. To override
---   this behavior, connect to the event with an index of `1` and return `true`.
+--   By default, compiler output is printed to the message buffer. In order to
+--   override this behavior, connect to the event with an index of `1` and
+--   return `true`.
 --   Arguments:
 --
 --   * `output`: A line of string output from the command.
@@ -28,8 +29,8 @@ local M = {}
 --     executed compile command.
 -- @field _G.events.RUN_OUTPUT (string)
 --   Emitted when executing a language's run shell command.
---   By default, output is printed to the message buffer. To override this
---   behavior, connect to the event with an index of `1` and return `true`.
+--   By default, output is printed to the message buffer. In order to override
+--   this behavior, connect to the event with an index of `1` and return `true`.
 --   Arguments:
 --
 --   * `output`: A line of string output from the command.
@@ -37,8 +38,8 @@ local M = {}
 --     executed run command.
 -- @field _G.events.BUILD_OUTPUT (string)
 --   Emitted when executing a project's build shell command.
---   By default, output is printed to the message buffer. To override this
---   behavior, connect to the event with an index of `1` and return `true`.
+--   By default, output is printed to the message buffer. In order to override
+--   this behavior, connect to the event with an index of `1` and return `true`.
 --   Arguments:
 --
 --   * `output`: A line of string output from the command.
@@ -316,9 +317,9 @@ end)
 -- patterns that match warning and error messages emitted by compile and run
 -- commands for those file extensions and lexers.
 -- Patterns match single lines and contain captures for a filename, line number,
--- column number (optional), and warning or error message (optional). When a
--- warning or error message is double-clicked, the user is taken to the source
--- of that warning/error.
+-- column number (optional), and warning or error message (optional).
+-- Double-clicking a warning or error message takes the user to the source of
+-- that warning/error.
 -- Note: `(.-)` captures in patterns are interpreted as filenames; `(%d+)`
 -- captures are interpreted as line numbers first, and then column numbers; and
 -- any other capture is treated as warning/error message text.
diff --git a/modules/textadept/session.lua b/modules/textadept/session.lua
index f0dea31c..e497aad0 100644
--- a/modules/textadept/session.lua
+++ b/modules/textadept/session.lua
@@ -27,8 +27,8 @@ M.max_recent_files = 10
 ---
 -- Loads session file *filename* or the user-selected session, returning `true`
 -- if a session file was opened and read.
--- Textadept restores split views, opened buffers, cursor information, and
--- recent files.
+-- Textadept restores split views, opened buffers, cursor information, recent
+-- files, and bookmarks.
 -- @param filename Optional absolute path to the session file to load. If `nil`,
 --   the user is prompted for one.
 -- @return `true` if the session file was opened and read; `false` otherwise.
@@ -110,7 +110,8 @@ end)
 
 ---
 -- Saves the session to file *filename* or the user-selected file.
--- Saves split views, opened buffers, cursor information, and recent files.
+-- Saves split views, opened buffers, cursor information, recent files, and
+-- bookmarks.
 -- @param filename Optional absolute path to the session file to save. If `nil`,
 --   the user is prompted for one.
 -- @usage textadept.session.save(filename)
diff --git a/modules/textadept/snippets.lua b/modules/textadept/snippets.lua
index 2d4bc1de..ebb53505 100644
--- a/modules/textadept/snippets.lua
+++ b/modules/textadept/snippets.lua
@@ -75,7 +75,7 @@ local M = {}
 -- transform with the process' standard output (stdout). The code may use a `%`
 -- character to represent placeholder *n*'s text. An example is
 --
---     snippets['env'] = '$%1(HOME) = %1[echo $%1]'
+--     snippets['env'] = '$%1(HOME) = %1[echo $%]'
 --
 -- ### `%%`
 --
@@ -344,7 +344,7 @@ function M._cancel_current()
 end
 
 ---
--- Prompts the user to select a snippet to be inserted from a list of global and
+-- Prompts the user to select a snippet to insert from a list of global and
 -- language-specific snippets.
 -- @name _select
 function M._select()