More LuaDoc updates.

19 files changed, 426 insertions, 423 deletions

diff --git a/core/.buffer.luadoc b/core/.buffer.luadoc
index 990cc2d3..5ddcf908 100644
--- a/core/.buffer.luadoc
+++ b/core/.buffer.luadoc
@@ -67,43 +67,41 @@
 --
 --   The default value is `buffer.ANNOTATION_HIDDEN`.
 -- @field auto_c_auto_hide (bool)
---   Automatically cancel the autocompletion or user list when no entries match
+--   Automatically cancel an autocompletion or user list when no entries match
 --   typed text.
 --   The default value is `true`.
 -- @field auto_c_cancel_at_start (bool)
---   Cancel an autocompletion or user list when backspacing to a position before
---   where autocompletion started (instead of before the word being completed)
---   or where the user list was shown.
+--   Cancel an autocompletion list when backspacing to a position before where
+--   autocompletion started (instead of before the word being completed).
+--   This option has no effect for a user list.
 --   The default value is `true`.
 -- @field auto_c_case_insensitive_behaviour (number)
 --   The behavior mode for a case insensitive autocompletion or user list when
 --   [`buffer.auto_c_ignore_case`](#auto_c_ignore_case) is `true`.
 --
---   * `buffer.CASEINSENSITIVEBEHAVIOR_RESPECTCASE`
+--   * `buffer.CASEINSENSITIVEBEHAVIOUR_RESPECTCASE`
 --     Prefer to select case-sensitive matches.
---   * `buffer.CASEINSENSITIVEBEHAVIOR_IGNORECASE`
+--   * `buffer.CASEINSENSITIVEBEHAVIOUR_IGNORECASE`
 --     No preference.
 --
---   The default value is `buffer.CASEINSENSITIVEBEHAVIOR_RESPECTCASE`.
+--   The default value is `buffer.CASEINSENSITIVEBEHAVIOUR_RESPECTCASE`.
 -- @field auto_c_choose_single (bool)
---   Automatically choose the item in a single-item autocompletion list. This
---   option has no effect for a user list.
+--   Automatically choose the item in a single-item autocompletion list.
+--   This option has no effect for a user list.
 --   The default value is `false`.
 -- @field auto_c_current (number, Read-only)
---   The index of the currently selected item in the autocompletion or user
---   list.
+--   The index of the currently selected item in an autocompletion or user list.
 -- @field auto_c_current_text (string, Read-only)
---   The text of the currently selected item in the autocompletion or user list.
+--   The text of the currently selected item in an autocompletion or user list.
 -- @field auto_c_drop_rest_of_word (bool)
---   Delete word characters after autocompleted text.
+--   Delete any word characters immediately to the right of autocompleted text.
 --   The default value is `false`.
 -- @field auto_c_fill_ups (string, Write-only)
 --   The set of characters that choose the currently selected item in an
---   autocompletion or user list when typed.
---   The default value is an empty string.
+--   autocompletion or user list when the user types one of them.
+--   The default value is `''`.
 -- @field auto_c_ignore_case (bool)
---   Ignore case when searching an autocompletion or user list for
---   matches.
+--   Ignore case when searching an autocompletion or user list for matches.
 --   The default value is `false`.
 -- @field auto_c_max_height (number)
 --   The maximum number of items per page to show in autocompletion and user
@@ -148,9 +146,9 @@
 --   bitmap to the screen.
 --   The default value is `true`.
 -- @field call_tip_fore_hlt (number, Write-only)
---   The call tip's highlighted text foreground color, in "0xBBGGRR" format.
+--   A call tip's highlighted text foreground color, in "0xBBGGRR" format.
 -- @field call_tip_position (boolean)
---   Display the call tip above the current line instead of below it.
+--   Display a call tip above the current line instead of below it.
 --   The default value is `false`.
 -- @field call_tip_use_style (number)
 --   The pixel width of tab characters in call tips.
@@ -160,14 +158,14 @@
 -- @field caret_fore (number)
 --   The caret's foreground color, in "0xBBGGRR" format.
 -- @field caret_line_back (number)
---   The background color, in "0xBBGGRR" format, of the line containing the
+--   The background color, in "0xBBGGRR" format, of the line that contains the
 --   caret.
 -- @field caret_line_back_alpha (number)
 --   The caret line's background alpha value, ranging from `0` (transparent) to
 --   `255` (opaque).
 --   The default value is `buffer.ALPHA_NOALPHA`, for no alpha.
 -- @field caret_line_visible (bool)
---   Color the background of the line containing the caret a different color.
+--   Color the background of the line that contains the caret a different color.
 --   The default value is `false`.
 -- @field caret_line_visible_always (bool)
 --   Always show the caret line, even when the window is not in focus.
@@ -207,8 +205,9 @@
 -- @field char_at (table, Read-only)
 --   Table of character bytes at positions starting from zero.
 -- @field column (table, Read-only)
---   Table of column numbers, taking tab widths into account, for positions
+--   Table of column numbers (taking tab widths into account) for positions
 --   starting from zero.
+--   Multi-byte characters count as single characters.
 -- @field current_pos (number)
 --   The caret's position.
 --   When set, does not scroll the caret into view.
@@ -227,7 +226,7 @@
 --   The default value is `buffer.CURSORNORMAL`.
 -- @field edge_colour (number)
 --   The color, in "0xBBGGRR" format, of the edge or background for long lines
---   based on `buffer.edge_mode`.
+--   according to `buffer.edge_mode`.
 -- @field edge_column (number)
 --   The column number to mark long lines at.
 -- @field edge_mode (number)
@@ -245,7 +244,7 @@
 -- @field encoding (string or nil)
 --   The string encoding of the file, or `nil` for binary files.
 -- @field encoding_bom (string)
---   The byte-order mark, if any, of the file.
+--   The byte-order mark (if any) of the file.
 -- @field end_at_last_line (bool)
 --   Disable scrolling past the last line.
 --   The default value is `true`.
@@ -254,7 +253,7 @@
 --   position.
 -- @field eol_mode (number)
 --   The current end of line mode. Changing the current mode does not convert
---   existing end of line characters.
+--   any of the buffer's existing end of line characters.
 --   Use [`buffer:convert_eols()`](#convert_eols) to do so.
 --
 --   * `buffer.EOL_CRLF`
@@ -277,8 +276,8 @@
 -- @field first_visible_line (number)
 --   The line number of the line at the top of the view, starting from zero.
 -- @field fold_expanded (table)
---   Table of flags indicating whether or not fold points are expanded for line
---   numbers starting from zero.
+--   Table of flags that indicate whether or not fold points are expanded for
+--   line numbers starting from zero.
 --   Setting expanded fold states does not toggle folds; it only updates fold
 --   margin markers. Use [`buffer:toggle_fold()`](#toggle_fold) instead.
 -- @field fold_flags (number)
@@ -335,11 +334,11 @@
 --     Draw guides only within indentation whitespace.
 --   * `buffer.IV_LOOKFORWARD`
 --     Draw guides beyond the current line up to the next non-empty line's
---     level, but with an additional level if the previous non-empty line is a
---     fold point.
+--     indentation level, but with an additional level if the previous non-empty
+--     line is a fold point.
 --   * `buffer.IV_LOOKBOTH`
---     Draw guides beyond the current line up to either the level of the
---     previous or next non-empty line, whichever is greater.
+--     Draw guides beyond the current line up to either the indentation level of
+--     the previous or next non-empty line, whichever is greater.
 --
 --   The default value is `buffer.IV_NONE`.
 -- @field indic_alpha (table)
@@ -403,7 +402,7 @@
 --
 --   [`_SCINTILLA.next_indic_number()`]: _SCINTILLA.html#next_indic_number
 -- @field indic_under (table)
---   Table of flags indicating whether or not to draw indicators behind text
+--   Table of flags that indicate whether or not to draw indicators behind text
 --   instead of over the top of it for indicator numbers from `0` to `31`.
 --   For values to be `true`, [`buffer.two_phase_draw`](#two_phase_draw) must be
 --   `true`.
@@ -430,8 +429,8 @@
 --   Line states are unaffected by changes in styling and are available in
 --   addition to the 8 bits of styling information per character.
 -- @field line_visible (table, Read-only)
---   Table of flags indicating whether or not lines are visible for line numbers
---   starting from zero.
+--   Table of flags that indicate whether or not lines are visible for line
+--   numbers starting from zero.
 -- @field lines_on_screen (number, Read-only)
 --   The number of completely visible lines in the view.
 --   It is possible to have a partial line visible at the bottom of the view.
@@ -463,15 +462,15 @@
 --   * `buffer.MARGINOPTION_NONE`
 --     None.
 --   * `buffer.MARGINOPTION_SUBLINESELECT`
---     Select only the wrapped line's sub-line, rather than the entire line, on
---     margin click.
+--     Select only a wrapped line's sub-line (rather than the entire line) when
+--     the line number margin is clicked.
 --
 --   The default value is `buffer.MARGINOPTION_NONE`.
 -- @field margin_right (number)
 --   The pixel size of the right margin of the buffer text.
 --   The default value is `1`.
 -- @field margin_sensitive_n (table)
---   Table of flags indicating whether or not mouse clicks in margins emit
+--   Table of flags that indicate whether or not mouse clicks in margins emit
 --   `MARGIN_CLICK` events for margin numbers from zero to four.
 --   The default values are `false`.
 -- @field margin_style (table)
@@ -516,7 +515,7 @@
 --   Table of pixel margin widths for margin numbers from zero to four.
 -- @field marker_alpha (table, Write-only)
 --   Table of alpha values, ranging from `0` (transparent) to `255` (opaque),
---   of markers drawn in the text area, not the margin, for markers numbers from
+--   of markers drawn in the text area (not the margin) for markers numbers from
 --   `0` to `31`.
 --   The default values are `buffer.ALPHA_NOALPHA`, for no alpha.
 -- @field marker_back (table, Write-only)
@@ -562,7 +561,7 @@
 -- @field punctuation_chars (string)
 --   The string set of characters recognized as punctuation characters.
 --   Set this only after setting [`buffer.word_chars`](#word_chars).
---   The default value is a string containing all non-word and non-whitespace
+--   The default value is a string that contains all non-word and non-whitespace
 --   characters.
 -- @field read_only (bool)
 --   Whether or not the buffer is read-only.
@@ -619,14 +618,14 @@
 --   [`buffer:search_in_target()`](#search_in_target).
 --
 --   * `buffer.FIND_WHOLEWORD`
---     Match the search text surrounded by non-word characters.
+--     Match search text only when it is surrounded by non-word characters.
 --   * `buffer.FIND_MATCHCASE`
---     Match the search text case sensitively.
+--     Match search text case sensitively.
 --   * `buffer.FIND_WORDSTART`
---     Match the search text only when the previous character is a non-word
+--     Match search text only when the previous character is a non-word
 --     character.
 --   * `buffer.FIND_REGEXP`
---     Interpret the search text as a regular expression.
+--     Interpret search text as a regular expression.
 --
 --   The default value is `0`.
 --
@@ -689,7 +688,7 @@
 --     selected.
 --
 --   When set, caret movement alters the selected text until this field is set
---   again to the same value or [`buffer:cancel()`](#cancel) is called.
+--   again to the same value or until [`buffer:cancel()`](#cancel) is called.
 -- @field selection_n_anchor (table)
 --   Table of positions at the beginning of existing selections numbered from
 --   zero, the main selection.
@@ -719,7 +718,7 @@
 --   Table of background colors, in "0xBBGGRR" format, of text for style numbers
 --   from `0` to `255`.
 -- @field style_bold (table)
---   Table of flags indicating whether or not text is bold for style numbers
+--   Table of flags that indicate whether or not text is bold for style numbers
 --   from `0` to `255`.
 --   The default values are `false`.
 -- @field style_case (table)
@@ -734,13 +733,13 @@
 --
 --   The default values are `buffer.CASE_MIXED`.
 -- @field style_changeable (table)
---   Table of flags indicating whether or not text is changeable for style
+--   Table of flags that indicate whether or not text is changeable for style
 --   numbers from `0` to `255`.
 --   The default values are `true`.
 --   Currently, read-only styles do not allow the caret into the range of text,
---   but ranges containing read-only text are deletable.
+--   but ranges that contain read-only text are deletable.
 -- @field style_eol_filled (table)
---   Table of flags indicating whether or not the background colors of styles
+--   Table of flags that indicate whether or not the background colors of styles
 --   whose characters occur last on lines extend all the way to the view's right
 --   margin for style numbers from `0` to `255`.
 --   The default values are `false`.
@@ -750,24 +749,24 @@
 --   Table of foreground colors, in "0xBBGGRR" format, of text for style numbers
 --   from `0` to `255`.
 -- @field style_hot_spot (table)
---   Table of flags indicating whether or not text is clickable for style
+--   Table of flags that indicate whether or not text is clickable for style
 --   numbers from `0` to `255`.
 --   The default values are `false`.
 -- @field style_italic (table)
---   Table of flags indicating whether or not text is italic for style numbers
---   from `0` to `255`.
+--   Table of flags that indicate whether or not text is italic for style
+--   numbers from `0` to `255`.
 --   The default values are `false`.
 -- @field style_name (table, Read-only)
 --   Table of style names for style numbers from `0` to `255`.
 -- @field style_size (table)
 --   Table of font sizes of text for style numbers from `0` to `255`.
 -- @field style_underline (table)
---   Table of flags indicating whether or not text is underlined for style
+--   Table of flags that indicate whether or not text is underlined for style
 --   numbers from `0` to `255`.
 --   The default values are `false`.
 -- @field style_visible (table)
---   Table of flags indicating whether or not text is visible for style numbers
---   from `0` to `255`.
+--   Table of flags that indicate whether or not text is visible for style
+--   numbers from `0` to `255`.
 --   The default values are `true`.
 -- @field tab_indents (bool)
 --   Indent text when tabbing within indentation.
@@ -795,12 +794,12 @@
 -- @field undo_collection (bool)
 --   Collect undo information.
 --   When setting to `false`, call
---   [`buffer:empty_undo_buffer()`](#empty_undo_buffer) to avoid desynchronizing
---   the undo buffer with the buffer text.
+--   [`buffer:empty_undo_buffer()`](#empty_undo_buffer) to synchronize the undo
+--   buffer with the buffer text.
 --   The default value is `true`.
 -- @field use_tabs (bool)
 --   Use tabs instead of spaces in indentation. Changing the current setting
---   does not convert existing indentation. Use
+--   does not convert any of the buffer's existing indentation. Use
 --   [`textadept.editing.convert_indentation()`][] to do so.
 --   The default value is `true`.
 -- @field v_scroll_bar (bool)
@@ -836,15 +835,15 @@
 -- @field whitespace_chars (string)
 --   The string set of characters recognized as whitespace characters.
 --   Set this only after setting [`buffer.word_chars`](#word_chars).
---   The default value is a string containing all non-newline characters less
+--   The default value is a string that contains all non-newline characters less
 --   than ASCII value 33.
 -- @field whitespace_size (number)
---   The pixel size of the dots representing space characters when whitespace is
---   visible.
+--   The pixel size of the dots that represent space characters when whitespace
+--   is visible.
 --   The default value is `1`.
 -- @field word_chars (string)
 --   The string set of characters recognized as word characters.
---   The default value is a string containing alphanumeric characters, an
+--   The default value is a string that contains alphanumeric characters, an
 --   underscore, and all characters greater than ASCII value 127.
 -- @field wrap_indent_mode (number)
 --   The wrapped line indent mode.
@@ -874,27 +873,27 @@
 --   `buffer.WRAP_INDENT_FIXED`.
 --   The default value is `0`.
 -- @field wrap_visual_flags (number)
---   The wrapped line visual display mode.
+--   The wrapped line visual flag display mode.
 --
 --   * `buffer.WRAPVISUALFLAG_NONE`
 --     No visual flags.
 --   * `buffer.WRAPVISUALFLAG_END`
---     Show visual flag at the end of the line.
+--     Show a visual flag at the end of a wrapped line.
 --   * `buffer.WRAPVISUALFLAG_START`
---     Show visual flag at the beginning of the sub-line.
+--     Show a visual flag at the beginning of a sub-line.
 --   * `buffer.WRAPVISUALFLAG_MARGIN`
---     Show visual flag in the sub-line's line number margin.
+--     Show a visual flag in the sub-line's line number margin.
 --
 --   The default value is `buffer.WRAPVISUALFLAG_NONE`.
 -- @field wrap_visual_flags_location (number)
 --   The wrapped line visual flag drawing mode.
 --
 --   * `buffer.WRAPVISUALFLAGLOC_DEFAULT`
---     Draw the visual flag near the view's right margin.
+--     Draw a visual flag near the view's right margin.
 --   * `buffer.WRAPVISUALFLAGLOC_END_BY_TEXT`
---     Draw the visual flag near text at the end of the line.
+--     Draw a visual flag near text at the end of a wrapped line.
 --   * `buffer.WRAPVISUALFLAGLOC_START_BY_TEXT`
---     Draw the visual flag near text at the beginning of the subline.
+--     Draw a visual flag near text at the beginning of a subline.
 --
 --   The default value is `buffer.WRAPVISUALFLAGLOC_DEFAULT`.
 -- @field x_offset (number)
@@ -957,47 +956,47 @@ function append_text(buffer, text) end
 function auto_c_active(buffer) end
 
 ---
--- Cancels the autocompletion or user list.
+-- Cancels an autocompletion or user list.
 -- @param buffer The buffer.
 function auto_c_cancel(buffer) end
 
 ---
--- Autocompletes the selected word in the autocompletion list.
+-- Completes the current word with the one selected in an autocompletion list.
 -- @param buffer The buffer.
 function auto_c_complete(buffer) end
 
 ---
--- Returns the position where autocompletion started or where the user list was
+-- Returns the position where autocompletion started or where a user list was
 -- shown.
 -- @param buffer The buffer.
 -- @return number
 function auto_c_pos_start(buffer) end
 
 ---
--- Selects the first item in the autocompletion or user list that starts with
--- string *prefix*, using case sensitivity setting `buffer.auto_c_ignore_case`.
+-- Selects the first item that starts with string *prefix* in an autocompletion
+-- or user list, using the case sensitivity setting `buffer.auto_c_ignore_case`.
 -- @param buffer The buffer.
 -- @param prefix The item in the list to select.
 function auto_c_select(buffer, prefix) end
 
 ---
--- Displays an autocompletion list constructed from string *item_list*, whose
--- items are delimited by `buffer.auto_c_separator` characters, using
--- *len_entered* number of characters behind the caret as the prefix of the word
--- to autocomplete.
--- `buffer.auto_c_order`, the sorted order of *item_list*, must have already
--- been defined.
+-- Displays an autocompletion list constructed from string *items* (whose items
+-- are delimited by `buffer.auto_c_separator` characters) using *len_entered*
+-- number of characters behind the caret as the prefix of the word to be
+-- autocompleted.
+-- The sorted order of *items* (`buffer.auto_c_order`) must have already been
+-- defined.
 -- @param buffer The buffer.
 -- @param len_entered The number of characters before the caret used to provide
 --   the context.
--- @param item_list The sorted string of words to show, separated by
+-- @param items The sorted string of words to show, separated by
 --   `buffer.auto_c_separator` characters (initially spaces).
-function auto_c_show(buffer, len_entered, item_list) end
+function auto_c_show(buffer, len_entered, items) end
 
 ---
--- Defines string *chars* as the set of characters that cancels an
--- autocompletion or user list when typed.
--- The default set is an empty string.
+-- Allows the user to type any character in string set *chars* in order to
+-- cancel an autocompletion or user list.
+-- The default set is empty.
 -- @param buffer The buffer.
 -- @param chars The string of characters that cancel autocompletion. This string
 --   is empty by default.
@@ -1009,7 +1008,7 @@ function auto_c_stops(buffer, chars) end
 function back_tab(buffer) end
 
 ---
--- Starts a sequence of actions to undo or redo as a single action.
+-- Starts a sequence of actions to be undone or redone as a single action.
 -- May be nested.
 -- @param buffer The buffer.
 function begin_undo_action(buffer) end
@@ -1024,13 +1023,13 @@ function begin_undo_action(buffer) end
 function brace_bad_light(buffer, pos) end
 
 ---
--- Highlights unmatched brace characters with indicator number *indic_num*, in
+-- Highlights unmatched brace characters with indicator number *indicator*, in
 -- the range of `0` to `31`, instead of the
 -- `buffer.STYLE_BRACEBAD` style if *use_indicator* is `true`.
 -- @param buffer The buffer.
 -- @param use_indicator Whether or not to use an indicator.
--- @param indic_num The indicator number to use.
-function brace_bad_light_indicator(buffer, use_indicator, indic_num) end
+-- @param indicator The indicator number to use.
+function brace_bad_light_indicator(buffer, use_indicator, indicator) end
 
 ---
 -- Highlights the characters at positions *pos1* and *pos2* as matching braces
@@ -1043,13 +1042,13 @@ function brace_bad_light_indicator(buffer, use_indicator, indic_num) end
 function brace_highlight(buffer, pos1, pos2) end
 
 ---
--- Highlights matching brace characters with indicator number *indic_num*, in
+-- Highlights matching brace characters with indicator number *indicator*, in
 -- the range of `0` to `31`, instead of the
 -- `buffer.STYLE_BRACELIGHT` style if *use_indicator* is `true`.
 -- @param buffer The buffer.
 -- @param use_indicator Whether or not to use an indicator.
--- @param indic_num The indicator number to use.
-function brace_highlight_indicator(buffer, use_indicator, indic_num) end
+-- @param indicator The indicator number to use.
+function brace_highlight_indicator(buffer, use_indicator, indicator) end
 
 ---
 -- Returns the position of the matching brace for the brace character at
@@ -1062,48 +1061,49 @@ function brace_highlight_indicator(buffer, use_indicator, indic_num) end
 function brace_match(buffer, pos) end
 
 ---
--- Returns whether or not the call tip is visible.
+-- Returns whether or not a call tip is visible.
 -- @param buffer The buffer.
 -- @return bool
 function call_tip_active(buffer) end
 
 ---
--- Removes the call tip from view.
+-- Removes a call tip from view.
 -- @param buffer The buffer.
 function call_tip_cancel(buffer) end
 
 ---
--- Returns the call tip's display position.
+-- Returns a call tip's display position.
 -- @param buffer The buffer.
 -- @return number
 function call_tip_pos_start(buffer) end
 
 ---
--- Highlights the call tip text between positions *start_pos*, starting from
+-- Highlights a call tip's text between positions *start_pos*, starting from
 -- zero, to *end_pos* with the color `buffer.call_tip_fore_hlt`.
 -- @param buffer The buffer.
--- @param start_pos The start position in the call tip text to highlight.
--- @param end_pos The end position in the call tip text to highlight.
+-- @param start_pos The start position in a call tip text to highlight.
+-- @param end_pos The end position in a call tip text to highlight.
 function call_tip_set_hlt(buffer, start_pos, end_pos) end
 
 ---
--- Displays a call tip containing string *text* for the word behind position
--- *pos*.
--- Any "\001" or "\002" bytes in *text* are replaced by up or down arrow
--- visuals, respectively, indicating the word has more than one call tip.
+-- Displays a call tip at position *pos* with string *text* as the call tip's
+-- contents.
+-- Any "\001" or "\002" bytes in *text* are replaced by clickable up or down
+-- arrow visuals, respectively. These may be used to indicate that a symbol has
+-- more than one call tip, for example.
 -- @param buffer The buffer.
--- @param pos The position in *buffer* to show the call tip at.
+-- @param pos The position in *buffer* to show a call tip at.
 -- @param text The call tip text to show.
 function call_tip_show(buffer, pos, text) end
 
 ---
--- Returns whether or not there is an action to redo.
+-- Returns whether or not there is an action to be redone.
 -- @param buffer The buffer.
 -- @return bool
 function can_redo(buffer) end
 
 ---
--- Returns whether or not there is an action to undo.
+-- Returns whether or not there is an action to be undone.
 -- @param buffer The buffer.
 -- @return bool
 function can_undo(buffer) end
@@ -1115,16 +1115,6 @@ function can_undo(buffer) end
 function cancel(buffer) end
 
 ---
--- Instructs the lexer to reprocess the range of text between *start_pos* and
--- *end_pos* due to a change in state.
--- @param buffer The buffer.
--- @param start_pos The start position of the range of text in *buffer* to
---   reprocess.
--- @param end_pos The end position of the range of text in *buffer* to
---   reprocess.
-function change_lexer_state(buffer, start_pos, end_pos) end
-
----
 -- Moves the caret left one character.
 -- @param buffer The buffer.
 function char_left(buffer) end
@@ -1192,9 +1182,9 @@ function clear_registered_images(buffer) end
 function clear_selections(buffer) end
 
 ---
--- Instructs the lexer to style and fold the range of text between *start_pos*
--- and *end_pos*.
--- If *end_pos* is `-1`, styles and folds to the end of the buffer.
+-- Instructs the lexer to style and mark fold points in the range of text
+-- between *start_pos* and *end_pos*.
+-- If *end_pos* is `-1`, styles and marks to the end of the buffer.
 -- @param buffer The buffer.
 -- @param start_pos The start position of the range of text in *buffer* to
 --   process.
@@ -1203,15 +1193,15 @@ function clear_selections(buffer) end
 function colourise(buffer, start_pos, end_pos) end
 
 ---
--- Returns the line number of the next contracted fold point starting at line
--- number *line_start*, or `-1`.
+-- Returns the line number of the next contracted fold point starting from line
+-- number *line*, or `-1` if none exists.
 -- @param buffer The buffer.
--- @param line_start The line number in *buffer* to start at.
+-- @param line The line number in *buffer* to start at.
 -- @return number
-function contracted_fold_next(buffer, line_start) end
+function contracted_fold_next(buffer, line) end
 
 ---
--- Converts all end of line characters to the ones in end of line mode *mode*.
+-- Converts all end of line characters to those in end of line mode *mode*.
 -- @param buffer The buffer.
 -- @param mode The end of line mode to convert to. Valid values are:
 --   * `buffer.EOL_CRLF`
@@ -1247,9 +1237,8 @@ function copy_range(buffer, start_pos, end_pos) end
 function copy_text(buffer, text) end
 
 ---
--- Returns the number of whole characters, taking multi-byte characters into
--- account, between positions *start_pos* and
--- *end_pos*.
+-- Returns the number of whole characters (taking multi-byte characters into
+-- account) between positions *start_pos* and *end_pos*.
 -- @param buffer The buffer.
 -- @param start_pos The start position of the range of text in *buffer* to start
 --   counting at.
@@ -1267,12 +1256,13 @@ function count_characters(buffer, start_pos, end_pos) end
 function cut(buffer) end
 
 ---
--- Deletes the range of text from the caret to the beginning of the line.
+-- Deletes the range of text from the caret to the beginning of the current
+-- line.
 -- @param buffer The buffer.
 function del_line_left(buffer) end
 
 ---
--- Deletes the range of text from the caret to the end of the line.
+-- Deletes the range of text from the caret to the end of the current line.
 -- @param buffer The buffer.
 function del_line_right(buffer) end
 
@@ -1298,13 +1288,15 @@ function del_word_right(buffer) end
 function del_word_right_end(buffer) end
 
 ---
--- Deletes the selected text or the character behind the caret.
+-- Deletes the character behind the caret if no text is selected.
+-- Otherwise, deletes the selected text.
 -- @param buffer The buffer.
 function delete_back(buffer) end
 
 ---
--- Deletes the selected text or the character behind the caret unless the caret
--- is at the beginning of a line.
+-- Deletes the character behind the caret unless either the caret is at the
+-- beginning of a line or text is selected.
+-- If text is selected, deletes it.
 -- @param buffer The buffer.
 function delete_back_not_line(buffer) end
 
@@ -1359,7 +1351,7 @@ function edit_toggle_overtype(buffer) end
 function empty_undo_buffer(buffer) end
 
 ---
--- Ends a sequence of actions to undo or redo as a single action.
+-- Ends a sequence of actions to be undone or redone as a single action.
 -- @param buffer The buffer.
 function end_undo_action(buffer) end
 
@@ -1378,8 +1370,8 @@ function ensure_visible(buffer, line) end
 function ensure_visible_enforce_policy(buffer, line) end
 
 ---
--- Returns the position of column number *column* on line number *line*, taking
--- tab and multi-byte characters into account, or the position at the end of
+-- Returns the position of column number *column* on line number *line* (taking
+-- tab and multi-byte characters into account), or the position at the end of
 -- line *line*.
 -- @param buffer The buffer.
 -- @param line The line number in *buffer* to use.
@@ -1387,7 +1379,7 @@ function ensure_visible_enforce_policy(buffer, line) end
 function find_column(buffer, line, column) end
 
 ---
--- Expands, contracts, or toggles all fold points, depending on *action*.
+-- Contracts, expands, or toggles all fold points, depending on *action*.
 -- When toggling, the state of the first fold point determines whether to
 -- expand or contract.
 -- @param buffer The buffer.
@@ -1398,7 +1390,7 @@ function find_column(buffer, line, column) end
 function fold_all(buffer, action) end
 
 ---
--- Expands, contracts, or toggles the fold point on line number *line* as well
+-- Contracts, expands, or toggles the fold point on line number *line*, as well
 -- as all of its children, depending on *action*.
 -- @param buffer The buffer.
 -- @param line The line number in *buffer* to set the fold states for.
@@ -1409,7 +1401,7 @@ function fold_all(buffer, action) end
 function fold_children(buffer, line, action) end
 
 ---
--- Expands, contracts, or toggles the fold point on line number *line*,
+-- Contracts, expands, or toggles the fold point on line number *line*,
 -- depending on *action*.
 -- @param buffer The buffer.
 -- @param line The line number in *buffer* to set the fold state for.
@@ -1425,7 +1417,7 @@ function fold_line(buffer, line, action) end
 function form_feed(buffer) end
 
 ---
--- Returns the current line's text and the caret's position on the line,
+-- Returns the current line's text and the caret's position on that line,
 -- starting from zero.
 -- @param buffer The buffer.
 -- @return string, number
@@ -1444,13 +1436,13 @@ function get_hotspot_active_back(buffer) end
 function get_hotspot_active_fore(buffer) end
 
 ---
--- Returns the line number of the last line after line number *start_line* whose
--- fold level is greater than *level* or, if *level* is `-1`, the level of
--- *start_line*.
+-- Returns the line number of the last line after line number *line* whose fold
+-- level is greater than *level*.
+-- If *level* is `-1`, returns the level of *line*.
 -- @param buffer The buffer.
--- @param start_line The line number in *buffer* of a header line.
--- @param level The fold level, or `-1` for the level of *start_line*.
-function get_last_child(buffer, start_line, level) end
+-- @param line The line number in *buffer* of a header line.
+-- @param level The fold level, or `-1` for the level of *line*.
+function get_last_child(buffer, line, level) end
 
 ---
 -- Returns the text on line number *line*, including end of line characters.
@@ -1461,14 +1453,14 @@ function get_line(buffer, line) end
 
 ---
 -- Returns the position of the end of the selected text on line number *line*,
--- or `-1`.
+-- or `-1` if *line* has no selection.
 -- @param buffer The buffer.
 -- @param line The line number in *buffer* to use.
 function get_line_sel_end_position(buffer, line) end
 
 ---
 -- Returns the position of the beginning of the selected text on line number
--- *line*, or `-1`.
+-- *line*, or `-1` if *line* has no selection.
 -- @param buffer The buffer.
 -- @param line The line number in *buffer* to use.
 function get_line_sel_start_position(buffer, line) end
@@ -1501,7 +1493,7 @@ function goto_line(buffer, line) end
 function goto_pos(buffer, pos) end
 
 ---
--- Hides the range of lines from line number *start_line* to *end_line*.
+-- Hides the range of lines between line numbers *start_line* to *end_line*.
 -- This has no effect on fold levels or fold flags and the first line cannot be
 -- hidden.
 -- @param buffer The buffer.
@@ -1555,7 +1547,7 @@ function home_wrap(buffer) end
 function home_wrap_extend(buffer) end
 
 ---
--- Returns a bit-mask representing which indicators are on at position *pos*.
+-- Returns a bit-mask that represents which indicators are on at position *pos*.
 -- Bit 0 is set if indicator 0 is on, bit 1 for indicator 1, etc.
 -- @param buffer The buffer.
 -- @param pos The position in *buffer* to get indicators at.
@@ -1564,35 +1556,37 @@ function indicator_all_on_for(buffer, pos) end
 
 ---
 -- Clears indicator number `buffer.indicator_current` over the range of text
--- from position *pos* to *pos* + *clear_length*.
+-- from position *pos* to *pos* + *length*.
 -- @param buffer The buffer.
 -- @param pos The start position of the range of text in *buffer* to clear
 --   indicators over.
--- @param clear_length The number of characters in the range of text to clear
+-- @param length The number of characters in the range of text to clear
 --   indicators over.
-function indicator_clear_range(buffer, pos, clear_length) end
+function indicator_clear_range(buffer, pos, length) end
 
 ---
--- Returns the end position of indicator number *indicator*, in the range of `0`
--- to `31`, at position *pos*.
+-- Returns the next boundary position, starting from position *pos*, of
+-- indicator number *indicator*, in the range of `0` to `31`.
+-- Returns `buffer.length` if *indicator* was not found.
 -- @param buffer The buffer.
 -- @param indicator An indicator number in the range of `0` to `31`.
 -- @param pos The position in *buffer* of the indicator.
 function indicator_end(buffer, indicator, pos) end
 
 ---
--- Fills the range of text from position *pos* to *pos* + *fill_length* with
+-- Fills the range of text from position *pos* to *pos* + *length* with
 -- indicator number `buffer.indicator_current`.
 -- @param buffer The buffer.
 -- @param pos The start position of the range of text in *buffer* to set
 --   indicators over.
--- @param fill_length The number of characters in the range of text to set
---   indicators over.
-function indicator_fill_range(buffer, pos, fill_length) end
+-- @param length The number of characters in the range of text to set indicators
+--   over.
+function indicator_fill_range(buffer, pos, length) end
 
 ---
--- Returns the position of the beginning of indicator number *indicator*, in the
--- range of `0` to `31`, at position *pos*.
+-- Returns the previous boundary position, starting from position *pos*, of
+-- indicator number *indicator*, in the range of `0` to `31`.
+-- Returns `0` if *indicator* was not found.
 -- @param buffer The buffer.
 -- @param indicator An indicator number in the range of `0` to `31`.
 -- @param pos The position in *buffer* of the indicator.
@@ -1687,7 +1681,7 @@ function line_end_wrap(buffer) end
 function line_end_wrap_extend(buffer) end
 
 ---
--- Returns the line number of the line containing position *pos*.
+-- Returns the line number of the line that contains position *pos*.
 -- Returns `0` if *pos* is less than 0 or `buffer.line_count` if *pos* is
 -- greater than `buffer.length`.
 -- @param buffer The buffer.
@@ -1745,14 +1739,15 @@ function line_up_extend(buffer) end
 function line_up_rect_extend(buffer) end
 
 ---
--- Joins the lines in the target range, inserting spaces between joined
--- words at line boundaries.
+-- Joins the lines in the target range, inserting spaces between the words
+-- joined at line boundaries.
 -- @param buffer The buffer.
 function lines_join(buffer) end
 
 ---
--- Splits the lines in the target range into lines at most *width* pixels wide
--- or, if *width* is `0`, lines as wide as the view.
+-- Splits the lines in the target range into lines *width* pixels wide.
+-- If *width* is `0`, splits the lines in the target range into lines as wide as
+-- the view.
 -- @param buffer The buffer.
 -- @param width The pixel width to split lines at. When `0`, uses the width of
 --   the view.
@@ -1769,15 +1764,15 @@ function lower_case(buffer) end
 function margin_text_clear_all(buffer) end
 
 ---
--- Adds marker number *marker_num*, in the range of `0` to `31`, to line number
--- *line*, returning a marker handle which can be used in
+-- Adds marker number *marker*, in the range of `0` to `31`, to line number
+-- *line*, returning the added marker's handle which can be used in
 -- `buffer:marker_delete_handle()` and `buffer:marker_line_from_handle()`, or
--- `-1` if the marker cannot be added.
+-- `0` if *line* is invalid.
 -- @param buffer The buffer.
 -- @param line The line number to add the marker on.
--- @param marker_num The marker number in the range of `0` to `31` to add.
+-- @param marker The marker number in the range of `0` to `31` to add.
 -- @return number
-function marker_add(buffer, line, marker_num) end
+function marker_add(buffer, line, marker) end
 
 ---
 -- Adds the markers specified in marker bit-mask *marker_mask* to line number
@@ -1791,42 +1786,41 @@ function marker_add(buffer, line, marker_num) end
 function marker_add_set(buffer, line, marker_mask) end
 
 ---
--- Assigns marker symbol *marker_symbol* to marker number *marker_num*, in the
--- range of `0` to `31`.
--- *marker_symbol* is shown in marker symbol margins next to lines marked with
--- *marker_num*.
+-- Assigns marker symbol *symbol* to marker number *marker*, in the range of `0`
+-- to `31`.
+-- *symbol* is shown in marker symbol margins next to lines marked with
+-- *marker*.
 -- @param buffer The buffer.
--- @param marker_num The marker number in the range of `0` to `31` to set
---   *marker_symbol* for.
--- @param marker_symbol The marker symbol: `buffer.MARK_*`.
+-- @param marker The marker number in the range of `0` to `31` to set *symbol*
+--   for.
+-- @param symbol The marker symbol: `buffer.MARK_*`.
 -- @see _SCINTILLA.next_marker_number
-function marker_define(buffer, marker_num, marker_symbol) end
+function marker_define(buffer, marker, symbol) end
 
 ---
--- Associates marker number *marker_num*, in the range of `0` to `31`, with XPM
+-- Associates marker number *marker*, in the range of `0` to `31`, with XPM
 -- image *pixmap*.
--- The `buffer.MARK_PIXMAP` marker symbol must be assigned to *marker_num*.
--- The image is shown in marker symbol margins next to lines marked with
--- *marker_num*.
+-- The `buffer.MARK_PIXMAP` marker symbol must be assigned to *marker*.
+-- *pixmap* is shown in marker symbol margins next to lines marked with
+-- *marker*.
 -- @param buffer The buffer.
--- @param marker_num The marker number in the range of `0` to `31` to define
+-- @param marker The marker number in the range of `0` to `31` to define
 --   pixmap *pixmap* for.
 -- @param pixmap The string pixmap data.
-function marker_define_pixmap(buffer, marker_num, pixmap) end
+function marker_define_pixmap(buffer, marker, pixmap) end
 
 ---
--- Associates marker number *marker_num*, in the range of `0` to `31`, with RGBA
+-- Associates marker number *marker*, in the range of `0` to `31`, with RGBA
 -- image *pixels*.
--- The dimensions for *pixels*, `buffer.rgba_image_width` and
--- `buffer.rgba_image_height`, must have already been defined. *pixels* is a
+-- The dimensions for *pixels* (`buffer.rgba_image_width` and
+-- `buffer.rgba_image_height`) must have already been defined. *pixels* is a
 -- sequence of 4 byte pixel values (red, blue, green, and alpha) defining the
 -- image line by line starting at the top-left pixel.
--- The `buffer.MARK_RGBAIMAGE` marker symbol must be assigned to *marker_num*.
--- The image is shown in symbol margins next to lines marked with *marker_num*.
--- RGBA image markers use the `buffer.MARK_RGBAIMAGE` marker symbol.
+-- The `buffer.MARK_RGBAIMAGE` marker symbol must be assigned to *marker*.
+-- *pixels* is shown in symbol margins next to lines marked with *marker*.
 -- @param buffer The buffer.
--- @param marker_num The marker number in the range of `0` to `31` to define
---   RGBA data *pixels* for.
+-- @param marker The marker number in the range of `0` to `31` to define RGBA
+--   data *pixels* for.
 -- @param pixels The string sequence of 4 byte pixel values starting with the
 --   pixels for the top line, with the leftmost pixel first, then continuing
 --   with the pixels for subsequent lines. There is no gap between lines for
@@ -1834,25 +1828,25 @@ function marker_define_pixmap(buffer, marker_num, pixmap) end
 --   byte, a blue byte and an alpha byte. The colour bytes are not premultiplied
 --   by the alpha value. That is, a fully red pixel that is 25% opaque will be
 --   `[FF, 00, 00, 3F]`.
-function marker_define_rgba_image(buffer, marker_num, pixels) end
+function marker_define_rgba_image(buffer, marker, pixels) end
 
 ---
--- Deletes marker number *marker_num*, in the range of `0` to `31` or `-1` for
--- all markers, from line number *line*.
+-- Deletes marker number *marker*, in the range of `0` to `31`, from line number
+-- *line*. If *marker* is `-1`, deletes all markers from *line*.
 -- @param buffer The buffer.
 -- @param line The line number to delete the marker on.
--- @param marker_num The marker number in the range of `0` to `31` to delete
---   from *line*, or `-1` to delete all markers from the line.
-function marker_delete(buffer, line, marker_num) end
+-- @param marker The marker number in the range of `0` to `31` to delete from
+--   *line*, or `-1` to delete all markers from the line.
+function marker_delete(buffer, line, marker) end
 
 ---
--- Deletes marker number *marker_num*, in the range of `0` to `31`, from any
--- line that has it.
--- If *marker_num* is `-1`, deletes all markers from all lines.
+-- Deletes marker number *marker*, in the range of `0` to `31`, from any line
+-- that has it.
+-- If *marker* is `-1`, deletes all markers from all lines.
 -- @param buffer The buffer.
--- @param marker_num The marker number in the range of `0` to `31` to delete
---   from all lines, or `-1` to delete all markers from all lines.
-function marker_delete_all(buffer, marker_num) end
+-- @param marker The marker number in the range of `0` to `31` to delete from
+--   all lines, or `-1` to delete all markers from all lines.
+function marker_delete_all(buffer, marker) end
 
 ---
 -- Deletes the marker with handle *handle* returned by `buffer:marker_add()`.
@@ -1868,7 +1862,7 @@ function marker_delete_handle(buffer, handle) end
 function marker_enable_highlight(buffer, enabled) end
 
 ---
--- Returns a bit-mask representing the markers that were added to line number
+-- Returns a bit-mask that represents the markers that were added to line number
 -- *line*.
 -- The first bit is set if marker number 0 is present, the second bit for marker
 -- number 1, and so on.
@@ -1879,45 +1873,45 @@ function marker_get(buffer, line) end
 
 ---
 -- Returns the line number that marker handle *handle*, returned by
--- `buffer:marker_add()`, was added to, or `-1`.
+-- `buffer:marker_add()`, was added to, or `-1` if the line was not found.
 -- @param buffer The buffer.
 -- @param handle The identifier of a marker returned by `buffer:marker_add()`.
 -- @return number
 function marker_line_from_handle(buffer, handle) end
 
 ---
--- Returns the first line number, starting at line number *start_line*, that has
--- had all of the markers represented by marker bit-mask *marker_mask* added to
--- it, or `-1` if no line was found.
+-- Returns the first line number, starting at line number *line*, that has had
+-- all of the markers represented by marker bit-mask *marker_mask* added to it.
+-- Returns `-1` if no line was found.
 -- Bit 0 is set if marker 0 is set, bit 1 for marker 1, etc., up to marker 31.
 -- @param buffer The buffer.
--- @param start_line The start line to search from.
+-- @param line The start line to search from.
 -- @param marker_mask The mask of markers to find. Set bit 0 to find marker 0,
 --   bit 1 for marker 1 and so on.
 -- @return number
-function marker_next(buffer, start_line, marker_mask) end
+function marker_next(buffer, line, marker_mask) end
 
 ---
--- Returns the last line number, before or on line number *start_line*, that has
--- had all of the markers represented by marker bit-mask *marker_mask* added to
--- it, or `-1` if no line was found.
+-- Returns the last line number, before or on line number *line*, that has had
+-- all of the markers represented by marker bit-mask *marker_mask* added to it.
+-- Returns `-1` if no line was found.
 -- Bit 0 is set if marker 0 is set, bit 1 for marker 1, etc., up to marker 31.
 -- @param buffer The buffer.
--- @param start_line The start line to search from.
+-- @param line The start line to search from.
 -- @param marker_mask The mask of markers to find. Set bit 0 to find marker 0,
 --   bit 1 for marker 1 and so on.
 -- @return number
-function marker_previous(buffer, start_line, marker_mask) end
+function marker_previous(buffer, line, marker_mask) end
 
 ---
--- Returns the symbol assigned to marker number *marker_num*, in the range of
--- `0` to `31`, used in `buffer:marker_define()`,
+-- Returns the symbol assigned to marker number *marker*, in the range of `0` to
+-- `31`, used in `buffer:marker_define()`,
 -- `buffer:marker_define_pixmap()`, or `buffer:marker_define_rgba_image()`.
 -- @param buffer The buffer.
--- @param marker_num The marker number in the range of `0` to `31` to get the
---   symbol of.
+-- @param marker The marker number in the range of `0` to `31` to get the symbol
+--   of.
 -- @return number
-function marker_symbol_defined(buffer, marker_num) end
+function marker_symbol_defined(buffer, marker) end
 
 ---
 -- Moves the caret into view if it is not already, removing any selections.
@@ -1935,7 +1929,7 @@ function move_selected_lines_down(buffer) end
 function move_selected_lines_up(buffer) end
 
 ---
--- Types a new line at the caret position based on
+-- Types a new line at the caret position according to
 -- [`buffer.eol_mode`](#eol_mode).
 -- @param buffer The buffer.
 function new_line(buffer) end
@@ -2001,20 +1995,22 @@ function para_up_extend(buffer) end
 
 ---
 -- Pastes the clipboard's contents into the buffer, replacing any selected text
--- depending on `buffer.multi_paste`.
+-- according to `buffer.multi_paste`.
 -- @param buffer The buffer.
 function paste(buffer) end
 
 ---
--- Returns the position of the next character after position *pos*, taking
--- multi-byte characters into account, or `buffer.length`.
+-- Returns the position of the character after position *pos* (taking multi-byte
+-- characters into account), or `buffer.length` if there is no character after
+-- *pos*.
 -- @param buffer The buffer.
 -- @param pos The position in *buffer* to get the position after from.
 function position_after(buffer, pos) end
 
 ---
--- Returns the position of the previous character before position *pos*, taking
--- multi-byte characters into account, or `0`.
+-- Returns the position of the character before position *pos* (taking
+-- multi-byte characters into account), or `0` if there is no character before
+-- *pos*.
 -- @param buffer The buffer.
 -- @param pos The position in *buffer* to get the position before from.
 -- @return number
@@ -2044,8 +2040,8 @@ function register_image(buffer, type, xpm_data) end
 ---
 -- Registers RGBA image *pixels* to type number *type* for use in autocompletion
 -- and user lists.
--- The dimensions for *pixels*, `buffer.rgba_image_width` and
--- `buffer.rgba_image_height`, must have already been defined. *pixels* is a
+-- The dimensions for *pixels* (`buffer.rgba_image_width` and
+-- `buffer.rgba_image_height`) must have already been defined. *pixels* is a
 -- sequence of 4 byte pixel values (red, blue, green, and alpha) defining the
 -- image line by line starting at the top-left pixel.
 -- @param buffer The buffer.
@@ -2087,7 +2083,7 @@ function replace_target(buffer, text) end
 function replace_target_re(buffer, text) end
 
 ---
--- Taps the next additional selection to be the main selection.
+-- Designates the next additional selection to be the main selection.
 -- @param buffer The buffer.
 function rotate_selection(buffer) end
 
@@ -2100,8 +2096,8 @@ function rotate_selection(buffer) end
 function scroll_caret(buffer) end
 
 ---
--- Scrolls the range of text between positions *primary_pos* and *secondary_pos*
--- into view, with priority given to *primary_pos*.
+-- Scrolls into view the range of text between positions *primary_pos* and
+-- *secondary_pos*, with priority given to *primary_pos*.
 -- Similar to `buffer:scroll_caret()`, but with *primary_pos* instead of
 -- `buffer.current_pos`.
 -- This is useful for scrolling search results into view.
@@ -2122,7 +2118,7 @@ function scroll_to_start(buffer) end
 
 ---
 -- Anchors the position that `buffer:search_next()` and `buffer:search_prev()`
--- begin at to the caret position.
+-- start at to the caret position.
 -- @param buffer The buffer.
 function search_anchor(buffer) end
 
@@ -2130,7 +2126,7 @@ function search_anchor(buffer) end
 -- Searches for the first occurrence of string *text* in the target range
 -- bounded by `buffer.target_start` and `buffer.target_end` using search flags
 -- `buffer.search_flags` and, if found, sets the new target range to that
--- occurrence, returning its position or `-1` otherwise.
+-- occurrence, returning its position or `-1` if *text* was not found.
 -- @param buffer The buffer.
 -- @param text The text to search the target range for.
 -- @return number
@@ -2139,8 +2135,8 @@ function search_in_target(buffer, text) end
 
 ---
 -- Searches for and selects the first occurrence of string *text* starting at
--- the search anchor using search flags *flags*, returning the occurrence's
--- position or `-1`.
+-- the search anchor using search flags *flags*, returning that occurrence's
+-- position or `-1` if *text* was not found.
 -- Selected text is not scrolled into view.
 -- @param buffer The buffer.
 -- @param flags The search flags to use. See `buffer.search_flags`.
@@ -2151,8 +2147,8 @@ function search_next(buffer, flags, text) end
 
 ---
 -- Searches for and selects the last occurrence of string *text* before the
--- search anchor using search flags *flags*, returning the occurrence's position
--- or `-1`.
+-- search anchor using search flags *flags*, returning that occurrence's
+-- position or `-1` if *text* was not found.
 -- @param buffer The buffer.
 -- @param flags The search flags to use. See `buffer.search_flags`.
 -- @param text The text to search for.
@@ -2166,8 +2162,8 @@ function search_prev(buffer, flags, text) end
 function select_all(buffer) end
 
 ---
--- Duplicates the selected text to its right or the current line on a new line
--- below.
+-- Duplicates the selected text to its right.
+-- If no text is selected, duplicates the current line on a new line below.
 -- @param buffer The buffer.
 function selection_duplicate(buffer) end
 
@@ -2262,8 +2258,8 @@ function set_sel_fore(buffer, use_setting, color) end
 function set_selection(buffer, end_pos, start_pos) end
 
 ---
--- Assigns the style of the next *length* characters, from the current styling
--- position, to style number *style*, in the range from `0` to `255`, and
+-- Assigns style number *style*, in the range from `0` to `255`, to the next
+-- *length* characters, starting from the current styling position, and
 -- increments the styling position by *length*.
 -- @param buffer The buffer.
 -- @param length The number of characters to style.
@@ -2277,15 +2273,15 @@ function set_styling(buffer, length, style) end
 function set_text(buffer, text) end
 
 ---
--- Sets the visible policy bit-mask *visible_policy* to *visible_slop* number of
--- lines away from the vertical margins when redisplaying hidden or folded lines
--- using `buffer:ensure_visible_enforce_policy()`.
+-- Defines scrolling policy bit-mask *policy* as the policy for keeping the
+-- caret *y* number of lines away from the vertical margins as
+-- `buffer:ensure_visible_enforce_policy()` redisplays hidden or folded lines.
 -- It is similar in operation to `buffer:set_y_caret_policy()`.
 -- @param buffer The buffer.
--- @param visible_policy The combination of `buffer.VISIBLE_SLOP` and
+-- @param policy The combination of `buffer.VISIBLE_SLOP` and
 --   `buffer.VISIBLE_STRICT` policy flags to set.
--- @param visible_slop The slop value to use.
-function set_visible_policy(buffer, visible_policy, visible_slop) end
+-- @param y The number of lines from the vertical margins to keep the caret.
+function set_visible_policy(buffer, policy, y) end
 
 ---
 -- Overrides the background color of whitespace with color *color*, in
@@ -2303,26 +2299,25 @@ function set_whitespace_back(buffer, use_setting, color) end
 function set_whitespace_fore(buffer, use_setting, color) end
 
 ---
--- Set the way the caret is kept visible when going sideways.
--- The exclusion zone is given in pixels.
+-- Defines scrolling policy bit-mask *policy* as the policy for keeping the
+-- caret *x* number of pixels away from the horizontal margins.
 -- @param buffer The buffer.
--- @param caret_policy The combination of `buffer.CARET_SLOP`,
---   `buffer.CARET_STRICT`, `buffer.CARET_EVEN`, and `buffer.CARET_JUMPS` policy
---   flags to set.
--- @param caret_slop The slop value to use.
-function set_x_caret_policy(buffer, caret_policy, caret_slop) end
+-- @param policy The combination of `buffer.CARET_SLOP`, `buffer.CARET_STRICT`,
+--   `buffer.CARET_EVEN`, and `buffer.CARET_JUMPS` policy flags to set.
+-- @param x The number of pixels from the horizontal margins to keep the caret.
+function set_x_caret_policy(buffer, policy, x) end
 
 ---
--- Set the way the line the caret is on is kept visible.
+-- Defines scrolling policy bit-mask *policy* as the policy for keeping the
+-- caret *y* number of lines away from the vertical margins.
 -- @param buffer The buffer.
--- @param caret_policy The combination of `buffer.CARET_SLOP`,
---   `buffer.CARET_STRICT`, `buffer.CARET_EVEN`, and `buffer.CARET_JUMPS` policy
---   flags to set.
--- @param caret_slop The slop value to use.
-function set_y_caret_policy(buffer, caret_policy, caret_slop) end
+-- @param policy The combination of `buffer.CARET_SLOP`, `buffer.CARET_STRICT`,
+--   `buffer.CARET_EVEN`, and `buffer.CARET_JUMPS` policy flags to set.
+-- @param y The number of lines from the vertical margins to keep the caret.
+function set_y_caret_policy(buffer, policy, y) end
 
 ---
--- Shows the range of lines from line number *start_line* to *end_line*.
+-- Shows the range of lines between line numbers *start_line* to *end_line*.
 -- This has no effect on fold levels or fold flags and the first line cannot be
 -- hidden.
 -- @param buffer The buffer.
@@ -2364,7 +2359,7 @@ function stuttered_page_up(buffer) end
 function stuttered_page_up_extend(buffer) end
 
 ---
--- Reverts all styles to have the same properties as `buffer.STYLE_DEFAULT`.
+-- Reverts all styles to having the same properties as `buffer.STYLE_DEFAULT`.
 -- @param buffer The buffer.
 function style_clear_all(buffer) end
 
@@ -2398,8 +2393,8 @@ function target_from_selection(buffer) end
 function text_height(buffer, line) end
 
 ---
--- Returns the pixel width of string *text* styled with style number
--- *style_num*, in the range of `0` to `255`.
+-- Returns the pixel width string *text* would have when styled with style
+-- number *style_num*, in the range of `0` to `255`.
 -- @param buffer The buffer.
 -- @param style_num The style number between `0` and `255` to use.
 -- @param text The text to measure the width of.
@@ -2407,16 +2402,16 @@ function text_height(buffer, line) end
 function text_width(buffer, style_num, text) end
 
 ---
--- Cycles between `buffer.caret_sticky` option settings `buffer.CARETSTICKY_ON`,
--- `buffer.CARETSTICKY_WHITESPACE`, and `buffer.CARETSTICKY_OFF`.
+-- Cycles between `buffer.caret_sticky` option settings `buffer.CARETSTICKY_ON`
+-- and `buffer.CARETSTICKY_OFF`.
 -- @param buffer The buffer.
 -- @see caret_sticky
 function toggle_caret_sticky(buffer) end
 
 ---
--- Toggles the fold point on line number *line* between expanded, where all of
--- its child lines are displayed, and contracted, where all of its child lines
--- are hidden.
+-- Toggles the fold point on line number *line* between expanded (where all of
+-- its child lines are displayed) and contracted (where all of its child lines
+-- are hidden).
 -- @param buffer The buffer.
 -- @param line The line number in *buffer* to toggle the fold on.
 function toggle_fold(buffer, line) end
@@ -2432,18 +2427,18 @@ function undo(buffer) end
 function upper_case(buffer) end
 
 ---
--- Displays a user list identified by list identifier number *list_item* and
--- constructed from string *item_list*, whose items are delimited by
--- `buffer.auto_c_separator` characters.
--- `buffer.auto_c_order`, the sorted order of *item_list*, must have already
--- been defined. When the user selects an item, *list_type* is sent in a
+-- Displays a user list identified by list identifier number *id* and
+-- constructed from string *items* (whose items are delimited by
+-- `buffer.auto_c_separator` characters).
+-- The sorted order of *items* (`buffer.auto_c_order`) must have already been
+-- defined. When the user selects an item, *id* is sent in a
 -- `USER_LIST_SELECTION` event along with the selection.
 -- @param buffer The buffer.
--- @param list_type The list identifier number greater than zero to use.
--- @param item_list The sorted string of words to show, separated by
+-- @param id The list identifier number greater than zero to use.
+-- @param items The sorted string of words to show, separated by
 --   `buffer.auto_c_separator` characters (initially spaces).
 -- @see _SCINTILLA.next_user_list_type
-function user_list_show(buffer, list_type, item_list) end
+function user_list_show(buffer, id, items) end
 
 ---
 -- Moves the caret to the first visible character on the current line or, if
@@ -2659,8 +2654,9 @@ function new() end
 function text_range(buffer, start_pos, end_pos) end
 
 ---
--- Returns the buffer's lexer name, or the name of the lexer under the caret in
--- a multiple-language lexer if *current* is `true`.
+-- Returns the buffer's lexer name.
+-- If *current* is `true`, returns the name of the lexer under the caret in
+-- a multiple-language lexer.
 -- @param buffer The buffer.
 -- @param current Whether or not to get the lexer at the current caret position
 --   in multi-language lexers. The default is `false` and returns the parent
@@ -2669,7 +2665,7 @@ function get_lexer(buffer, current) end
 
 ---
 -- Associates lexer name *lexer* or the auto-detected lexer name with the buffer
--- and then loads the appropriate language module if the module exists.
+-- and then loads the appropriate language module if that module exists.
 -- @param buffer The buffer.
 -- @param lexer Optional string lexer name to set. If `nil`, attempts to
 --   auto-detect the buffer's lexer.
@@ -2731,6 +2727,7 @@ function set_lexer(buffer, lexer) end
 --   * allocate_sub_styles+
 --   * assign_cmd_key
 --   * can_paste
+--   * change_lexer_state
 --   * char_position_from_point
 --   * char_position_from_point_close
 --   * clear_cmd_key
diff --git a/core/.ui.dialogs.luadoc b/core/.ui.dialogs.luadoc
index 68c33c3a..2ff99827 100644
--- a/core/.ui.dialogs.luadoc
+++ b/core/.ui.dialogs.luadoc
@@ -277,7 +277,7 @@ function filesave(options) end
 --     is `false`.
 --   * `focus_textbox`: Focus the textbox instead of the buttons. The default
 --     value is `false`.
---   * `scroll_to`: Where to scroll the textbox text when it is not all visible.
+--   * `scroll_to`: Where to scroll the textbox text.
 --     The available values are `"top"` and `"bottom"`. The default value is
 --     `"top"`.
 --   * `selected`: Select all of the textbox's text. The default value is
diff --git a/core/.view.luadoc b/core/.view.luadoc
index 7dbb0aca..f5db67a8 100644
--- a/core/.view.luadoc
+++ b/core/.view.luadoc
@@ -14,7 +14,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 20cb6cb9..53896cbe 100644
--- a/core/events.lua
+++ b/core/events.lua
@@ -34,13 +34,13 @@ local M = {}
 --
 --   * _`uri`_: The UTF-8-encoded URI to open.
 -- @field AUTO_C_CHAR_DELETED (string)
---   Emitted when deleting a character while the autocompletion or user list is
+--   Emitted after deleting a character while an autocompletion or user list is
 --   active.
 -- @field AUTO_C_CANCELED (string)
---   Emitted when canceling the autocompletion or user list.
+--   Emitted when canceling an autocompletion or user list.
 -- @field AUTO_C_SELECTION (string)
---   Emitted when selecting an item in the autocompletion list and before
---   inserting the selection.
+--   Emitted after selecting an item from an autocompletion list, but before
+--   inserting that item into the buffer.
 --   Automatic insertion can be cancelled by calling
 --   [`buffer:auto_c_cancel()`][] before returning from the event handler.
 --   Arguments:
@@ -85,15 +85,15 @@ local M = {}
 --   Arguments:
 --
 --   * _`position`_: The position double-clicked.
---   * _`line`_: The line number double-clicked.
+--   * _`line`_: The line number of the position double-clicked.
 --   * _`modifiers`_: A bit-mask of any modifier keys used: `buffer.MOD_CTRL`,
 --     `buffer.MOD_SHIFT`, `buffer.MOD_ALT`, and `buffer.MOD_META`.
 --     Note: If you set `buffer.rectangular_selection_modifier` to
 --     `buffer.MOD_CTRL`, the "Control" modifier is reported as *both* "Control"
 --     and "Alt" due to a Scintilla limitation with GTK+.
 -- @field DWELL_END (string)
---   Emitted after a `DWELL_START` when the user moves the mouse, presses a key,
---   etc.
+--   Emitted after `DWELL_START` when the user moves the mouse, presses a key,
+--   or scrolls the view.
 --   Arguments:
 --
 --   * _`position`_: The position closest to *x* and *y*.
@@ -119,8 +119,8 @@ local M = {}
 --   * _`text`_: The text to search for.
 --   * _`next`_: Whether or not to search forward.
 -- @field HOTSPOT_CLICK (string)
---   Emitted when clicking on text that is in a style with the hotspot attribute
---   set.
+--   Emitted when clicking on text that is in a style that has the hotspot
+--   attribute set.
 --   Arguments:
 --
 --   * _`position`_: The clicked text's position.
@@ -130,8 +130,8 @@ local M = {}
 --     `buffer.MOD_CTRL`, the "Control" modifier is reported as *both* "Control"
 --     and "Alt" due to a Scintilla limitation with GTK+.
 -- @field HOTSPOT_DOUBLE_CLICK (string)
---   Emitted when double-clicking on text that is in a style with the hotspot
---   attribute set.
+--   Emitted when double-clicking on text that is in a style that has the
+--   hotspot attribute set.
 --   Arguments:
 --
 --   * _`position`_: The double-clicked text's position.
@@ -142,7 +142,7 @@ local M = {}
 --     and "Alt" due to a Scintilla limitation with GTK+.
 -- @field HOTSPOT_RELEASE_CLICK (string)
 --   Emitted when releasing the mouse after clicking on text that is in a style
---   with the hotspot attribute set.
+--   that has the hotspot attribute set.
 --   Arguments:
 --
 --   * _`position`_: The clicked text's position.
@@ -179,7 +179,7 @@ local M = {}
 --   Arguments:
 --
 --   * _`margin`_: The margin number clicked.
---   * _`position`_: The position of the start of the clicked margin's line.
+--   * _`position`_: The beginning position of the clicked margin's line.
 --   * _`modifiers`_: A bit-mask of any modifier keys used: `buffer.MOD_CTRL`,
 --     `buffer.MOD_SHIFT`, `buffer.MOD_ALT`, and `buffer.MOD_META`.
 --     Note: If you set `buffer.rectangular_selection_modifier` to
@@ -217,18 +217,17 @@ local M = {}
 -- @field SAVE_POINT_REACHED (string)
 --   Emitted after reaching a save point.
 -- @field UPDATE_UI (string)
---   Emitted when buffer content, styling, selection, or scroll position
---   changes.
+--   Emitted after the view is visually updated.
 -- @field URI_DROPPED (string)
 --   Emitted after dragging and dropping a URI into a view.
 --   Arguments:
 --
 --   * _`text`_: The UTF-8-encoded URI dropped.
 -- @field USER_LIST_SELECTION (string)
---   Emitted after selecting an item in the user list.
+--   Emitted after selecting an item in a user list.
 --   Arguments:
 --
---   * _`list_type`_: The *list_type* from [`buffer:user_list_show()`][].
+--   * _`id`_: The *id* from [`buffer:user_list_show()`][].
 --   * _`text`_: The selection's text.
 --   * _`position`_: The position the list was displayed at.
 -- @field VIEW_NEW (string)
@@ -259,8 +258,8 @@ local handlers = {}
 ---
 -- Adds function *f* to the set of event handlers for event *event* at position
 -- *index*.
--- *event* may be any arbitrary string and does not need to have been previously
--- defined.
+-- If *index* not given, appends *f* to the set of handlers. *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.
diff --git a/core/file_io.lua b/core/file_io.lua
index cf877a37..9abc3580 100644
--- a/core/file_io.lua
+++ b/core/file_io.lua
@@ -35,7 +35,7 @@
 --
 --   * _`filename`_: The filename externally modified.
 -- @field SNAPOPEN_MAX (number)
---   The maximum number of files to list in the snapopen dialog.
+--   The maximum number of files listed in the snapopen dialog.
 --   The default value is `1000`.
 module('io')]]
 
@@ -340,7 +340,7 @@ events_connect(events.FILE_OPENED, function(filename)
 end)
 
 ---
--- Prompts the user to select a recently opened file to reopen.
+-- Prompts the user to select a recently opened file to be reopened.
 -- @see recent_files
 -- @name open_recent_file
 function io.open_recent_file()
@@ -356,8 +356,8 @@ function io.open_recent_file()
 end
 
 ---
--- Prompts the user to select files to open from *paths*, a string directory
--- path or list of directory paths, using a filtered list dialog.
+-- Prompts the user to select files to be opened from *paths*, a string
+-- directory path or list of directory paths, using a filtered list dialog.
 -- Files shown in the dialog do not match any pattern in either string or table
 -- *filter* or, unless *exclude_FILTER* is `true`, in `lfs.FILTER`. A filter
 -- table contains Lua patterns that match filenames to exclude, an optional
diff --git a/core/init.lua b/core/init.lua
index b7429940..4d03bb01 100644
--- a/core/init.lua
+++ b/core/init.lua
@@ -21,17 +21,17 @@ if jit then module, package.searchers, bit32 = nil, package.loaders, bit end
 ---
 -- Extends Lua's _G table to provide extra functions and fields for Textadept.
 -- @field _HOME (string)
---   The path to Textadept's home, or installation directory.
+--   The path to Textadept's home, or installation, directory.
 -- @field _RELEASE (string)
 --   The Textadept release version string.
 -- @field _USERHOME (string)
 --   The path to the user's *~/.textadept/* directory, where all preferences and
 --   user-data is stored.
 --   On Windows machines *~/* is the value of the "USERHOME" environment
---   variable, typically *C:\Users\username\\* or
---   *C:\Documents and Settings\username\\*. On Linux, BSD, and Mac OSX
---   machines *~/* is the value of "$HOME", typically */home/username/* and
---   */Users/username/* respectively.
+--   variable (typically *C:\Users\username\\* or
+--   *C:\Documents and Settings\username\\*). On Linux, BSD, and Mac OSX
+--   machines *~/* is the value of "$HOME" (typically */home/username/* and
+--   */Users/username/* respectively).
 -- @field _CHARSET (string)
 --   The filesystem's character encoding.
 --   This is used when [working with files](io.html).
@@ -113,9 +113,9 @@ local quit
 local reset
 
 ---
--- Calls function *f* with the given arguments after number *interval* seconds
--- and then repeatedly while *f* returns `true`. A `nil` or `false` return value
--- stops repetition.
+-- Calls function *f* with the given arguments after *interval* seconds.
+-- If *f* returns `true`, calls *f* repeatedly every *interval* seconds as long
+-- as *f* returns `true`. A `nil` or `false` return value stops repetition.
 -- @param interval The interval in seconds to call *f* after.
 -- @param f The function to call.
 -- @param ... Additional arguments to pass to *f*.
diff --git a/core/locale.conf b/core/locale.conf
index ab7ea05d..76ab5c39 100644
--- a/core/locale.conf
+++ b/core/locale.conf
@@ -35,7 +35,7 @@ File = File
 
 % core/gui.lua
 [Message Buffer] = [Message Buffer]
-_OK = _Ok
+_OK = _OK
 _Cancel = _Cancel
 Name = Name
 %File = File
diff --git a/core/locales/locale.fr.conf b/core/locales/locale.fr.conf
index 167a910b..69149204 100644
--- a/core/locales/locale.fr.conf
+++ b/core/locales/locale.fr.conf
@@ -36,7 +36,7 @@ File = Fichier
 
 % core/gui.lua
 [Message Buffer] = [Buffer des messages]
-_OK = _Ok
+_OK = _OK
 _Cancel = _Annuler
 Name = Nom
 %File = Fichier
diff --git a/core/ui.lua b/core/ui.lua
index 3d98acab..4cbdab4d 100644
--- a/core/ui.lua
+++ b/core/ui.lua
@@ -137,22 +137,23 @@ function ui.switch_buffer()
 end
 
 ---
--- Switches to the buffer whose filename is *filename* in an existing view,
--- otherwise splitting the current view if *split* is `true` or shifting to the
--- next or *preferred_view* view instead of staying in the current one.
--- *sloppy* indicates whether or not to only match the last part of *filename*
--- to a buffer's `filename`.
+-- Switches to the existing view whose buffer's filename is *filename*.
+-- If no view was found and *split* is `true`, splits the current view in order
+-- to show the requested file. If *split* is `false`, shifts to the next or
+-- *preferred_view* view in order to show the requested file. If *sloppy* is
+-- `true`, requires only the last part of *filename* to match a buffer's
+-- `filename`.
 -- @param filename The filename of the buffer to go to.
--- @param split Optional flag indicating whether or not to open the buffer in a
---   split view if there is only one view. The default value is `false`.
+-- @param split Optional flag that indicates whether or not to open the buffer
+--   in a split view if there is only one view. The default value is `false`.
 -- @param preferred_view Optional view to open the desired buffer in if the
 --   buffer is not visible in any other view.
--- @param sloppy Optional flag indicating whether or not to not match *filename*
---   to `buffer.filename` exactly. When `true`, matches *filename* to only the
---   last part of `buffer.filename` This is useful for run and compile commands
---   which output relative filenames and paths instead of full ones and it is
---   likely that the file in question is already open. The default value is
---   `false`.
+-- @param sloppy Optional flag that indicates whether or not to not match
+--   *filename* to `buffer.filename` exactly. When `true`, matches *filename* to
+--   only the last part of `buffer.filename` This is useful for run and compile
+--   commands which output relative filenames and paths instead of full ones and
+--   it is likely that the file in question is already open. The default value
+--   is `false`.
 -- @name goto_file
 function ui.goto_file(filename, split, preferred_view, sloppy)
   local patt = '^'..filename..'$'
@@ -177,7 +178,7 @@ function ui.goto_file(filename, split, preferred_view, sloppy)
 end
 
 ---
--- Switches the editor theme to string *name* and optionally assigns the
+-- Switches the editor theme to string *name* and (optionally) assigns the
 -- properties contained in table *props*.
 -- User themes override Textadept's default themes when they have the same name.
 -- If *name* contains slashes, it is assumed to be an absolute path to a theme
@@ -406,12 +407,12 @@ The functions below are Lua C functions.
 local dialog
 
 ---
--- Returns a split table containing Textadept's current split view structure.
+-- Returns a split table that contains Textadept's current split view structure.
 -- This is primarily used in session saving.
 -- @return table of split views. Each split view entry is a table with 4
 --   fields: `1`, `2`, `vertical`, and `size`. `1` and `2` have values of either
 --   nested split view entries or the views themselves; `vertical` is a flag
---   indicating if the split is vertical or not; and `size` is the integer
+--   that indicates if the split is vertical or not; and `size` is the integer
 --   position of the split resizer.
 -- @class function
 -- @name get_split_table
@@ -423,7 +424,7 @@ local get_split_table
 -- view's index in `_G._VIEWS` instead of an absolute index.
 -- Emits `VIEW_BEFORE_SWITCH` and `VIEW_AFTER_SWITCH` events.
 -- @param n A relative or absolute view index in `_G._VIEWS`.
--- @param relative Optional flag indicating whether *n* is a relative or
+-- @param relative Optional flag that indicates whether *n* is a relative or
 --   absolute index. The default value is `false`, for an absolute index.
 -- @see _G._G._VIEWS
 -- @see events.VIEW_BEFORE_SWITCH
diff --git a/doc/08_Preferences.md b/doc/08_Preferences.md
index f57e02ca..efcd1fb5 100644
--- a/doc/08_Preferences.md
+++ b/doc/08_Preferences.md
@@ -9,9 +9,9 @@ At this point the manual assumes you are at least familiar with the basics of
 
 Textadept executes a *~/.textadept/init.lua*, your user-init file, on startup.
 If this file does not exist, Textadept creates it for you. This file allows you
-to indicate what you want Textadept to do when the application starts, such as
-change the settings of existing modules, load new ones, and/or run plain Lua
-code.
+to indicate what you want Textadept to do when the application starts. Examples
+include changing the settings of existing modules, loading new modules, and
+running arbitrary Lua code.
 
 ### Modules
 
@@ -155,8 +155,8 @@ from *~/.textadept/init.lua*. For example:
 ## Buffer Properties
 
 Since Textadept runs *~/.textadept/init.lua* only once on startup, it is not the
-appropriate place to set per-buffer properties like indentation size or
-view-related properties like the behaviors for scrolling and autocompletion.
+appropriate place to set per-buffer properties (like indentation size) or
+view-related properties (like the behaviors for scrolling and autocompletion).
 If you do set such properties in *~/.textadept/init.lua*, those settings only
 apply to the first buffer and view -- subsequent buffers and split views will
 not inherit those settings. Instead, put your settings in a
diff --git a/doc/14_Appendix.md b/doc/14_Appendix.md
index e128143b..182569cf 100644
--- a/doc/14_Appendix.md
+++ b/doc/14_Appendix.md
@@ -128,9 +128,9 @@ non-existant graphics capabilities:
   (`0xFF0000`), light green (`0x00FF00`), light yellow (`0xFFFF00`), light blue
   (`0x0000FF`), light magenta (`0xFF00FF`), light cyan (`0x00FFFF`), and light
   white (`0xFFFFFF`). Even if your terminal uses a different color map, you must
-  use these color values; unrecognized colors default to white. For some
-  terminals, you may need to set a lexer style's `bold` attribute to use the
-  light color variant.
+  use these color values. Your terminal will remap them automatically.
+  Unrecognized colors default to white. For some terminals, you may need to set
+  a lexer style's `bold` attribute to use the light color variant.
 * No scroll bars.
 * Not all key sequences recognized properly.
 * No style settings like font name, font size, or italics.
diff --git a/modules/textadept/adeptsense.lua b/modules/textadept/adeptsense.lua
index cc7c3c3c..a212381e 100644
--- a/modules/textadept/adeptsense.lua
+++ b/modules/textadept/adeptsense.lua
@@ -395,8 +395,7 @@ M.FUNCTION = 'functions'
 M.FIELD = 'fields'
 
 ---
--- Returns the full symbol or '' and the current symbol part behind the caret or
--- ''.
+-- Returns the full symbol and the current symbol part behind the caret.
 -- For example: `buffer.cur` would return `'buffer'` and `'cur'`.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @return symbol or `''`
@@ -413,11 +412,12 @@ end
 
 ---
 -- Returns the class type of *symbol* name.
--- If *symbol* is `sense.syntax.self` and inside a class definition matching
--- `sense.syntax.class_definition`, that class is returned. Otherwise the
--- buffer is searched backwards for a type declaration of *symbol* according to
--- the patterns in `sense.syntax.type_declarations` or a type assignment of
--- *symbol* according to `sense.syntax.type_assignments`.
+-- If *symbol* is `sense.syntax.self` and occurs inside a class definition that
+-- matches `sense.syntax.class_definition`, that class is returned. Otherwise,
+-- the buffer is searched backwards for either a type declaration of *symbol*
+-- according to the patterns in `sense.syntax.type_declarations`, or for a type
+-- assignment of *symbol* according to `sense.syntax.type_assignments`,
+-- whichever comes first.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @param symbol The symbol name to get the class of.
 -- @return class or `nil`
@@ -509,7 +509,7 @@ local function add_inherited(sense, class, only_fields, only_funcs, c, added)
 end
 
 ---
--- Returns the list of completions for symbol *symbol*.
+-- Returns the list of completions for string *symbol*.
 -- If either *only_fields* or *only_functions* is `true`, returns the
 -- appropriate subset of completions.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
@@ -602,7 +602,8 @@ function M.complete(sense, only_fields, only_functions)
 end
 
 ---
--- Signals character(s) *c* to trigger autocompletion.
+-- Allows the user to autocomplete the symbol behind the caret by typing
+-- character(s) *c*.
 -- If either *only_fields* or *only_functions* is `true`, displays the
 -- appropriate subset of completions.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
@@ -629,8 +630,9 @@ function M.add_trigger(sense, c, only_fields, only_functions)
 end
 
 ---
--- Returns the list of apidocs for symbol *symbol*.
--- The list also holds a `pos` key with the index of the apidoc to show.
+-- Returns the list of API documentation strings for string *symbol*.
+-- A `pos` key in that list holds the index of the documentation string that
+-- should be shown.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @param symbol The symbol name to get apidocs for.
 -- @return list of apidocs or `nil`
@@ -669,7 +671,7 @@ local apidocs = nil
 
 ---
 -- Shows a call tip with API documentation for the symbol behind the caret.
--- If documentation is already being shown, cycles through multiple definitions.
+-- If a call tip is already shown, cycles to the next one if it exists.
 -- @param sense The Adeptsense returned by `adeptsense.new()`. If `nil`, uses
 --   the current language's Adeptsense (if it exists).
 -- @return list of apidocs on success or `nil`.
@@ -718,18 +720,18 @@ end)
 ---
 -- Generates a set of symbol completion lists from Ctags file *tag_file* and
 -- adds the set to the Adeptsense.
--- *nolocations* indicates whether or not to store the location part of tags. If
--- `true`, `sense:goto_ctag()` cannot be used with this set of tags. It is
+-- *no_locations* indicates whether or not to store the location part of tags.
+-- If `true`, `sense:goto_ctag()` cannot be used with this set of tags. It is
 -- recommended to pass `-n` to `ctags` in order to use line numbers instead of
 -- text patterns to locate tags. This will greatly reduce memory usage for a
--- large number of symbols if *nolocations* is `false`.
+-- large number of symbols if *no_locations* is `false`.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @param tag_file The path of the Ctags file to load.
--- @param nolocations Optional flag indicating whether or not to discard the
+-- @param no_locations Optional flag indicating whether or not to discard the
 --   locations of the tags for use by `sense:goto_ctag()`. The default value is
 --   `false`.
 -- @name load_ctags
-function M.load_ctags(sense, tag_file, nolocations)
+function M.load_ctags(sense, tag_file, no_locations)
   local ctags_kinds = sense.ctags_kinds
   local completions = sense.completions
   local locations = sense.locations
@@ -752,7 +754,7 @@ function M.load_ctags(sense, tag_file, nolocations)
             local t = completions[class][kind]
             t[#t + 1] = tag_name..(kind == M.FIELD and '?1' or '?2')
             -- Update locations.
-            if not nolocations then
+            if not no_locations then
               if not locations[k] then locations[k] = {} end
               locations[k][class..'#'..tag_name] = {file_name, ex_cmd}
             end
@@ -784,7 +786,7 @@ function M.load_ctags(sense, tag_file, nolocations)
         local t = completions[''].fields
         t[#t + 1] = tag_name..'?1'
         -- Update locations.
-        if not nolocations then
+        if not no_locations then
           if not locations[k] then locations[k] = {} end
           locations[k][tag_name] = {file_name, ex_cmd}
         end
diff --git a/modules/textadept/command_entry.lua b/modules/textadept/command_entry.lua
index ddd78c02..224109c0 100644
--- a/modules/textadept/command_entry.lua
+++ b/modules/textadept/command_entry.lua
@@ -56,7 +56,7 @@ end
 
 ---
 -- Exits the current key mode, closes the command entry, and calls function *f*
--- (if given) with the command entry text as an argument.
+-- (if given) with the command entry's text as an argument.
 -- This is useful for binding keys to exit a command entry mode and perform an
 -- action with the entered text.
 -- @param f Optional function to call. It should accept the command entry text
@@ -91,9 +91,10 @@ local env = setmetatable({}, {
 })
 
 ---
--- Executes string *code* as Lua code subject to an "abbreviated" environment
--- where the contents of the `buffer`, `view`, and `ui` tables are also
--- considered as global functions and fields.
+-- Executes string *code* as Lua code that is subject to an "abbreviated"
+-- environment.
+-- In this environment, the contents of the `buffer`, `view`, and `ui` tables
+-- are also considered as global functions and fields.
 -- Prints the results of '=' expressions like in the Lua prompt.
 -- @param code The Lua code to execute.
 -- @name execute_lua
diff --git a/modules/textadept/editing.lua b/modules/textadept/editing.lua
index 8539f3f7..e110faba 100644
--- a/modules/textadept/editing.lua
+++ b/modules/textadept/editing.lua
@@ -17,7 +17,7 @@ local M = {}
 --   Matching braces are defined in the [`braces`](#braces) table.
 -- @field TYPEOVER_CHARS (bool)
 --   Move over closing brace and quote characters under the caret when typing
---   them instead of inserting them.
+--   them.
 --   The default value is `true`.
 --   Typeover characters are defined in the [`typeover_chars`](#typeover_chars)
 --   table.
@@ -55,7 +55,7 @@ M.comment_string = {actionscript='//',ada='--',antlr='//',adpl='!',ansi_c='/*|*/
 -- Map of auto-paired characters like parentheses, brackets, braces, and quotes,
 -- with language-specific auto-paired character maps assigned to a lexer name
 -- key.
--- The ASCII values of opening characters are assigned to strings containing
+-- The ASCII values of opening characters are assigned to strings that contain
 -- complement characters. The default auto-paired characters are "()", "[]",
 -- "{}", "''", and """".
 -- @class table
@@ -202,9 +202,10 @@ function M.match_brace(select)
 end
 
 ---
--- Displays an autocompletion list, built from the set of words in string
--- *words* and existing words in the buffer, for the word behind the caret,
--- returning `true` if completions were found.
+-- Displays an autocompletion list for the word behind the caret, returning
+-- `true` if completions were found.
+-- The displayed list is built from existing words in the buffer and the set of
+-- words in string *words*.
 -- @param words Optional list of words considered to be in the buffer,
 --   even if they are not. Words may contain [registered images][].
 --
@@ -306,7 +307,7 @@ end
 
 ---
 -- Moves the caret to the beginning of line number *line* or the user-specified
--- line, ensuring the line is visible.
+-- line, ensuring *line* is visible.
 -- @param line Optional line number to go to. If `nil`, the user is prompted for
 --   one.
 -- @name goto_line
@@ -372,8 +373,9 @@ function M.enclose(left, right)
 end
 
 ---
--- Selects the text between strings *left* and *right* containing the caret or,
--- if already selected, toggles between selecting *left* and *right* too.
+-- Selects the text between strings *left* and *right* that enclose the caret.
+-- If that range is already selected, toggles between selecting *left* and
+-- *right* as well.
 -- @param left The left part of the enclosure.
 -- @param right The right part of the enclosure.
 -- @name select_enclosed
@@ -428,7 +430,8 @@ function M.select_paragraph()
 end
 
 ---
--- Selects all text with the current level of indentation.
+-- Selects the surrounding block of text whose lines' indentation levels are
+-- greater than or equal to the current line's level.
 -- If a text block is selected and the lines immediately above and below it are
 -- one indentation level lower, adds those lines to the selection.
 -- @name select_indented_block
@@ -450,7 +453,7 @@ function M.select_indented_block()
 end
 
 ---
--- Converts indentation between tabs and spaces based on `buffer.use_tabs`.
+-- Converts indentation between tabs and spaces according to `buffer.use_tabs`.
 -- If `buffer.use_tabs` is `true`, `buffer.tab_width` indenting spaces are
 -- converted to tabs. Otherwise, all indenting tabs are converted to
 -- `buffer.tab_width` spaces.
@@ -517,10 +520,10 @@ end
 -- standard output (stdout).
 -- Standard input is as follows:
 --
--- 1. If text is selected and spans multiple lines, all text on the lines
--- containing the selection is passed as stdin. However, if the end of the
--- selection is at the beginning of a line, only the line ending delimiters from
--- the previous line are included. The rest of the line is excluded.
+-- 1. If text is selected and spans multiple lines, all text on the lines that
+-- have text selected is passed as stdin. However, if the end of the selection
+-- is at the beginning of a line, only the line ending delimiters from the
+-- previous line are included. The rest of the line is excluded.
 -- 2. If text is selected and spans a single line, only the selected text is
 -- used.
 -- 3. If no text is selected, the entire buffer is used.
diff --git a/modules/textadept/file_types.lua b/modules/textadept/file_types.lua
index de79a079..02dd3c63 100644
--- a/modules/textadept/file_types.lua
+++ b/modules/textadept/file_types.lua
@@ -18,8 +18,7 @@ module('textadept.file_types')]]
 events.LEXER_LOADED = 'lexer_loaded'
 
 ---
--- Map of file extensions (excluding the leading '.') to their associated
--- lexer names.
+-- Map of file extensions to their associated lexer names.
 -- If the file type is not recognized by shebang words or first-line patterns,
 -- each file extension is matched against the file's extension.
 -- @class table
diff --git a/modules/textadept/find.lua b/modules/textadept/find.lua
index b6e471d6..57f87553 100644
--- a/modules/textadept/find.lua
+++ b/modules/textadept/find.lua
@@ -6,20 +6,21 @@ local M = ui.find
 ---
 -- Textadept's Find & Replace pane.
 -- @field find_entry_text (string)
---   The text in the find entry.
+--   The text in the "Find" entry.
 -- @field replace_entry_text (string)
---   The text in the replace entry.
+--   The text in the "Replace" entry.
 -- @field match_case (bool)
---   Match the search text case sensitively.
+--   Match search text case sensitively.
 --   The default value is `false`.
 -- @field whole_word (bool)
---   Match the search text surrounded by non-word characters in searches.
+--   Match search text only when it is surrounded by non-word characters in
+--   searches.
 --   The default value is `false`.
 -- @field lua (bool)
---   Interpret the search text as a Lua pattern.
+--   Interpret search text as a Lua pattern.
 --   The default value is `false`.
 -- @field in_files (bool)
---   Find the search text in a list of files.
+--   Find search text in a list of files.
 --   The default value is `false`.
 -- @field find_label_text (string, Write-only)
 --   The text of the "Find" label.
@@ -52,9 +53,9 @@ local M = ui.find
 --   The text of the "In files" label.
 --   This is primarily used for localization.
 -- @field _G.events.FIND_WRAPPED (string)
---   Emitted when a text search wraps, either from bottom to top when searching
---   for a next occurrence, or from top to bottom when searching for a previous
---   occurrence.
+--   Emitted when a text search wraps, either from bottom to top (when searching
+--   for a next occurrence), or from top to bottom (when searching for a
+--   previous occurrence).
 --   This is useful for implementing a more visual or audible notice when a
 --   search wraps in addition to the statusbar message.
 module('ui.find')]]
@@ -187,11 +188,11 @@ local function find_incremental(text, next, anchor)
 end
 
 ---
--- Begins an incremental search using the command entry if *text* is `nil`;
--- otherwise continues an incremental search by searching for the next or
--- previous instance of string *text* depending on boolean *next*.
+-- Begins an incremental search using the command entry if *text* is `nil`.
+-- Otherwise, continues an incremental search by searching for the next or
+-- previous instance of string *text*, depending on boolean *next*.
 -- *anchor* indicates whether or not to search for *text* starting from the
--- caret position instead of the position where the incremental search began at.
+-- 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).
@@ -210,7 +211,8 @@ end
 
 ---
 -- Searches directory *dir* or the user-specified directory for files that match
--- search text and options and prints the results to a "Files Found" buffer.
+-- search text and search options, and prints the results to a buffer titled
+-- "Files Found".
 -- 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.
@@ -330,8 +332,8 @@ events.connect(events.REPLACE_ALL, replace_all)
 local function is_ff_buf(buf) return buf._type == _L['[Files Found Buffer]'] end
 ---
 -- Jumps to the source of the find in files search result on line number *line*
--- in the "Files Found" buffer or, if *line* is `nil`, the next or previous
--- search result depending on boolean *next*.
+-- in the buffer titled "Files Found" or, if *line* is `nil`, jumps to the next
+-- or previous search result, depending on boolean *next*.
 -- @param line The line number in the files found buffer that contains the
 --   search result to go to.
 -- @param next Optional flag indicating whether to go to the next search result
diff --git a/modules/textadept/run.lua b/modules/textadept/run.lua
index f796808f..9600a5d5 100644
--- a/modules/textadept/run.lua
+++ b/modules/textadept/run.lua
@@ -14,24 +14,24 @@ local M = {}
 -- @field MARK_ERROR (number)
 --   The run or compile error marker number.
 -- @field cwd (string, Read-only)
---   The most recently executed compile or run command's working directory.
+--   The most recently executed compile or run shell command's working directory.
 --   It is used for going to error messages with relative file paths.
 -- @field _G.events.COMPILE_OUTPUT (string)
---   Emitted after executing a language's compile command.
+--   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`.
 --   Arguments:
 --
 --   * `lexer`: The language's lexer name.
---   * `output`: The command's string output.
+--   * `output`: A line of string output from the command.
 -- @field _G.events.RUN_OUTPUT (string)
---   Emitted after executing a language's run command.
+--   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`.
 --   Arguments:
 --
 --   * `lexer`: The language's lexer name.
---   * `output`: The command's string output.
+--   * `output`: A line of string output from the command.
 module('textadept.run')]]
 
 M.MARK_WARNING = _SCINTILLA.next_marker_number()
@@ -42,7 +42,7 @@ events.COMPILE_OUTPUT, events.RUN_OUTPUT = 'compile_output', 'run_output'
 
 local preferred_view
 
--- Executes a compile or run command.
+-- Executes a compile or run shell command.
 -- Emits a `COMPILE_OUTPUT` or `RUN_OUTPUT` event based on the `compiling` flag.
 -- @param commands Either `compile_commands` or `run_commands`.
 -- @param compiling Flag indicating whether or not the command is a compiler
@@ -109,7 +109,7 @@ local function get_error(message)
   return nil
 end
 
--- Prints the output from a run or compile command.
+-- Prints the output from a run or compile shell command.
 -- If the output is a recognized warning or error message, mark it.
 -- @param lexer The current lexer.
 -- @param output The output to print.
@@ -123,22 +123,21 @@ local function print_output(lexer, output)
 end
 
 ---
--- Map of file extensions (excluding the leading '.') or lexer names to their
--- associated "compile" shell command line strings or functions returning such
--- strings.
+-- Map of file extensions or lexer names to their associated "compile" shell
+-- command line strings or functions returning such strings.
 -- Command line strings may have the following macros:
 --
---   + `%(filepath)`: The current file's full path.
---   + `%d` or `%(filedir)`: The current file's directory path.
 --   + `%f` or `%(filename)`: The file's name, including its extension.
 --   + `%e` or `%(filename_noext)`: The file's name, excluding its extension.
+--   + `%d` or `%(filedir)`: The current file's directory path.
+--   + `%(filepath)`: The current file's full path.
 -- @class table
 -- @name compile_commands
 M.compile_commands = {actionscript='mxmlc "%f"',ada='gnatmake "%f"',ansi_c='gcc -o "%e" "%f"',antlr='antlr4 "%f"',g='antlr3 "%f"',applescript='osacompile "%f" -o "%e.scpt"',asm='nasm "%f" && ld "%e.o" -o "%e"',boo='booc "%f"',caml='ocamlc -o "%e" "%f"',csharp=WIN32 and 'csc "%f"' or 'mcs "%f"',cpp='g++ -o "%e" "%f"',coffeescript='coffee -c "%f"',context='context --nonstopmode "%f"',cuda=WIN32 and 'nvcc -o "%e.exe" "%f"' or 'nvcc -o "%e" "%f"',dmd='dmd "%f"',dot='dot -Tps "%f" -o "%e.ps"',eiffel='se c "%f"',erlang='erl -compile "%e"',fsharp=WIN32 and 'fsc.exe "%f"' or 'mono fsc.exe "%f"',fortran='gfortran -o "%e" "%f"',gap='gac -o "%e" "%f"',go='go build "%f"',groovy='groovyc "%f"',haskell=WIN32 and 'ghc -o "%e.exe" "%f"' or 'ghc -o "%e" "%f"',inform=function() return 'inform -c "'..buffer.filename:match('^(.+%.inform[/\\])Source')..'"' end,java='javac "%f"',ltx='pdflatex -file-line-error -halt-on-error "%f"',less='lessc "%f" "%e.css"',lilypond='lilypond "%f"',lisp='clisp -c "%f"',litcoffee='coffee -c "%f"',lua='luac -o "%e.luac" "%f"',markdown='markdown "%f" > "%e.html"',nemerle='ncc "%f" -out:"%e.exe"',nimrod='nimrod c "%f"',nsis='MakeNSIS "%f"',objective_c='gcc -o "%e" "%f"',pascal='fpc "%f"',perl='perl -c "%f"',php='php -l "%f"',prolog='gplc --no-top-level "%f"',python='python -m py_compile "%f"',ruby='ruby -c "%f"',sass='sass "%f" "%e.css"',scala='scalac "%f"',tex='pdflatex -file-line-error -halt-on-error "%f"',vala='valac "%f"',vb=WIN32 and 'vbc "%f"' or 'vbnc "%f"',}
 
 ---
 -- Compiles the current file based on its extension or language, using the
--- command from the `compile_commands` table.
+-- shell command from the `compile_commands` table.
 -- Emits a `COMPILE_OUTPUT` event.
 -- @see compile_commands
 -- @see _G.events
@@ -147,22 +146,21 @@ function M.compile() command(M.compile_commands, true) end
 events.connect(events.COMPILE_OUTPUT, print_output)
 
 ---
--- Map of file extensions (excluding the leading '.') or lexer names to their
--- associated "run" shell command line strings or functions returning such
--- strings.
+-- Map of file extensions or lexer names to their associated "run" shell command
+-- line strings or functions returning such strings.
 -- Command line strings may have the following macros:
 --
---   + `%(filepath)`: The full path of the current file.
---   + `%d` or `%(filedir)`: The current file's directory path.
 --   + `%f` or `%(filename)`: The file's name, including its extension.
 --   + `%e` or `%(filename_noext)`: The file's name, excluding its extension.
+--   + `%d` or `%(filedir)`: The current file's directory path.
+--   + `%(filepath)`: The full path of the current file.
 -- @class table
 -- @name run_commands
 M.run_commands = {actionscript=WIN32 and 'start "" "%e.swf"' or OSX and 'open "file://%e.swf"' or 'xdg-open "%e.swf"',ada=WIN32 and '"%e"' or './"%e"',ansi_c=WIN32 and '"%e"' or './"%e"',applescript='osascript "%f"',asm='./"%e"',awk='awk -f "%f"',batch='"%f"',boo='booi "%f"',caml='ocamlrun "%e"',csharp=WIN32 and '"%e"' or 'mono "%e.exe"',cpp=WIN32 and '"%e"' or './"%e"',chuck='chuck "%f"',cmake='cmake -P "%f"',coffeescript='coffee "%f"',context=WIN32 and 'start "" "%e.pdf"' or OSX and 'open "%e.pdf"' or 'xdg-open "%e.pdf"',cuda=WIN32 and '"%e"' or './"%e"',dmd=WIN32 and '"%e"' or './"%e"',eiffel="./a.out",fsharp=WIN32 and '"%e"' or 'mono "%e.exe"',forth='gforth "%f" -e bye',fortran=WIN32 and '"%e"' or './"%e"',gnuplot='gnuplot "%f"',go='go run "%f"',groovy='groovy "%f"',haskell=WIN32 and '"%e"' or './"%e"',hypertext=WIN32 and 'start "" "%f"' or OSX and 'open "file://%f"' or 'xdg-open "%f"',idl='idl -batch "%f"',Io='io "%f"',java='java "%e"',javascript='node "%f"',ltx=WIN32 and 'start "" "%e.pdf"' or OSX and 'open "%e.pdf"' or 'xdg-open "%e.pdf"',less='lessc --no-color "%f"',lilypond=WIN32 and 'start "" "%e.pdf"' or OSX and 'open "%e.pdf"' or 'xdg-open "%e.pdf"',lisp='clisp "%f"',litcoffee='coffee "%f"',lua='lua -e "io.stdout:setvbuf(\'no\')" "%f"',makefile=WIN32 and 'nmake -f "%f"' or 'make -f "%f"',markdown='markdown "%f"',nemerle=WIN32 and '"%e"' or 'mono "%e.exe"',nimrod=WIN32 and '"%e"' or './"%e"',objective_c=WIN32 and '"%e"' or './"%e"',pascal=WIN32 and '"%e"' or './"%e"',perl='perl "%f"',php='php "%f"',pike='pike "%f"',pkgbuild='makepkg -p "%f"',prolog=WIN32 and '"%e"' or './"%e"',python='python "%f"',rstats=WIN32 and 'Rterm -f "%f"' or 'R -f "%f"',rebol='REBOL "%f"',rexx=WIN32 and 'rexx "%e"' or 'regina "%e"',ruby='ruby "%f"',sass='sass "%f"',scala='scala "%e"',bash='bash "%f"',csh='tcsh "%f"',sh='sh "%f"',zsh='zsh "%f"',smalltalk='gst "%f"',tcl='tclsh "%f"',tex=WIN32 and 'start "" "%e.pdf"' or OSX and 'open "%e.pdf"' or 'xdg-open "%e.pdf"',vala=WIN32 and '"%e"' or './"%e"',vb=WIN32 and '"%e"' or 'mono "%e.exe"',}
 
 ---
--- Runs the current file based on its extension or language, using the command
--- from the `run_commands` table.
+-- Runs the current file based on its extension or language, using the shell
+-- command from the `run_commands` table.
 -- Emits a `RUN_OUTPUT` event.
 -- @see run_commands
 -- @see _G.events
@@ -187,9 +185,10 @@ M.error_patterns = {--[[ANTLR]]'^error%(%d+%): (.-):(%d+):%d+: (.+)$','^warning%
 local function is_msg_buf(buf) return buf._type == _L['[Message Buffer]'] end
 ---
 -- Jumps to the source of the recognized compile/run warning or error on line
--- number *line* in the message buffer or, if *line* is `nil`, the next or
--- previous warning or error depending on boolean *next*.
--- Displays an annotation with the warning or error message if possible.
+-- number *line* in the message buffer.
+-- If *line* is `nil`, jumps to the next or previous warning or error, depending
+-- on boolean *next*. Displays an annotation with the warning or error message
+-- if possible.
 -- @param line The line number in the message buffer that contains the
 --   compile/run warning/error to go to.
 -- @param next Optional flag indicating whether to go to the next recognized
diff --git a/modules/textadept/session.lua b/modules/textadept/session.lua
index 1f314092..0e53137f 100644
--- a/modules/textadept/session.lua
+++ b/modules/textadept/session.lua
@@ -29,8 +29,8 @@ M.SAVE_ON_QUIT = true
 M.MAX_RECENT_FILES = 10
 
 ---
--- Loads session file *filename* or the user-selected file, returning `true` if
--- the session file was opened and read.
+-- 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.
 -- @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 4c3ccc33..5d4b26d2 100644
--- a/modules/textadept/snippets.lua
+++ b/modules/textadept/snippets.lua
@@ -124,9 +124,9 @@ end
 
 ---
 -- Inserts snippet text *text* or the snippet assigned to the trigger word
--- behind the caret or, if a snippet is active, goes to the active snippet's
--- next placeholder.
--- Returns `false` if no action was taken.
+-- behind the caret.
+-- Otherwise, if a snippet is active, goes to the active snippet's next
+-- placeholder. Returns `false` if no action was taken.
 -- @param text Optional snippet text to insert. If `nil`, attempts to insert a
 --   new snippet based on the trigger, the word behind caret, and the current
 --   lexer.
@@ -169,7 +169,7 @@ function M._cancel_current()
 end
 
 ---
--- Prompts the user to select a snippet to insert from a list of global and
+-- Prompts the user to select a snippet to be inserted from a list of global and
 -- language-specific snippets.
 -- @name _select
 function M._select()