15 files changed, 74 insertions, 72 deletions
diff --git a/core/.iconv.luadoc b/core/.iconv.luadoc
index e8892c20..ee403194 100644
--- a/core/.iconv.luadoc
+++ b/core/.iconv.luadoc
@@ -6,9 +6,9 @@
 module('string')
 
 ---
--- Converts string *text* from character set *from* to character set *to* using
--- iconv.
--- Valid character sets are [GNU iconv's character sets][] and include:
+-- Converts string *text* from encoding *from* to encoding *to* using iconv,
+-- returning the string result.
+-- Valid encodings are [GNU iconv's encodings][] and include:
 --
 --   * European: ASCII, ISO-8859-{1,2,3,4,5,7,9,10,13,14,15,16}, KOI8-R, KOI8-U,
 --     KOI8-RU, CP{1250,1251,1252,1253,1254,1257}, CP{850,866,1131},
@@ -31,8 +31,8 @@ module('string')
 --   * Unicode: UTF-8, UCS-2, UCS-2BE, UCS-2LE, UCS-4, UCS-4BE, UCS-4LE, UTF-16,
 --     UTF-16BE, UTF-16LE, UTF-32, UTF-32BE, UTF-32LE, UTF-7, C99, JAVA.
 --
--- [GNU iconv's character sets]: http://www.gnu.org/software/libiconv/
+-- [GNU iconv's encodings]: http://www.gnu.org/software/libiconv/
 -- @param text The text to convert.
--- @param to The string character set to convert to.
--- @param from The string character set to convert from.
+-- @param to The string encoding to convert to.
+-- @param from The string encoding to convert from.
 function iconv(text, to, from) end
diff --git a/core/.view.luadoc b/core/.view.luadoc
index 949ee997..29509f9b 100644
--- a/core/.view.luadoc
+++ b/core/.view.luadoc
@@ -5,7 +5,8 @@
 ---
 -- A Textadept view object.
 -- @field size (number)
---   The position of the split resizer (if this view is part of a split view).
+--   The pixel position of the split resizer if this view is part of a split
+--   view.
 module('view')
 
 ---
@@ -15,7 +16,7 @@ module('view')
 local buffer
 
 ---
--- Splits the view into top and bottom views, unless *vertical* is `true`,
+-- Splits the view into top and bottom views unless *vertical* is `true`,
 -- focuses the new view, and returns both the old and new views.
 -- If *vertical* is `false`, splits the view vertically into left and
 -- right views.
diff --git a/core/events.lua b/core/events.lua
index 658d011b..b7b9771d 100644
--- a/core/events.lua
+++ b/core/events.lua
@@ -29,7 +29,7 @@ local M = {}
 -- handler handled it.
 --
 -- @field APPLEEVENT_ODOC (string)
---   Emitted when Mac OSX tells Textadept to open a document.
+--   Emitted when Mac OSX tells Textadept to open a file.
 --   Arguments:
 --
 --   * _`uri`_: The UTF-8-encoded URI to open.
@@ -45,8 +45,7 @@ local M = {}
 --   Arguments:
 --
 --   * _`text`_: The text of the selection.
---   * _`position`_: The position in the buffer of the beginning of the
---     autocompleted word.
+--   * _`position`_: The position of the beginning of the autocompleted word.
 -- @field BUFFER_AFTER_SWITCH (string)
 --   Emitted right after switching to another buffer.
 --   Emitted by [`view:goto_buffer()`][].
@@ -86,9 +85,8 @@ local M = {}
 --
 --   * _`position`_: The position in the buffer double-clicked.
 --   * _`line`_: The line number double-clicked.
---   * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are
---     `buffer.SCMOD_ALT`, `buffer.SCMOD_CTRL`, `buffer.SCMOD_SHIFT`, and
---     `buffer.SCMOD_META`.
+--   * _`modifiers`_: A bit-mask of any modifier keys used: `buffer.SCMOD_CTRL`,
+--     `buffer.SCMOD_SHIFT`, `buffer.SCMOD_ALT`, and `buffer.SCMOD_META`.
 --     Note: If you set `buffer.rectangular_selection_modifier` to
 --     `buffer.SCMOD_CTRL`, the "Control" modifier is reported as *both*
 --     "Control" and "Alt" due to a Scintilla limitation with GTK+.
@@ -123,9 +121,8 @@ local M = {}
 --   Arguments:
 --
 --   * _`position`_: The position in the buffer clicked.
---   * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are
---     `buffer.SCMOD_ALT`, `buffer.SCMOD_CTRL`, `buffer.SCMOD_SHIFT`, and
---     `buffer.SCMOD_META`.
+--   * _`modifiers`_: A bit-mask of any modifier keys used: `buffer.SCMOD_CTRL`,
+--     `buffer.SCMOD_SHIFT`, `buffer.SCMOD_ALT`, and `buffer.SCMOD_META`.
 --     Note: If you set `buffer.rectangular_selection_modifier` to
 --     `buffer.SCMOD_CTRL`, the "Control" modifier is reported as *both*
 --     "Control" and "Alt" due to a Scintilla limitation with GTK+.
@@ -135,9 +132,8 @@ local M = {}
 --   Arguments:
 --
 --   * _`position`_: The position in the buffer double-clicked.
---   * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are
---     `buffer.SCMOD_ALT`, `buffer.SCMOD_CTRL`, `buffer.SCMOD_SHIFT`, and
---     `buffer.SCMOD_META`.
+--   * _`modifiers`_: A bit-mask of any modifier keys used: `buffer.SCMOD_CTRL`,
+--     `buffer.SCMOD_SHIFT`, `buffer.SCMOD_ALT`, and `buffer.SCMOD_META`.
 --     Note: If you set `buffer.rectangular_selection_modifier` to
 --     `buffer.SCMOD_CTRL`, the "Control" modifier is reported as *both*
 --     "Control" and "Alt" due to a Scintilla limitation with GTK+.
@@ -148,22 +144,21 @@ local M = {}
 --
 --   * _`position`_: The position in the buffer unclicked.
 -- @field INDICATOR_CLICK (string)
---   Emitted when clicking the mouse on text that has an indicator.
+--   Emitted when clicking the mouse on text that has an indicator present.
 --   Arguments:
 --
---   * _`position`_: The position in the buffer clicked.
---   * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are
---     `buffer.SCMOD_ALT`, `buffer.SCMOD_CTRL`, `buffer.SCMOD_SHIFT`, and
---     `buffer.SCMOD_META`.
+--   * _`position`_: The position of the clicked text in the buffer.
+--   * _`modifiers`_: A bit-mask of any modifier keys used: `buffer.SCMOD_CTRL`,
+--     `buffer.SCMOD_SHIFT`, `buffer.SCMOD_ALT`, and `buffer.SCMOD_META`.
 --     Note: If you set `buffer.rectangular_selection_modifier` to
 --     `buffer.SCMOD_CTRL`, the "Control" modifier is reported as *both*
 --     "Control" and "Alt" due to a Scintilla limitation with GTK+.
 -- @field INDICATOR_RELEASE (string)
---   Emitted after releasing the mouse after clicking on text that had an
---   indicator.
+--   Emitted when releasing the mouse after clicking on text that has an
+--   indicator present.
 --   Arguments:
 --
---   * _`position`_: The position in the buffer unclicked.
+--   * _`position`_: The position of the clicked text in the buffer.
 -- @field INITIALIZED (string)
 --   Emitted after Textadept finishes initializing.
 -- @field KEYPRESS (string)
@@ -182,10 +177,9 @@ local M = {}
 --
 --   * _`margin`_: The margin number clicked.
 --   * _`position`_: The position of the start of the line in the buffer whose
---     margin line was clicked.
---   * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are
---     `buffer.SCMOD_ALT`, `buffer.SCMOD_CTRL`, `buffer.SCMOD_SHIFT`, and
---     `buffer.SCMOD_META`.
+--     margin was clicked.
+--   * _`modifiers`_: A bit-mask of any modifier keys used: `buffer.SCMOD_CTRL`,
+--     `buffer.SCMOD_SHIFT`, `buffer.SCMOD_ALT`, and `buffer.SCMOD_META`.
 --     Note: If you set `buffer.rectangular_selection_modifier` to
 --     `buffer.SCMOD_CTRL`, the "Control" modifier is reported as *both*
 --     "Control" and "Alt" due to a Scintilla limitation with GTK+.
@@ -261,9 +255,10 @@ module('events')]]
 local handlers = {}
 
 ---
--- Adds function *f* to the set of event handlers for *event* at position
--- *index*, returning a handler ID for *f*. *event* is an arbitrary event name
--- that does not need to have been previously defined.
+-- Adds function *f* to the set of event handlers for event *event* at position
+-- *index*, returning the handler identifier for *f*.
+-- *event* may be any arbitrary string and does not need to have been previously
+-- defined.
 -- @param event The string event name.
 -- @param f The Lua function to connect to *event*.
 -- @param index Optional index to insert the handler into.
@@ -280,8 +275,8 @@ function M.connect(event, f, index)
 end
 
 ---
--- Removes handler ID *id*, returned by `events.connect()`, from the set of
--- event handlers for *event*.
+-- Removes handler identifier *id*, returned by `events.connect()`, from the set
+-- of handlers for event *event*.
 -- @param event The string event name.
 -- @param id ID of the handler returned by `events.connect()`.
 -- @see connect
@@ -293,9 +288,9 @@ end
 
 local error_emitted = false
 ---
--- Sequentially calls all handler functions for *event* with the given
+-- Sequentially calls all handler functions for event *event* with the given
 -- arguments.
--- *event* is an arbitrary event name that does not need to have been previously
+-- *event* may be any arbitrary string and does not need to have been previously
 -- defined. If any handler explicitly returns `true` or `false`, the event is
 -- not propagated any further, iteration ceases, and `emit()` returns that
 -- value. This is useful for stopping the propagation of an event like a
diff --git a/core/file_io.lua b/core/file_io.lua
index 2cf7f08b..967332f8 100644
--- a/core/file_io.lua
+++ b/core/file_io.lua
@@ -79,7 +79,7 @@ io.SNAPOPEN_MAX = 1000
 io.recent_files = {}
 
 ---
--- List of byte-order marks (BOMs) for identifying unicode file types.
+-- List of byte-order marks (BOMs) for identifying unicode file encodings.
 -- @class table
 -- @name boms
 io.boms = {
@@ -89,7 +89,7 @@ io.boms = {
 }
 
 ---
--- List of encodings to try to decode files as.
+-- List of encodings to attempt to decode files as.
 -- You should add to this list if you get a "Conversion failed" error when
 -- trying to open a file whose encoding is not recognized. Valid encodings are
 -- [GNU iconv's encodings][] and include:
diff --git a/core/keys.lua b/core/keys.lua
index 338c54e9..ac782df1 100644
--- a/core/keys.lua
+++ b/core/keys.lua
@@ -104,12 +104,12 @@ local M = {}
 --       c = {function3, arg1, arg2}
 --     }
 -- @field CLEAR (string)
---   The string representing the key sequence that clears the current key chain.
+--   The key that clears the current key chain.
 --   It cannot be part of a key chain.
 --   The default value is `'esc'` for the `Esc` (`⎋` on Mac OSX | `Esc` in
 --   curses) key.
 -- @field LANGUAGE_MODULE_PREFIX (string)
---   The starting key of the key chain reserved for language modules.
+--   The prefix key of the key chain reserved for language modules.
 --   The default value is `'cl'` on platforms other than Mac OSX, `'ml'`
 --   otherwise. Equivalent to `Ctrl+L` (`⌘L` on Mac OSX | `M-L` in curses).
 -- @field MODE (string)
diff --git a/core/lfs_ext.lua b/core/lfs_ext.lua
index d79800a4..36dfeffc 100644
--- a/core/lfs_ext.lua
+++ b/core/lfs_ext.lua
@@ -6,7 +6,7 @@
 module('lfs')]]
 
 ---
--- Filter table containing common binary file extensions and version control
+-- The filter table containing common binary file extensions and version control
 -- folders to exclude when iterating over files and directories using
 -- `dir_foreach` when its `exclude_FILTER` argument is `false`.
 -- @see dir_foreach
diff --git a/core/ui.lua b/core/ui.lua
index d347d724..4ef4ea70 100644
--- a/core/ui.lua
+++ b/core/ui.lua
@@ -52,7 +52,7 @@ local function _print(buffer_type, ...)
   buffer:set_save_point()
 end
 ---
--- Helper function for printing messages to buffers.
+-- Helper function for printing messages to the buffer of type *buffer_type*.
 -- Splits the view and opens a new buffer for printing messages to. If the
 -- message buffer is already open in a view, the message is printed to that
 -- view. Otherwise the view is split and the message buffer is opened or
@@ -383,7 +383,7 @@ events_connect(events.ERROR, ui.print)
 local menubar
 
 ---
--- A table containing the width and height values of the Textadept window.
+-- A table containing the width and height pixel values of the Textadept window.
 -- @class table
 -- @name size
 local size
@@ -391,8 +391,8 @@ local size
 The functions below are Lua C functions.
 
 ---
--- Displays a *kind* [gtdialog][] with the given string arguments to pass to
--- the dialog and returns a formatted string of the dialog's output.
+-- Displays a [gtdialog][] of kind *kind* with the given string arguments to
+-- pass to the dialog and returns a formatted string of the dialog's output.
 -- Table arguments containing strings are allowed and expanded in place. This is
 -- useful for filtered list dialogs with many items.
 -- For more information on gtdialog, see [http://foicica.com/gtdialog][].
diff --git a/modules/textadept/bookmarks.lua b/modules/textadept/bookmarks.lua
index 4e2d7b03..525befa9 100644
--- a/modules/textadept/bookmarks.lua
+++ b/modules/textadept/bookmarks.lua
@@ -37,9 +37,10 @@ function M.clear()
 end
 
 ---
--- Prompts the user to select a bookmarked line to go to unless *next* is given.
--- If *next* is `true` or `false`, goes to the next or previous bookmark,
--- respectively.
+-- Prompts the user to select a bookmarked line to move the caret to the
+-- beginning of unless *next* is given.
+-- If *next* is `true` or `false`, moves the caret to the beginning of the next
+-- or previously bookmarked line, respectively.
 -- @param next Optional flag indicating whether to go to the next or previous
 --   bookmarked line relative to the current line. The default value is `nil`,
 --   prompting the user for a bookmarked line to go to.
diff --git a/modules/textadept/command_entry.lua b/modules/textadept/command_entry.lua
index 7d9783bb..e5ec6903 100644
--- a/modules/textadept/command_entry.lua
+++ b/modules/textadept/command_entry.lua
@@ -32,7 +32,7 @@ local M = ui.command_entry
 --
 -- [modes]: keys.html#Modes
 -- @field entry_text (string)
---   The text in the entry.
+--   The text in the command entry.
 module('ui.command_entry')]]
 
 ---
diff --git a/modules/textadept/editing.lua b/modules/textadept/editing.lua
index 36dee287..acd4a5e1 100644
--- a/modules/textadept/editing.lua
+++ b/modules/textadept/editing.lua
@@ -6,8 +6,8 @@ local M = {}
 ---
 -- Editing features for Textadept.
 -- @field AUTOPAIR (bool)
---   Automatically close opening '(', '[', '{', '&quot;', or '&apos;'
---   characters.
+--   Automatically close opening brace and quote characters with their
+--   complements.
 --   The default value is `true`.
 --   Auto-paired characters are defined in the [`char_matches`](#char_matches)
 --   table.
@@ -16,8 +16,8 @@ local M = {}
 --   The default value is `true`.
 --   Matching braces are defined in the [`braces`](#braces) table.
 -- @field TYPEOVER_CHARS (bool)
---   Move over the typeover character under the caret when typing it instead of
---   inserting it.
+--   Move over closing brace and quote characters under the caret when typing
+--   them instead of inserting them.
 --   The default value is `true`.
 --   Typeover characters are defined in the [`typeover_chars`](#typeover_chars)
 --   table.
@@ -43,7 +43,7 @@ M.HIGHLIGHT_COLOR = not CURSES and 'color.orange' or 'color.yellow'
 -- Map of lexer names to line comment strings for programming languages, used by
 -- the `block_comment()` function.
 -- Keys are lexer names and values are either the language's line comment
--- prefixes or block comment delimiters separated by a '|'.
+-- prefixes or block comment delimiters separated by a '|' character.
 -- @class table
 -- @name comment_string
 -- @see block_comment
@@ -261,13 +261,15 @@ function M.autocomplete_word(default_words)
 end
 
 ---
--- Comments or uncomments the selected lines with line comment string *comment*
--- or the comment from the `comment_string` table for the current lexer.
+-- Comments or uncomments the selected lines with line comment or block comment
+-- delimiters string *comment* or the comment from the `comment_string` table
+-- for the current lexer.
+-- Block comment delimiters are separated by a '|' character.
 -- As long as any part of a line is selected, the entire line is eligible for
 -- commenting/uncommenting.
 -- @param comment Optional comment string inserted or removed from each line in
---   the selection. Comment delimiters are separated by a '|'. The default value
---   is the comment in the `comment_string` table for the current lexer.
+--   the selection. The default value is the comment in the `comment_string`
+--   table for the current lexer.
 -- @see comment_string
 -- @name block_comment
 function M.block_comment(comment)
diff --git a/modules/textadept/file_types.lua b/modules/textadept/file_types.lua
index c34ab0e3..e99374a0 100644
--- a/modules/textadept/file_types.lua
+++ b/modules/textadept/file_types.lua
@@ -11,7 +11,7 @@ local M = {}
 --   properties since the module is not loaded when Textadept starts.
 --   Arguments:
 --
---   * *`lang`*: The language lexer name.
+--   * *`lexer`*: The language lexer name.
 module('textadept.file_types')]]
 
 -- Events.
diff --git a/modules/textadept/find.lua b/modules/textadept/find.lua
index f83c626c..43a48223 100644
--- a/modules/textadept/find.lua
+++ b/modules/textadept/find.lua
@@ -78,8 +78,8 @@ events.FIND_WRAPPED = 'find_wrapped'
 local preferred_view
 
 ---
--- Table of Lua patterns matching files and folders to exclude when finding in
--- files.
+-- The table of Lua patterns matching files and folders to exclude when finding
+-- in files.
 -- Each filter string is a pattern that matches filenames to exclude, with
 -- patterns matching folders to exclude listed in a `folders` sub-table.
 -- Patterns starting with '!' exclude files and folders that do not match the
@@ -208,8 +208,8 @@ function M.find_incremental(text, next, anchor)
 end
 
 ---
--- Searches the *utf8_dir* or user-specified directory for files that match
--- search text and options and prints the results to a buffer.
+-- Searches directory *utf8_dir* or user-specified directory for files that
+-- match search text and options and prints the results to a files found buffer.
 -- Use the `find_text`, `match_case`, `whole_word`, and `lua` fields to set the
 -- search text and option flags, respectively. Use `FILTER` to set the search
 -- filter.
diff --git a/modules/textadept/session.lua b/modules/textadept/session.lua
index f31a944e..8ae408fd 100644
--- a/modules/textadept/session.lua
+++ b/modules/textadept/session.lua
@@ -17,7 +17,7 @@ local M = {}
 --   The default value is `true`, but is disabled when passing the command line
 --   switch `-n` or `--nosession` to Textadept.
 -- @field MAX_RECENT_FILES (number)
---   The maximum number of recent files to save to the session.
+--   The maximum number of recent files to save to session files.
 --   Recent files are stored in [`io.recent_files`][].
 --   The default value is `10`.
 --
@@ -29,8 +29,8 @@ M.SAVE_ON_QUIT = true
 M.MAX_RECENT_FILES = 10
 
 ---
--- Loads the Textadept session file *filename* or prompts the user to select
--- one, returning `true` if the session file was opened and read.
+-- Loads Textadept session file *filename* or prompts the user to selectone,
+-- returning `true` if the session file was opened and read.
 -- Textadept restores split views, opened buffers, cursor information, and
 -- recent files.
 -- @param filename Optional absolute path to the session file to load. If `nil`,
diff --git a/modules/textadept/snippets.lua b/modules/textadept/snippets.lua
index 4827c8c8..9b8e8bda 100644
--- a/modules/textadept/snippets.lua
+++ b/modules/textadept/snippets.lua
@@ -67,11 +67,13 @@ local M = {}
 --
 -- ### `\t`
 --
--- A single unit of indentation based on the user's indentation settings.
+-- A single unit of indentation based on the user's indentation settings
+-- (`buffer.use_tabs` and `buffer.tab_width`).
 --
 -- ### `\n`
 --
--- A single set of line ending delimiters based on the user's end of line mode.
+-- A single set of line ending delimiters based on the user's end of line mode
+-- (`buffer.eol_mode`).
 --
 -- [`io.popen()`]: http://www.lua.org/manual/5.2/manual.html#pdf-io.popen
 module('textadept.snippets')]=]
diff --git a/scripts/gen_iface.lua b/scripts/gen_iface.lua
index c2dc0920..56089020 100755
--- a/scripts/gen_iface.lua
+++ b/scripts/gen_iface.lua
@@ -188,7 +188,8 @@ function M.next_indic_number()
 end
 
 ---
--- Returns a unique user list type for use with `buffer.user_list_show()`.
+-- Returns a unique user list identier number for use with
+-- `buffer.user_list_show()`.
 -- Use this function for custom user lists in order to prevent clashes with
 -- list identifiers of other custom user lists.
 -- @usage local list_type = _SCINTILLA.next_user_list_type()